Add "Grid-System"
parent
1c784e2830
commit
8bd530056c
|
|
@ -0,0 +1,161 @@
|
|||
# Grid System
|
||||
|
||||
The Grid System is McRogueFace's core spatial container for roguelike game maps. It provides tilemap rendering, entity management, FOV (field of view), and pathfinding integration with libtcod.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
**Related Issues:**
|
||||
- [#124](../../issues/124) - Grid Point Animation (Tier 1 - Active)
|
||||
- [#123](../../issues/123) - Grid Subgrid System (Tier 1 - Active)
|
||||
- [#114](../../issues/114) - CellView API (Tier 1 - Active)
|
||||
- [#113](../../issues/113) - Batch Operations for Grid (Tier 1 - Active)
|
||||
- [#64](../../issues/64) - Grid-Entity-GridPointState TCOD Updates
|
||||
- [#50](../../issues/50) - Grid Background Color (Closed - Implemented)
|
||||
|
||||
**Key Files:**
|
||||
- `src/UIGrid.h` / `src/UIGrid.cpp` - Main grid implementation
|
||||
- `src/UIGridPoint.h` - Individual grid cell (visual layer)
|
||||
- `src/UIGridPointState.h` - Per-entity perspective/knowledge
|
||||
- `src/UIEntity.h` / `src/UIEntity.cpp` - Entity system (lives on grid)
|
||||
|
||||
**API Reference:**
|
||||
- See [mcrfpy.Grid](../../docs/api_reference_dynamic.html#Grid) in generated API docs
|
||||
- See [mcrfpy.Entity](../../docs/api_reference_dynamic.html#Entity) in generated API docs
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### Three-Layer Design
|
||||
|
||||
The Grid System uses a three-layer architecture for sophisticated roguelike features:
|
||||
|
||||
1. **Visual Layer** (`UIGridPoint`)
|
||||
- What's displayed: tile sprite, colors, animations
|
||||
- Shared by all viewers
|
||||
- File: `src/UIGridPoint.h`
|
||||
|
||||
2. **World State Layer** (`TCODMap`)
|
||||
- Physical properties: walkable, transparent, cost
|
||||
- Used for pathfinding and FOV calculations
|
||||
- Integration: libtcod via `src/UIGrid.cpp`
|
||||
|
||||
3. **Perspective Layer** (`UIGridPointState`)
|
||||
- Per-entity knowledge: what each entity has seen/explored
|
||||
- Enables fog of war, asymmetric information
|
||||
- File: `src/UIGridPointState.h`
|
||||
|
||||
This architecture follows proven patterns from Caves of Qud, Cogmind, and DCSS.
|
||||
|
||||
### Grid → Entity Relationship
|
||||
|
||||
**Entity Lifecycle:**
|
||||
- Entities live on exactly 0 or 1 grids
|
||||
- `grid.entities.append(entity)` sets `entity.grid = grid`
|
||||
- `grid.entities.remove(entity)` sets `entity.grid = None`
|
||||
- Entity removal handled automatically on grid destruction
|
||||
|
||||
**Spatial Queries:**
|
||||
- Currently: Linear iteration through entity list
|
||||
- Planned: SpatialHash for O(1) lookups (see [#115](../../issues/115))
|
||||
|
||||
## Sub-Pages
|
||||
|
||||
- [[Grid-Rendering-Pipeline]] - How grid renders each frame
|
||||
- [[Grid-TCOD-Integration]] - FOV, pathfinding, walkability
|
||||
- [[Grid-Entity-Lifecycle]] - Entity creation, movement, removal
|
||||
- [[Grid-Performance-Optimization]] - Dirty flags, culling, batch ops
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Creating a Grid
|
||||
|
||||
```python
|
||||
import mcrfpy
|
||||
|
||||
# Create 50x50 grid with 16x16 tile size
|
||||
grid = mcrfpy.Grid(50, 50, 16, 16)
|
||||
grid.texture = mcrfpy.createTexture("tileset.png")
|
||||
grid.pos = (100, 100) # Screen position
|
||||
|
||||
# Add to scene
|
||||
mcrfpy.sceneUI("game").append(grid)
|
||||
```
|
||||
|
||||
**Details:** See `src/UIGrid.cpp::PyInit()` for constructor implementation
|
||||
|
||||
### Setting Tile Properties
|
||||
|
||||
```python
|
||||
# Access individual cell
|
||||
cell = grid.at((x, y))
|
||||
|
||||
# Visual properties
|
||||
cell.tilesprite = 42 # Sprite index in texture
|
||||
cell.color = mcrfpy.Color(255, 255, 255)
|
||||
|
||||
# World properties (TCOD integration)
|
||||
grid.walkable((x, y), True) # Can entities walk here?
|
||||
grid.transparent((x, y), True) # Can see through?
|
||||
```
|
||||
|
||||
**Implementation:** `src/UIGrid.cpp::walkable()`, `src/UIGrid.cpp::transparent()`
|
||||
|
||||
### FOV and Pathfinding
|
||||
|
||||
```python
|
||||
# Compute field of view from entity position
|
||||
grid.compute_fov(entity.x, entity.y, radius=10)
|
||||
|
||||
# A* pathfinding
|
||||
path = entity.path_to(target_x, target_y)
|
||||
```
|
||||
|
||||
**Implementation:**
|
||||
- FOV: `src/UIGrid.cpp::compute_fov()` (TCOD integration)
|
||||
- Pathfinding: `src/UIEntity.cpp::path_to()` (uses TCOD A*)
|
||||
|
||||
## Performance Characteristics
|
||||
|
||||
**Current:**
|
||||
- Grid rendering: O(visible_cells) - renders only viewport
|
||||
- Entity rendering: O(entities) - culls out-of-bounds (see `src/UIGrid.cpp::render()`)
|
||||
- Static grids: Inefficient - redraws unchanged cells every frame
|
||||
|
||||
**Optimizations In Progress:**
|
||||
- [#116](../../issues/116): Dirty flag system - only redraw on changes
|
||||
- [#113](../../issues/113): Batch operations - reduce Python/C++ boundary crossings
|
||||
- [#115](../../issues/115): SpatialHash - O(1) entity spatial queries
|
||||
- [#123](../../issues/123): Subgrid system - divide large grids into chunks
|
||||
|
||||
**Profiling:** Press F3 in-game to see grid render metrics (see [[Performance-and-Profiling]])
|
||||
|
||||
## Design Proposals
|
||||
|
||||
Active architectural evolution:
|
||||
|
||||
- [[Proposal-Next-Gen-Grid-Architecture]] - Subgrid system, tile animation
|
||||
- [[Proposal-Next-Gen-Entity-System]] - Flexible entity content, multi-tile entities
|
||||
|
||||
## Known Issues & Limitations
|
||||
|
||||
**Current Limitations:**
|
||||
- No tile-level animation (planned: [#124](../../issues/124))
|
||||
- Large grids (>200x200) can have rendering overhead
|
||||
- Entity iteration is O(n) for spatial queries
|
||||
|
||||
**Workarounds:**
|
||||
- Keep grids reasonably sized (< 100x100 for best performance)
|
||||
- Use entity culling (automatically enabled in `UIGrid::render()`)
|
||||
- Profile with F3 overlay to identify bottlenecks
|
||||
|
||||
## Related Systems
|
||||
|
||||
- [[UI-Component-Hierarchy]] - Grid inherits from UIDrawable
|
||||
- [[Animation-System]] - Grid properties are animatable (pos, zoom, etc)
|
||||
- [[Performance-and-Profiling]] - Grid rendering instrumented with ScopedTimer
|
||||
- [[Entity-Management]] - Entity use case depends on Grid system
|
||||
|
||||
---
|
||||
|
||||
**See Also:**
|
||||
- Tutorial: [McRogueFace Does The Entire Roguelike Tutorial](../../roguelike_tutorial/)
|
||||
- Build Guide: CLAUDE.md in repository root
|
||||
Loading…
Reference in New Issue