@vimazing/vim-sudoku

Lightweight, typed React hooks for building interactive sudoku games with VIM-style modal editing.

Part of the VIMazing project.

---

Contents

• Features
• Installation
• Quick Start
• API Reference
• Game States
• VIM Controls
• Scoring System
• Game Over Conditions
• Hint System
• Configuration
• Example App
• License

---

Features

• 🎮 VIM modal editing – Navigate in normal mode, edit cells with i/r/c commands
• ⌨️ Full VIM motions – hjkl, counts (5j), anchors (^/$), gg/G, repeat (.)
• 🎯 Smart cell protection – Pre-filled clues locked with visual feedback
• 💡 Hint system – Get hints for incorrect cells or empty cells (Shift+H)
• ⏱️ Configurable limits – Time limits and hint penalties trigger game-over
• 📊 Comprehensive scoring – Time + keystrokes + hints with difficulty multipliers
• 🎨 Tokyo Night theme – Beautiful dark theme with proper 3x3 box separators
• 📦 Full TypeScript – Complete type safety with generated declarations
• 🪝 Composable architecture – Clean separation: board, cursor, score, game status
• 🌐 Platform hooks – Optional integration for analytics and custom bindings

---

Installation

npm install @vimazing/vim-sudoku

Or with bun:

bun add @vimazing/vim-sudoku

---

Quick Start

import { useGame } from "@vimazing/vim-sudoku";
import "@vimazing/vim-sudoku/game.css";

export function SudokuGame() {
  const gameManager = useGame({ difficulty: 'easy' });
  const { containerRef, gameStatus, scoreManager, startGame } = gameManager;

  return (
    <div>
      <h1>VIMazing Sudoku</h1>
      
      {gameStatus === 'waiting' && (
        <button onClick={startGame}>Start Game</button>
      )}
      
      <div ref={containerRef} />
      
      {gameStatus === 'game-won' && (
        <div>
          <h2>You Won!</h2>
          <p>Score: {scoreManager.finalScore} / 1000</p>
          <p>Time: {Math.floor(scoreManager.timeValue / 1000)}s</p>
        </div>
      )}
    </div>
  );
}

Note: You must manually import game.css for styling.

---

API Reference

useGame(options?, platformHook?)

Main orchestrator hook that composes all game functionality.

Options

type GameOptions = {
  difficulty?: 'easy' | 'medium' | 'hard';  // Default: 'easy'
  timeLimit?: number;                        // In seconds, default: 600 (10 min)
  removedCells?: number;                     // Override difficulty default
};

Difficulty Defaults:

• easy: 25 cells removed (~56 givens)
• medium: 40 cells removed (~41 givens)
• hard: 50 cells removed (~31 givens)

Examples:

// Default configuration
useGame()

// Hard difficulty with defaults
useGame({ difficulty: 'hard' })

// Custom puzzle size
useGame({ removedCells: 30 })

// Custom everything
useGame({ 
  difficulty: 'hard',
  removedCells: 45,
  timeLimit: 480  // 8 minutes
})

Returns: GameManager

type GameManager = {
  // DOM Reference
  containerRef: RefObject<HTMLDivElement | null>;
  
  // Rendering
  renderBoard: () => void;
  
  // Game Status
  gameStatus: GameStatus;
  setGameStatus: (status: GameStatus) => void;
  startGame: () => void;
  togglePause: (pause?: boolean) => void;
  quitGame: () => void;
  
  // Cursor
  cursor: CursorManager;
  
  // Scoring
  scoreManager: ScoreManager;
  
  // Input Tracking
  keyLog: KeyLogEntry[];
  clearKeyLog: () => void;
  getKeyLog: () => KeyLogEntry[];
};

CursorManager

type CursorManager = {
  position: () => Coord;              // Current { row, col }
  mode: () => CursorMode;             // 'normal' | 'edit'
  moveLeft: (count?: number) => void;
  moveRight: (count?: number) => void;
  moveUp: (count?: number) => void;
  moveDown: (count?: number) => void;
  moveToStart: () => void;            // ^ or 0
  moveToEnd: () => void;              // $
  moveToTop: () => void;              // gg
  moveToBottom: () => void;           // G
  repeatLastMotion: () => void;       // .
};

ScoreManager

