@vimazing/vim-snake

Lightweight, typed React hooks and utilities for building interactive snake games with VIM-inspired controls.

Part of the VIMazing project - GitHub.

Contents

• Features
• Installation
• Quick Start
• Core Hooks
• Utilities
• Example App
• Build & Release
• License
• Acknowledgements

Features

• Drop-in hooks for snake game mechanics, scoring, and key logging.
• Typed API with generated declaration files for editor IntelliSense.
• VIM-style controls (h, j, k, l for direction changes).
• Composable architecture – bring your own rendering and platform-specific bindings.
• Tree-shakeable exports to keep bundles lean.

Installation

Using npm:

npm install @vimazing/vim-snake

Or with bun:

bun add @vimazing/vim-snake

Quick Start

import { useEffect } from "react";
import { useGame } from "@vimazing/vim-snake";
import "@vimazing/vim-snake/game.css";

export function SnakeGame() {
  const { containerRef, gameStatus, score, level } = useGame();

  return (
    <section className="mx-auto w-fit space-y-4">
      <h1 className="text-2xl font-bold">VIMazing Snake</h1>
      <div className="flex gap-4 justify-center">
        <div>Score: {score}</div>
        <div>Level: {level}</div>
      </div>
      <div ref={containerRef} className="relative" />
      {gameStatus === "game-over" && <p>Game Over! Press Space to restart</p>}
    </section>
  );
}

Note: You must manually import the CSS file. The package exports styles but does not auto-import them, giving you control over when and how styles are loaded.

Default Controls

| Key | Action | | ----------- | ------------------- | | Space | Start / Restart | | h / l | Turn left / right | | j / k | Turn down / up | | q | Quit game | | p | Pause / unpause |

Game Options

Use GameOptions to customize the game:

const game = useGame({
  cols: 40,                    // Board width (default: 30)
  rows: 25,                    // Board height (default: 20)
  startingLevel: 5,            // Initial level (default: 1)
  foodsPerLevel: 5,            // Foods to level up (default: 10)
  maxLevel: 20,                // Maximum level (default: 25)
  initialSnakeSize: 5,         // Snake segments at start (default: 3)
  initialFoodCount: 2,         // Food items at start (default: 1)
});

All options are optional with sensible defaults. Call useGame() with no arguments for default settings.

API

useGame Hook

Main hook that orchestrates all game mechanics:

const gameManager = useGame(options?, platformHook?);

Parameters:

• options (optional): GameOptions object for customization
• platformHook (optional): Function to handle platform-specific logic

Returns: GameManager with:

• containerRef – DOM ref for game board rendering
• gameStatus – Current state ('waiting' | 'started' | 'game-over' | 'game-won')
• score – Current game score
• level – Current level (also equals game speed in FPS)
• scoreManager – Tracks time, keystrokes, and final score
• cursor – Snake manager with movement and state
• keyLog – Array of all key presses during game
• Control methods: startGame(), quitGame(), togglePause(), etc.

gameInfo Export

Get complete game documentation for platforms:

import { gameInfo } from "@vimazing/vim-snake";

console.log(gameInfo.name);           // "VIMazing Snake"
console.log(gameInfo.controls);       // Control mappings
console.log(gameInfo.scoring);        // Scoring rules
console.log(gameInfo.configuration);  // All GameOptions

Perfect for building help screens, settings, and platform integrations.

Utilities

Besides the hooks, the library exports:

• types – shared TypeScript types such as GameStatus, Direction, and Position.

import { GameStatus } from "@vimazing/vim-snake";

Example App

A demo application lives under example/ and consumes the package directly.

cd example
bun install
bun run dev

During local development the Vite config aliases @vimazing/vim-snake to the source folder so you can iterate without rebuilding. When publishing, run the build first (see below) so editors consume the generated declarations in dist/.

Build & Release

Build the distributable bundle and type declarations:

bun run build

This writes JavaScript, type definitions, and styles to dist/. The prepublishOnly hook reuses the same command to guarantee fresh artifacts before publishing.

License

MIT © André Padez

Acknowledgements

Classic Snake game reimagined for the VIMazing platform with Vim-style controls.