feat: Add tutorial parts 0-6 with documentation

Add working tutorial implementations covering:
- Part 0: Basic setup and character display
- Part 1: Movement and grid interaction
- Part 2: Movement variations (naive, queued, final)
- Part 3: Dungeon generation
- Part 4: Field of View
- Part 5: Entities and interactions
- Part 6: Combat system

Each part includes corresponding README with explanations.
Implementation plan document included for parts 6-8.

Tutorial follows "forward-only" philosophy - each step builds
on previous without requiring refactoring.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
John McCardle 2025-10-23 13:18:45 -04:00
commit a76ebcd05a
10 changed files with 2232 additions and 0 deletions

View file

@ -0,0 +1,82 @@
# Simple TCOD Tutorial Part 2 - The generic Entity, the map, and walls
This is Part 2 of the Simple TCOD Tutorial adapted for McRogueFace. Building on Part 1's foundation, we now introduce proper world representation and collision detection.
## Running the Code
From your tutorial build directory:
```bash
cd simple_tcod_tutorial/build
./mcrogueface scripts/main.py
```
## New Architecture Components
### GameMap Class (`game/game_map.py`)
The GameMap inherits from `mcrfpy.Grid` and adds:
- **Tile Management**: Uses Grid's built-in point system with walkable property
- **Entity Container**: Manages entity lifecycle with `add_entity()` and `remove_entity()`
- **Spatial Queries**: `get_entities_at()`, `get_blocking_entity_at()`, `is_walkable()`
- **Direct Integration**: Leverages Grid's walkable and tilesprite properties
### Tiles System (`game/tiles.py`)
- **Simple Tile Types**: Using NamedTuple for clean tile definitions
- **Tile Types**: Floor (walkable) and Wall (blocks movement)
- **Grid Integration**: Maps directly to Grid point properties
- **Future-Ready**: Includes transparency for FOV system in Part 4
### Entity Placement System
- **Bidirectional References**: Entities know their map, maps track their entities
- **`place()` Method**: Handles all bookkeeping when entities move between maps
- **Lifecycle Management**: Automatic cleanup when entities leave maps
## Key Changes from Part 1
### Engine Updates
- Replaced direct grid management with GameMap
- Engine creates and configures the GameMap
- Player is placed using the new `place()` method
### Movement System
- MovementAction now checks `is_walkable()` before moving
- Collision detection for both walls and blocking entities
- Clean separation between validation and execution
### Visual Changes
- Walls rendered as trees (sprite index 3)
- Border of walls around the map edge
- Floor tiles still use alternating pattern
## Architectural Benefits
### McRogueFace Integration
- **No NumPy Dependency**: Uses Grid's native tile management
- **Direct Walkability**: Grid points have built-in walkable property
- **Unified System**: Visual and logical tile data in one place
### Separation of Concerns
- **GameMap**: Knows about tiles and spatial relationships
- **Engine**: Coordinates high-level game state
- **Entity**: Manages its own lifecycle through `place()`
- **Actions**: Validate their own preconditions
### Extensibility
- Easy to add new tile types
- Simple to implement different map generation
- Ready for FOV, pathfinding, and complex queries
- Entity system scales to items and NPCs
### Type Safety
- TYPE_CHECKING imports prevent circular dependencies
- Proper type hints throughout
- Forward references maintain clean architecture
## What's Next
Part 3 will add:
- Procedural dungeon generation
- Room and corridor creation
- Multiple entities in the world
- Foundation for enemy placement
The architecture established in Part 2 makes these additions straightforward, demonstrating the value of proper design from the beginning.