type ScoreManager = {
  timeValue: number;                  // Milliseconds elapsed
  startTimer: () => void;
  stopTimer: () => void;
  resetTimer: () => void;
  totalKeystrokes: number;            // All keys pressed
  hintsUsed: number;                  // Number of hints requested
  finalScore: number | null;          // 0-1000, null until game-won
  gameOverReason: string | null;      // "Time's up!" or "Too many hints!"
};

---

Game States

The game follows a strict state machine:

waiting → started → game-won
              ↓
           game-over
              
All states → [quit] → waiting
started ↔ paused

State Descriptions

State	Description	Triggers
waiting	Initial state, awaiting start	Default on load
started	Game in progress	Press Space or call startGame()
paused	Game temporarily paused	Press P or call togglePause()
game-won	Puzzle completed successfully	All cells filled correctly
game-over	Failed to complete in time/hints	Time limit or hint limit exceeded

---

VIM Controls

Normal Mode (Default)

Movement

Key	Action	Example
h	Move left	h moves 1 left
j	Move down	j moves 1 down
k	Move up	k moves 1 up
l	Move right	l moves 1 right
<count><motion>	Move with count	5j moves 5 down, 3l moves 3 right
0 or ^	Jump to row start	Move to column 0
$	Jump to row end	Move to column 8
gg	Jump to board top	Move to row 0
G	Jump to board bottom	Move to row 8
.	Repeat last motion	Repeats with same count

Edit Commands

Key	Action	Valid On	Mode
i	Insert digit	✅ Empty cells only	Multi-edit: type digits until Esc
r	Replace digit	✅ User-entered cells only	Single-edit: auto-exit after 1 digit
c	Change digit	✅ User-entered cells only	Single-edit: auto-exit after 1 digit
x	Delete digit	✅ User-entered cells only	Instant
d	Delete digit	✅ User-entered cells only	Instant
Delete	Delete digit	✅ User-entered cells only	Instant
Backspace	Invalid move	❌ All cells	Red flash (use in edit mode)

Hints & Game Control

Key	Action	Notes
Shift+H	Request hint	Penalty: 25/50/100 pts based on difficulty
q	Quit game	Return to waiting state
p	Pause/unpause	Toggle pause state
Space	Start new game	Only in waiting/game-over state

Edit Mode (i/r/c to enter)

Key	Action
1-9	Enter digit in current cell
Backspace	Clear current cell (stay in edit mode)
Escape	Exit to normal mode

---

Cell State Rules

Understanding cell states is crucial for VIM-style editing:

Cell State	i Insert	r/c Replace	x/d/Delete	Visual Class
Empty	✅ Enter multi-edit	🔴 Flash (use i)	🔴 Flash (nothing to delete)	None
User-entered	🔴 Flash (use r/c)	✅ Enter single-edit	✅ Delete instantly	.user-entered
Given	🔴 Flash (locked)	🔴 Flash (locked)	🔴 Flash (locked)	.given

Visual Feedback

• 🔵 Blue outline – Normal mode cursor (.active)
• 🟡 Yellow pulsing glow – Edit mode cursor (.editing)
• 🔴 Red flash – Invalid move (.invalid-move - 500ms)
• 🔴 Red flash + background – Hint: incorrect cell (.hint-flash-error - 1000ms)
• 🟢 Green flash + background – Hint: correct digit shown (.hint-flash-correct - 1000ms)

---

Scoring System

Formula

Base Score = 1000 - (time penalty) - (keystroke penalty) - (hint penalty)
Final Score = min(1000, max(0, round(Base Score × difficulty multiplier)))

Penalties

Time Penalty: seconds / 10

• 10 seconds = -1 point
• 60 seconds = -6 points
• 300 seconds = -30 points

Keystroke Penalty: totalKeystrokes / 2

• 2 keystrokes = -1 point
• 50 keystrokes = -25 points
• 200 keystrokes = -100 points

Hint Penalty: hintsUsed × penalty

• Easy: 25 points per hint
• Medium: 50 points per hint
• Hard: 100 points per hint

Difficulty Multipliers

• Easy: 1.0x (no bonus)
• Medium: 1.5x (can exceed 1000 base, capped at 1000)
• Hard: 2.0x (can exceed 1000 base, capped at 1000)

Example Scores

Easy Mode (25 cells, 1.0x):

30 seconds, 50 keys, 0 hints:
= 1000 - 3 - 25 - 0 = 972 × 1.0 = 972 / 1000

