135 lines
4.5 KiB
Markdown
135 lines
4.5 KiB
Markdown
# 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)
|