vim-maze/IMPLEMENTATION_INSTRUCTIONS.md

Implementation Instructions for New Games

Goal

Create a comprehensive UNIFIED_API.md that documents the current architecture in src/ (not src_old/), replacing the old UNIFIED_API_OLD.md. This will serve as the blueprint for porting existing games and creating new games using the new unified architecture.

Files to Reference

Read These First

1. AGENTS.md - Contains all development guidelines, code conventions, naming patterns, hook structure, and architectural principles
2. UNIFIED_API_OLD.md - The old API documentation (for reference on what we're replacing)

Reference the New Codebase

• src/useGame.ts - Main orchestrator hook, entry point
• src/useBoard/ - Board/level management
  • useBoard.ts
  • MazeGenerator.ts
  • MazeRenderer.ts
  • useMazeNavigation.ts
• src/useCursor/ - Player/actor management
  • useCursor.ts
  • useHero.ts
  • useHeroRender.ts
  • useVimMotions.ts
  • useGameKeys.ts
  • useAnimation.ts
• src/useScore/ - Scoring system
  • useScore.ts
  • useScorePaths.ts
  • useScoreTime.ts
  • useTimer.ts
• src/useGameStatus.ts - Game state management
• src/types.ts - All shared TypeScript types

Example Implementation

• example/src/App.tsx - Shows how to use the new unified API

What the New UNIFIED_API.md Should Cover

1. Architecture Overview

• Single entry point: useGame(options?, platformHook?)
• Three core hooks composition pattern
• Scoring system integration
• Type-safe throughout

2. Core Hooks Reference

For each hook, document:

• Purpose - What it does
• Parameters - What it accepts with types
• Return Type - What it returns with type definition
• Dependencies - What other hooks it depends on
• Example Usage - Real code example

Core hooks to document:

• useGame() - Main orchestrator
• useBoard() - Board/maze management
• useCursor() - Player movement and controls
• useScore() - Scoring system
• useGameStatus() - Game state
• Supporting hooks in each module

3. Type System Documentation

• Document all major types from src/types.ts:
  • GameManager
  • BoardManager
  • CursorManager
  • ScoreManager
  • GameStatusManager
  • Coord, MazeCell, etc.
• Show relationships between types
• Include examples of how types flow through the system

4. File Structure & Organization

• Show the complete src/ directory structure
• Explain the purpose of each module
• Show public exports from index.ts files

5. Naming Conventions & Patterns

• Hook naming: use[FeatureName]()
• Type naming: PascalCase with descriptive names
• Function naming: camelCase with clear verbs
• Pattern examples from actual code

6. Key Implementation Details

• How board generation and rendering works
• How player movement and vim motions are handled
• How scoring is calculated
• How game status transitions work
• Animation system for multi-step movements
• Keyboard input handling and key binding system

7. Integration Points for New Games

• What you need to implement for a new game
• How to customize board generation
• How to customize player movement rules
• How to customize scoring logic
• Platform hook integration (if applicable)

8. Code Examples

• Minimal game setup example
• Complete feature examples (movement, scoring, rendering)
• Type usage examples
• Common patterns and best practices

9. Migration Guide (Optional)

• How to port games from src_old/ structure to new structure
• Common gotchas and solutions
• Before/after code comparisons

Output Requirements

The new UNIFIED_API.md should:

• Be comprehensive but readable
• Use clear sections and subsections
• Include code blocks for all examples
• Show actual types and function signatures from the codebase
• Be focused on developers porting games or creating new ones
• Be maintainable - designed to stay in sync with actual code in src/

Success Criteria

When done, a developer should be able to:

1. Understand the complete architecture without reading source code
2. Know exactly what types and functions are available
3. Understand how hooks compose together
4. Have templates/examples for common tasks
5. Easily port a game from src_old/ to new structure
6. Create a completely new game following this pattern

Notes

• AGENTS.md already contains code conventions and patterns - reference it heavily
• Focus the new doc on WHAT each part does and HOW to use it, not just code style
• Keep the doc well-organized so it's easy to find specific information
• Show how everything connects together (data flow, composition)