143 lines
5.5 KiB
Markdown
143 lines
5.5 KiB
Markdown
---
|
|
id: PLN-0014
|
|
ticket: scene-bank-and-viewport-cache-refactor
|
|
title: Plan - Renderer Migration to Scene Viewport Cache
|
|
status: accepted
|
|
created: 2026-04-13
|
|
completed:
|
|
tags: [gfx, tilemap, runtime, render]
|
|
---
|
|
|
|
## Objective
|
|
|
|
Migrate world rendering from direct canonical `SceneBank` consumption to `SceneViewportCache` consumption while preserving the accepted observable composition order.
|
|
|
|
## Background
|
|
|
|
`DEC-0013` makes `SceneViewportCache` the immediate source of copy data for world blits and preserves the visible order of world layers, interleaved sprites, and HUD. `PLN-0011` already removed the old canonical `TileLayer` / `ScrollableTileLayer` model and cleaned the bridge surface accordingly. This plan focuses on the renderer migration itself.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
- Remove direct world-layer map reads from the renderer hot path.
|
|
- Make world-layer composition consume cache-backed copy requests.
|
|
- Preserve sprite interleaving and HUD ordering.
|
|
- Keep V1 destructive `back` composition acceptable.
|
|
|
|
### Excluded
|
|
- scene domain model refactor
|
|
- cache structural implementation
|
|
- resolver movement logic
|
|
- non-world rendering systems beyond required integration points
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Identify and isolate direct canonical map consumption in the renderer
|
|
|
|
**What:**
|
|
Locate current renderer paths that read canonical scene/layer maps directly.
|
|
|
|
**How:**
|
|
- Replace any remaining direct `SceneBank` / `SceneLayer` / `TileMap` reads in [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs) with abstraction points prepared to accept cache-sourced copy requests.
|
|
- Keep the migration incremental enough to preserve buildability.
|
|
|
|
**File(s):**
|
|
- [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs)
|
|
|
|
### Step 2 - Introduce world-layer copy paths driven by cache requests
|
|
|
|
**What:**
|
|
Teach the renderer to copy world content from `SceneViewportCache`.
|
|
|
|
**How:**
|
|
- Add renderer-facing entry points that consume per-layer copy instrumentation emitted by the resolver.
|
|
- Ensure the renderer treats the cache as the immediate world source for blit operations.
|
|
- Do not let the renderer re-own totem/drift/clamp policy.
|
|
|
|
**File(s):**
|
|
- [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs)
|
|
- Supporting cache/resolver integration modules
|
|
|
|
### Step 3 - Preserve accepted composition order
|
|
|
|
**What:**
|
|
Keep the visible ordering of layers, sprites, and HUD intact during migration.
|
|
|
|
**How:**
|
|
- Preserve composition order:
|
|
- world layer 0
|
|
- sprites
|
|
- world layer 1
|
|
- sprites
|
|
- world layer 2
|
|
- sprites
|
|
- world layer 3
|
|
- sprites
|
|
- HUD
|
|
- Keep `HUD`, sprites, and fades outside the viewport-cache invalidation model.
|
|
|
|
**File(s):**
|
|
- [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs)
|
|
|
|
### Step 4 - Preserve destructive `back` composition for V1
|
|
|
|
**What:**
|
|
Accept destructive composition while still benefiting from cache-backed world inputs.
|
|
|
|
**How:**
|
|
- Keep the first migrated renderer implementation destructive in `back`.
|
|
- Ensure the code path clearly separates:
|
|
- canonical scene data
|
|
- viewport cache data
|
|
- final composition buffer
|
|
- Avoid mixing “cache update” with “final buffer copy” concerns in the renderer.
|
|
|
|
**File(s):**
|
|
- [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs)
|
|
|
|
### Step 5 - Add renderer regression coverage
|
|
|
|
**What:**
|
|
Protect the migrated composition order and world rendering behavior.
|
|
|
|
**How:**
|
|
- Add tests or golden-style checks for:
|
|
- world layers rendered from cache, not canonical maps
|
|
- visible ordering of sprites between layers
|
|
- HUD remaining on top
|
|
- Add probes or assertions preventing accidental fallback to direct canonical map reads.
|
|
|
|
**File(s):**
|
|
- Renderer tests in [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs) and adjacent test modules
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
- Cache-driven world copy code produces the same visible layer ordering as the prior renderer.
|
|
|
|
### Integration Tests
|
|
- Full `render_all()` path uses `SceneViewportCache` for world layers.
|
|
- Sprites/HUD/fades remain correctly ordered relative to world layers.
|
|
|
|
### Manual Verification
|
|
- Render representative scenes with multiple active layers and sprites to confirm no visible ordering regressions.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] Renderer world composition no longer reads canonical `SceneBank` data directly in the hot path.
|
|
- [ ] World layers are copied from `SceneViewportCache`.
|
|
- [ ] Sprite interleaving and HUD ordering remain correct.
|
|
- [ ] V1 destructive composition still works end-to-end.
|
|
- [ ] Regression coverage protects the migrated path.
|
|
|
|
## Dependencies
|
|
|
|
- Depends on `PLN-0011`, `PLN-0012`, and `PLN-0013`.
|
|
- Source decision: `DEC-0013`
|
|
|
|
## Risks
|
|
|
|
- Renderer migration can accidentally duplicate world-copy work if cache and compositor responsibilities blur.
|
|
- Sprite ordering regressions are easy to introduce during world-layer refactoring.
|
|
- Temporary fallback paths can linger unless tests explicitly block them.
|