Hard Mode (50 cells, 2.0x):

120 seconds, 150 keys, 2 hints:
= 1000 - 12 - 75 - 200 = 713 × 2.0 = 1000 / 1000 (capped)

---

Game Over Conditions

Time Limit

• Default: 600 seconds (10 minutes) for all difficulties
• Configurable: Set via GameOptions.timeLimit
• Trigger: When timeValue >= timeLimit × 1000
• Message: "Time's up!"

Hint Limit

• Threshold: 500 points total hint penalty
• Easy: 20 hints max (20 × 25 = 500)
• Medium: 10 hints max (10 × 50 = 500)
• Hard: 5 hints max (5 × 100 = 500)
• Trigger: When hintsUsed × HINT_PENALTY[difficulty] >= 500
• Message: "Too many hints!"

Both conditions checked continuously during gameplay. Timer stops on game-over.

---

Hint System

Press Shift+H in normal mode to request a hint.

Hint Priority

Priority 1: Show Incorrect Cell (Red Flash)

• Finds all user-entered cells with wrong values
• Selects one randomly
• Flashes red with background for 1 second
• Does NOT reveal correct digit (player must figure it out)

Priority 2: Show Correct Digit (Green Flash)

• If no incorrect cells exist
• Finds all empty cells
• Selects one randomly
• Shows correct digit with green flash for 1 second
• Digit disappears after flash (player must remember and enter it)

Hint Penalties

Hints subtract directly from base score before multiplier:

• Easy: -25 points per hint
• Medium: -50 points per hint
• Hard: -100 points per hint

After 500 points of penalties, game-over triggers.

---

Configuration

Recommended Configurations

Beginner Practice:

useGame({ 
  difficulty: 'easy',
  removedCells: 15,
  timeLimit: 900  // 15 minutes
})

Standard Easy:

useGame({ difficulty: 'easy' })
// 25 cells, 10 minutes, 1.0x multiplier

Standard Medium:

useGame({ difficulty: 'medium' })
// 40 cells, 10 minutes, 1.5x multiplier

Standard Hard:

useGame({ difficulty: 'hard' })
// 50 cells, 10 minutes, 2.0x multiplier

Speed Challenge:

useGame({
  difficulty: 'medium',
  timeLimit: 300  // 5 minutes
})

Custom Difficulty:

useGame({
  difficulty: 'easy',      // Easy scoring (1.0x, 25pt hints)
  removedCells: 60,        // But very hard puzzle
  timeLimit: 1200          // Generous time (20 min)
})

---

Game Instructions Export

The package exports a structured gameInfo object containing complete game documentation:

import { gameInfo } from '@vimazing/vim-sudoku';

// Access structured instructions
console.log(gameInfo.name);           // "VIM Sudoku"
console.log(gameInfo.controls);       // Navigation, editing, deletion, hints, game
console.log(gameInfo.rules);          // Cell types, modes, visual feedback
console.log(gameInfo.scoring);        // Formula, penalties, multipliers, examples
console.log(gameInfo.gameOver);       // Time and hint limit conditions
console.log(gameInfo.hints);          // How the hint system works
console.log(gameInfo.objective);      // Win condition

Use cases:

• Render in-game help screens
• Generate tutorials
• Display control reference
• Show scoring breakdown
• Explain game mechanics

All data is fully typed with the GameInfo type for type safety.

---

Example App

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

cd example
npm install
npm run dev

The example shows:

• Difficulty selection (Easy/Medium/Hard)
• Live scoreboard (Time, Keystrokes, Hints)
• Game status messages
• Final score display on win
• All vim controls working

---

Platform Hook

Optional callback for platform integration:

function myPlatformHook(gameManager: GameManager) {
  // Track analytics
  console.log('Game initialized');
  
  // Add custom key handlers
  window.addEventListener('keydown', (e) => {
    if (e.key === 'F1') {
      console.log('Help requested');
    }
  });
  
  // Monitor game events
  const interval = setInterval(() => {
    if (gameManager.gameStatus === 'game-won') {
      console.log('Victory!', gameManager.scoreManager.finalScore);
      clearInterval(interval);
    }
  }, 100);
}

const gameManager = useGame({ difficulty: 'easy' }, myPlatformHook);

---

License

MIT © André Padez