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