Remove original layers and migrate Grids to entirely user-driven layer objects #150

New Issue

john · 2025-11-29T03:22:00Z

john commented

2025-11-29 03:22:00 +00:00

See #147, #123

We've created an entirely additional arbitrary layer system, which has pros and cons compared to the base layer.

base rendering iterates only over the cells that are visible in the viewport.
cached rendering re-renders an entire layer - but only a single layer - whenever that layer has been marked dirty.

What would harmony look like?

No base layers - Grids only contain what users define. Yes, it's a breaking change; it's the final evolution of https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki/Proposal-Next-Gen-Grid-Entity-System.-
split into subgrids - a ~64x64-ish portion of the grid is what's marked dirty, and re-rendered; not the entire layer.
smart compromise on memory - subgrids are only rendered as required, perhaps as low as 4 to display the visible section. We don't need every subgrid - we just want to be able to do pathing and FOV over the whole grid, and display an arbitrary but reasonable subsection.

See #147, #123 We've created an entirely additional arbitrary layer system, which has pros and cons compared to the base layer. * base rendering iterates only over the cells that are visible in the viewport. * cached rendering re-renders an entire layer - but only a single layer - whenever that layer has been marked dirty. What would harmony look like? * No base layers - Grids only contain what users define. Yes, it's a breaking change; it's the final evolution of https://gamedev.ffwf.net/gitea/john/McRogueFace/wiki/Proposal-Next-Gen-Grid-Entity-System.- * split into subgrids - a `~64x64-ish` portion of the grid is what's marked dirty, and re-rendered; not the entire layer. * smart compromise on memory - subgrids are only rendered as required, perhaps as low as 4 to display the visible section. We don't need every subgrid - we just want to be able to do pathing and FOV over the whole grid, and display an arbitrary but reasonable subsection.

john commented

2025-11-29 03:48:24 +00:00

Design Decision Summary

Named Layers as GridPoint Properties

# Explicit layer definition
grid = mcrfpy.Grid(
    grid_size=(100, 100),
    layers={
        "ground": "color",
        "terrain": "tile", 
        "fog": "color",
    }
)

cell = grid.at(x, y)
cell.ground = Color(50, 50, 50)   # ColorLayer access
cell.terrain = 42                  # TileLayer access

Key Design Points

Protected names: walkable and transparent are grid-level properties for TCOD pathfinding/FOV. They cannot be used as layer names.
Default layer: When layers parameter is omitted, defaults to {"tilesprite": "tile"} - maintains backward compatibility with grid.at(x,y).tilesprite = 5. Explicit layers={} means NO rendering layers (entity storage + pathfinding only).
Migration: Update tests to use explicit layer definitions. No deprecation machinery - just fix tests as migration path.

Unified Rendering Architecture

Each layer gets its own ChunkManager (~64x64 chunks)
Single rendering loop: for each layer → for each visible chunk → render if dirty → blit
Lazy chunk allocation: only render chunks that are visible
Memory efficient: can deallocate off-screen chunk textures

Implementation Tasks

Refactor GridLayer to use per-layer ChunkManager
Implement GridPoint dynamic property access via layer names
Add layers dict parameter to Grid constructor
Remove base layer rendering from UIGrid::render()
Protected name validation for walkable/transparent
Update test suite for explicit layer definitions

## Design Decision Summary ### Named Layers as GridPoint Properties ```python # Explicit layer definition grid = mcrfpy.Grid( grid_size=(100, 100), layers={ "ground": "color", "terrain": "tile", "fog": "color", } ) cell = grid.at(x, y) cell.ground = Color(50, 50, 50) # ColorLayer access cell.terrain = 42 # TileLayer access ``` ### Key Design Points 1. **Protected names**: `walkable` and `transparent` are grid-level properties for TCOD pathfinding/FOV. They cannot be used as layer names. 2. **Default layer**: When `layers` parameter is omitted, defaults to `{"tilesprite": "tile"}` - maintains backward compatibility with `grid.at(x,y).tilesprite = 5`. Explicit `layers={}` means NO rendering layers (entity storage + pathfinding only). 3. **Migration**: Update tests to use explicit layer definitions. No deprecation machinery - just fix tests as migration path. ### Unified Rendering Architecture - Each layer gets its own ChunkManager (~64x64 chunks) - Single rendering loop: for each layer → for each visible chunk → render if dirty → blit - Lazy chunk allocation: only render chunks that are visible - Memory efficient: can deallocate off-screen chunk textures ### Implementation Tasks - [ ] Refactor GridLayer to use per-layer ChunkManager - [ ] Implement GridPoint dynamic property access via layer names - [ ] Add `layers` dict parameter to Grid constructor - [ ] Remove base layer rendering from UIGrid::render() - [ ] Protected name validation for `walkable`/`transparent` - [ ] Update test suite for explicit layer definitions

john referenced this issue from a commit

2025-11-29 04:28:21 +00:00

feat: Implement chunk-based Grid rendering for large grids (closes #123)

john referenced this issue from a commit

2025-11-29 04:28:21 +00:00

feat: Migrate Grid to user-driven layer rendering (closes #150)

john closed this issue

2025-11-29 04:28:21 +00:00

john referenced this issue from a commit

2025-11-29 04:28:21 +00:00

refactor: Remove layer-related GridPoint properties, fix layer z-index

Sign in to join this conversation.