implements PLN-0011
This commit is contained in:
@@ -0,0 +1,152 @@
|
||||
---
|
||||
id: PLN-0011
|
||||
ticket: scene-bank-and-viewport-cache-refactor
|
||||
title: Plan - Scene Core Types and Bank Contract
|
||||
status: accepted
|
||||
created: 2026-04-13
|
||||
completed:
|
||||
tags: [gfx, tilemap, runtime, render]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Introduce the canonical type model required by `DEC-0013`: `SceneBank`, `SceneLayer`, `TileMap`, and `Tile`, plus the asset-bank/domain contract changes needed to carry scene-backed tilemap data as the new source of truth.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0013` locks the canonical runtime model around `SceneBank` and `SceneLayer`, replacing the old `TileLayer`/`ScrollableTileLayer` coupling. This plan isolates the domain-model and bank-contract refactor before cache or renderer migration begins.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Introduce `SceneBank` and `SceneLayer` in the HAL/runtime model.
|
||||
- Preserve `TileMap` and `Tile` as canonical grid/unit concepts.
|
||||
- Define the minimum `SceneLayer` fields required by the decision.
|
||||
- Update bank/domain enums and payload contracts so scenes can exist as first-class banked content.
|
||||
- Add compile-time migration shims only when strictly needed to keep the tree buildable during the refactor.
|
||||
|
||||
### Excluded
|
||||
- `SceneViewportCache`
|
||||
- `SceneViewportResolver`
|
||||
- renderer migration to cache consumption
|
||||
- rematerialization algorithm
|
||||
- final composition changes
|
||||
- final binary `SCENE` payload format and decoder implementation
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Introduce canonical scene types in HAL
|
||||
|
||||
**What:**
|
||||
Add `SceneBank` and `SceneLayer` to the HAL model and define the minimum canonical fields required by the decision.
|
||||
|
||||
**How:**
|
||||
- Replace or retire the old `TileLayer`-centric model in [tile_layer.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/tile_layer.rs).
|
||||
- Keep `TileMap` as the canonical grid owner and `Tile` as the canonical cell unit.
|
||||
- Define `SceneLayer` with:
|
||||
- `glyph_bank_id`
|
||||
- `tile_size`
|
||||
- `active`
|
||||
- `motion_factor`
|
||||
- `tilemap`
|
||||
- Define `SceneBank` as the aggregate of exactly four `SceneLayer`s using a fixed array.
|
||||
|
||||
**File(s):**
|
||||
- [crates/console/prometeu-hal/src/tile_layer.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/tile_layer.rs)
|
||||
- [crates/console/prometeu-hal/src/tile.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/tile.rs)
|
||||
- [crates/console/prometeu-hal/src/glyph.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/glyph.rs)
|
||||
- HAL module export files as needed
|
||||
|
||||
### Step 2 - Remove `ScrollableTileLayer` from the canonical model
|
||||
|
||||
**What:**
|
||||
Delete the canonical role of `ScrollableTileLayer` and any direct ownership path that makes scroll part of the canonical scene representation.
|
||||
|
||||
**How:**
|
||||
- Remove `ScrollableTileLayer` and `HudTileLayer` from the HAL tile-layer model or reduce them to non-canonical transitional wrappers only if needed to keep compilation moving during the refactor.
|
||||
- Ensure canonical scene state no longer encodes direct renderer scroll ownership.
|
||||
|
||||
**File(s):**
|
||||
- [crates/console/prometeu-hal/src/tile_layer.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/tile_layer.rs)
|
||||
- [crates/console/prometeu-hal/src/gfx_bridge.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/gfx_bridge.rs)
|
||||
|
||||
### Step 3 - Introduce the bank/domain contract for scene-backed content
|
||||
|
||||
**What:**
|
||||
Add or revise the asset-bank/domain model so the canonical loaded scene can be represented in the bank contract.
|
||||
|
||||
**How:**
|
||||
- Update `BankType` and related asset/bank metadata in HAL to support `Scene`-backed content at the domain level.
|
||||
- Adjust slot/reference types where necessary so scene content can be addressed consistently with existing banks.
|
||||
- Keep the exact asset-bank enum wiring minimal and domain-first; do not conflate it with renderer cache details.
|
||||
|
||||
**File(s):**
|
||||
- [crates/console/prometeu-hal/src/asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/asset.rs)
|
||||
- [crates/console/prometeu-hal/src/syscalls/domains/bank.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/syscalls/domains/bank.rs)
|
||||
- [crates/console/prometeu-hal/src/syscalls/domains/asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/syscalls/domains/asset.rs)
|
||||
- Any bank-facing shared types used by runtime and drivers
|
||||
|
||||
### Step 4 - Thread the new scene types through driver-facing runtime structures
|
||||
|
||||
**What:**
|
||||
Prepare the driver layer to reference canonical `SceneBank` types instead of old layer/map ownership.
|
||||
|
||||
**How:**
|
||||
- Identify the driver-side structs currently owning the old layer model.
|
||||
- Replace those type references with the new canonical scene types without yet switching renderer logic to the viewport cache.
|
||||
- Keep this step focused on compile-safe type replacement, not behavior changes.
|
||||
|
||||
**File(s):**
|
||||
- [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs)
|
||||
- [crates/console/prometeu-drivers/src/hardware.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/hardware.rs)
|
||||
|
||||
### Step 5 - Add baseline tests for the canonical scene model
|
||||
|
||||
**What:**
|
||||
Protect the new canonical scene types with focused tests before cache and renderer work begins.
|
||||
|
||||
**How:**
|
||||
- Add unit tests for:
|
||||
- scene-bank construction
|
||||
- layer ownership of tilemaps
|
||||
- tile write/read behavior
|
||||
- preservation of `motion_factor`
|
||||
- Keep tests domain-focused and independent of viewport caching.
|
||||
|
||||
**File(s):**
|
||||
- HAL tests colocated with scene/tile modules
|
||||
- Driver tests only if required to preserve build integrity
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- `SceneBank` owns exactly four canonical `SceneLayer`s.
|
||||
- `SceneLayer` exposes the required minimal fields.
|
||||
- `TileMap` indexing and mutation still behave canonically.
|
||||
- `motion_factor` survives construction and mutation paths.
|
||||
|
||||
### Integration Tests
|
||||
- Asset/bank domain types accept the new scene-backed contract without breaking existing glyph/sound usage.
|
||||
- `SCENE` binary decode remains intentionally open and out of scope for this plan.
|
||||
|
||||
### Manual Verification
|
||||
- Build the console crates and verify no canonical runtime path still treats `ScrollableTileLayer` as the source of truth.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `SceneBank` and `SceneLayer` exist as canonical runtime types.
|
||||
- [ ] `ScrollableTileLayer` is no longer the canonical scene model.
|
||||
- [ ] Bank/domain types can represent scene-backed content.
|
||||
- [ ] Driver-facing runtime structures compile against the new canonical scene model.
|
||||
- [ ] Baseline tests protect the new type graph.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: `DEC-0013`
|
||||
- No dependency on later plans; this is the foundation for the rest of the family.
|
||||
|
||||
## Risks
|
||||
|
||||
- Breaking too many public or cross-crate type references at once can stall compilation.
|
||||
- Bank enum changes can ripple into syscalls and telemetry if not scoped carefully.
|
||||
- Transitional wrappers can accidentally survive longer than intended if not explicitly retired in later plans.
|
||||
@@ -0,0 +1,147 @@
|
||||
---
|
||||
id: PLN-0012
|
||||
ticket: scene-bank-and-viewport-cache-refactor
|
||||
title: Plan - Scene Viewport Cache Structure
|
||||
status: accepted
|
||||
created: 2026-04-13
|
||||
completed:
|
||||
tags: [gfx, tilemap, runtime, render]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Implement the `SceneViewportCache` as the operational render cache for one `Scene`, including one internal ringbuffer per layer and lightweight derived cache entries for raster acceleration.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0013` locks `SceneViewportCache` as the renderer-facing view of scene data and prefers internal ringbuffer storage per layer. This plan isolates the cache data structure and update API before resolver and renderer integration.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Define `SceneViewportCache`.
|
||||
- Define the per-layer internal ringbuffer structure.
|
||||
- Define the cached tile entry format.
|
||||
- Define cache update APIs for line, column, and area/region.
|
||||
- Define full invalidation on scene swap.
|
||||
|
||||
### Excluded
|
||||
- camera logic
|
||||
- drift/hysteresis logic
|
||||
- final renderer migration
|
||||
- execution of blits into `back`
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Define cache entry and layer-cache structures
|
||||
|
||||
**What:**
|
||||
Create the internal data model for one viewport cache layer and for cached tile entries.
|
||||
|
||||
**How:**
|
||||
- Introduce a cache tile entry type that stores:
|
||||
- resolved `glyph_id`
|
||||
- resolved `palette_id`
|
||||
- packed flip flags
|
||||
- `active/empty`
|
||||
- fast layer-local glyph bank reference/index
|
||||
- Introduce one ringbuffer-backed layer-cache structure per scene layer.
|
||||
- Keep ringbuffer internals encapsulated and out of public semantic APIs.
|
||||
|
||||
**File(s):**
|
||||
- New HAL or driver-side viewport-cache module(s), likely under:
|
||||
- `crates/console/prometeu-hal/src/`
|
||||
- and/or `crates/console/prometeu-drivers/src/`
|
||||
|
||||
### Step 2 - Define `SceneViewportCache` as a four-layer aggregate
|
||||
|
||||
**What:**
|
||||
Create the top-level cache aggregate for one `Scene`.
|
||||
|
||||
**How:**
|
||||
- Represent one cache aggregate containing four internal layer caches.
|
||||
- Thread through cache dimensions and tile-size assumptions for V1.
|
||||
- Make the cache explicitly scene-derived and non-canonical.
|
||||
|
||||
**File(s):**
|
||||
- New cache module(s)
|
||||
- Any related exports in HAL/driver public surfaces
|
||||
|
||||
### Step 3 - Implement cache mutation APIs
|
||||
|
||||
**What:**
|
||||
Define the update surface that later plans will use for rematerialization.
|
||||
|
||||
**How:**
|
||||
- Add explicit APIs for:
|
||||
- refresh line
|
||||
- refresh column
|
||||
- refresh area/region
|
||||
- invalidate whole cache on scene swap
|
||||
- Ensure corner refresh can use region updates without duplicate work on already-present tiles.
|
||||
|
||||
**File(s):**
|
||||
- New cache module(s)
|
||||
- Any helper modules shared with resolver integration
|
||||
|
||||
### Step 4 - Implement scene-to-cache materialization helpers
|
||||
|
||||
**What:**
|
||||
Add helpers that copy canonical scene data into cache entries.
|
||||
|
||||
**How:**
|
||||
- Build helpers that read canonical `SceneLayer`/`TileMap` data and populate cache entries.
|
||||
- Keep the helpers unaware of camera policy; they should only perform requested materialization work.
|
||||
- Ensure per-layer movement factors remain metadata of the scene layer, not cache-only state.
|
||||
|
||||
**File(s):**
|
||||
- New cache/materialization helper module(s)
|
||||
|
||||
### Step 5 - Add focused tests for cache structure and update rules
|
||||
|
||||
**What:**
|
||||
Protect the cache shape and update operations before wiring the resolver.
|
||||
|
||||
**How:**
|
||||
- Add tests for:
|
||||
- ringbuffer wrap behavior
|
||||
- line refresh
|
||||
- column refresh
|
||||
- region refresh
|
||||
- scene-swap invalidation
|
||||
- no duplicate reload for corner-style region updates
|
||||
|
||||
**File(s):**
|
||||
- Tests colocated with cache modules
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- Each cache layer maintains ringbuffer invariants under wrap.
|
||||
- Cache entry fields match the expected derived values from canonical scene tiles.
|
||||
- Line/column/region refresh APIs only rewrite the requested area.
|
||||
|
||||
### Integration Tests
|
||||
- Materialization from `Scene` into `SceneViewportCache` succeeds across all four layers.
|
||||
|
||||
### Manual Verification
|
||||
- Inspect debug output or temporary probes to confirm cache updates do not expose ringbuffer details outside the cache boundary.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `SceneViewportCache` exists as a four-layer aggregate.
|
||||
- [ ] Each layer cache uses internal ringbuffer storage.
|
||||
- [ ] Cache entries store the lightweight derived raster fields defined by the decision.
|
||||
- [ ] Explicit APIs exist for line, column, area/region, and full invalidation.
|
||||
- [ ] Tests cover wrap and non-duplicative corner updates.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0011` for canonical `Scene` / `SceneLayer` / `TileMap` types.
|
||||
- Source decision: `DEC-0013`
|
||||
|
||||
## Risks
|
||||
|
||||
- Over-designing cache entry shape can accidentally turn the cache into a second heavy scene representation.
|
||||
- Ringbuffer implementation bugs can stay hidden until resolver integration if tests are too weak.
|
||||
- Region refresh semantics can become ambiguous if API boundaries are not explicit early.
|
||||
@@ -0,0 +1,161 @@
|
||||
---
|
||||
id: PLN-0013
|
||||
ticket: scene-bank-and-viewport-cache-refactor
|
||||
title: Plan - Scene Viewport Resolver and Rematerialization
|
||||
status: accepted
|
||||
created: 2026-04-13
|
||||
completed:
|
||||
tags: [gfx, tilemap, runtime, render]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Implement `SceneViewportResolver` as the owner of master totem, per-layer totems, drift, hysteresis, clamp, cache update decisions, and per-layer copy instrumentation metadata.
|
||||
|
||||
## Background
|
||||
|
||||
`DEC-0013` makes the resolver the owner of movement policy between camera input and viewport cache updates. This plan isolates the decision logic before final renderer migration.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Define `SceneViewportResolver`.
|
||||
- Implement master totem and per-layer derived totems.
|
||||
- Implement drift and hysteresis.
|
||||
- Implement clamp behavior.
|
||||
- Implement cache-update triggering and copy instrumentation metadata.
|
||||
|
||||
### Excluded
|
||||
- actual framebuffer copy execution
|
||||
- sprite/HUD/fade composition logic
|
||||
- broad renderer migration
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Define resolver state and inputs
|
||||
|
||||
**What:**
|
||||
Create the resolver state model and its public input surface.
|
||||
|
||||
**How:**
|
||||
- Define resolver state to own:
|
||||
- master totem
|
||||
- per-layer derived totems
|
||||
- viewport dimensions
|
||||
- hysteresis thresholds
|
||||
- clamp-relevant scene bounds
|
||||
- Define the external entry point that accepts camera position input.
|
||||
|
||||
**File(s):**
|
||||
- New resolver module(s), likely under HAL or drivers depending on final ownership
|
||||
|
||||
### Step 2 - Implement master-to-layer totem derivation
|
||||
|
||||
**What:**
|
||||
Make layer motion derive from the master totem using each layer’s `totem_factor`.
|
||||
|
||||
**How:**
|
||||
- Compute per-layer effective motion from the master totem.
|
||||
- Preserve support for normal layers (`1.0`) and parallax/background-like layers (`!= 1.0`).
|
||||
- Keep the derivation explicit and testable per axis.
|
||||
|
||||
**File(s):**
|
||||
- Resolver module(s)
|
||||
- Any math/helper module(s) needed for factor handling
|
||||
|
||||
### Step 3 - Implement drift, hysteresis, and clamp
|
||||
|
||||
**What:**
|
||||
Translate camera motion into discrete totem advancement safely.
|
||||
|
||||
**How:**
|
||||
- Implement drift calculation in pixel space against totem centers in tile space.
|
||||
- Implement hysteresis with:
|
||||
- internal safe band
|
||||
- external trigger band
|
||||
- Implement clamp against scene bounds.
|
||||
- Ensure edge behavior is explicitly asymmetric when clamped.
|
||||
|
||||
**File(s):**
|
||||
- Resolver module(s)
|
||||
|
||||
### Step 4 - Connect resolver decisions to cache update requests
|
||||
|
||||
**What:**
|
||||
Turn resolver state changes into concrete cache update requests.
|
||||
|
||||
**How:**
|
||||
- Emit requests for:
|
||||
- line refresh
|
||||
- column refresh
|
||||
- area/region refresh for corner updates
|
||||
- Ensure no duplicate work is scheduled for already-covered cache content.
|
||||
- Keep the resolver in charge of “what to refresh,” not “how cache storage performs it.”
|
||||
|
||||
**File(s):**
|
||||
- Resolver module(s)
|
||||
- Shared request/command structs between resolver and cache
|
||||
|
||||
### Step 5 - Add copy instrumentation outputs for later renderer use
|
||||
|
||||
**What:**
|
||||
Make the resolver capable of describing which cache slice/region should be copied for each layer.
|
||||
|
||||
**How:**
|
||||
- Define a per-layer copy request/instrumentation type.
|
||||
- Include enough information for a later compositor to copy from cache into `back` without re-deciding viewport math.
|
||||
- Do not execute the copy here.
|
||||
|
||||
**File(s):**
|
||||
- Resolver module(s)
|
||||
- Shared copy-request types
|
||||
|
||||
### Step 6 - Add focused resolver tests
|
||||
|
||||
**What:**
|
||||
Protect resolver correctness before renderer integration.
|
||||
|
||||
**How:**
|
||||
- Add tests for:
|
||||
- master totem updates
|
||||
- per-layer totem factor derivation
|
||||
- hysteresis stability
|
||||
- repeated high-speed movement
|
||||
- clamp at scene edges
|
||||
- corner-trigger conversion into region refresh requests
|
||||
|
||||
**File(s):**
|
||||
- Tests colocated with resolver modules
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- Hysteresis prevents edge flick/thrash.
|
||||
- Totem movement occurs discretely in tile steps.
|
||||
- Per-layer totems follow the master according to `totem_factor`.
|
||||
- Clamp behavior is correct near scene edges.
|
||||
|
||||
### Integration Tests
|
||||
- Resolver outputs valid update requests consumable by `SceneViewportCache`.
|
||||
|
||||
### Manual Verification
|
||||
- Instrument logs or debug traces to confirm no unnecessary refresh churn during back-and-forth movement near edges.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `SceneViewportResolver` exists with the full state required by `DEC-0013`.
|
||||
- [ ] Master and per-layer totems are derived correctly.
|
||||
- [ ] Hysteresis and clamp are implemented and tested.
|
||||
- [ ] Cache refresh requests are emitted by line, column, and region as required.
|
||||
- [ ] Copy instrumentation metadata is available for later renderer use.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0011` and `PLN-0012`.
|
||||
- Source decision: `DEC-0013`
|
||||
|
||||
## Risks
|
||||
|
||||
- Resolver logic can become hard to reason about if movement, clamp, and copy instrumentation are not clearly separated.
|
||||
- Parallax factor derivation can introduce subtle off-by-one or drift mismatch issues per layer.
|
||||
- Region-update scheduling can duplicate work if X/Y corner movement is not normalized carefully.
|
||||
@@ -0,0 +1,142 @@
|
||||
---
|
||||
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 map 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. 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 layer maps directly.
|
||||
|
||||
**How:**
|
||||
- Replace direct `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 scene maps 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.
|
||||
@@ -0,0 +1,141 @@
|
||||
---
|
||||
id: PLN-0015
|
||||
ticket: scene-bank-and-viewport-cache-refactor
|
||||
title: Plan - API, Bank Integration, and Tests
|
||||
status: accepted
|
||||
created: 2026-04-13
|
||||
completed:
|
||||
tags: [gfx, tilemap, runtime, render]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Finish the scene/viewport-cache migration by aligning exposed APIs, bank-loading integration, and test coverage across HAL, drivers, and system entry points.
|
||||
|
||||
## Background
|
||||
|
||||
After core types, cache, resolver, and renderer migration exist, the remaining work is to align the surrounding surfaces so the new architecture is usable as the runtime’s operational model.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Update bridge APIs and exposed runtime surfaces.
|
||||
- Align bank-loading/integration paths with scene-backed content.
|
||||
- Remove stale tile-layer-era interfaces.
|
||||
- Add cross-layer regression coverage.
|
||||
|
||||
### Excluded
|
||||
- additional architectural redesign
|
||||
- feature work beyond the accepted decision
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Update HAL and bridge surfaces
|
||||
|
||||
**What:**
|
||||
Remove or replace public APIs still shaped around the old scrollable tile-layer model.
|
||||
|
||||
**How:**
|
||||
- Update `GfxBridge` and adjacent bridge traits so they no longer expose obsolete canonical layer ownership assumptions.
|
||||
- Introduce scene/cache/resolver-oriented access only where required by runtime consumers.
|
||||
|
||||
**File(s):**
|
||||
- [crates/console/prometeu-hal/src/gfx_bridge.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/gfx_bridge.rs)
|
||||
- Other bridge traits affected by scene model changes
|
||||
|
||||
### Step 2 - Align driver/hardware construction paths
|
||||
|
||||
**What:**
|
||||
Ensure hardware and driver initialization paths can construct and own the new scene/cache/resolver model.
|
||||
|
||||
**How:**
|
||||
- Update hardware bootstrap and driver ownership paths to instantiate the canonical scene and viewport-cache stack.
|
||||
- Remove any remaining ownership assumptions tied to `ScrollableTileLayer`.
|
||||
|
||||
**File(s):**
|
||||
- [crates/console/prometeu-drivers/src/hardware.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/hardware.rs)
|
||||
- [crates/console/prometeu-drivers/src/gfx.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/gfx.rs)
|
||||
|
||||
### Step 3 - Align asset/bank integration paths
|
||||
|
||||
**What:**
|
||||
Make sure bank-loading and asset integration paths understand the scene-backed model at the operational layer.
|
||||
|
||||
**How:**
|
||||
- Update asset-side or loader-side integration points so scene-backed content can be staged, installed, and referenced coherently.
|
||||
- Keep the work scoped to the bank-loading path; do not reopen the canonical model here.
|
||||
|
||||
**File(s):**
|
||||
- [crates/console/prometeu-drivers/src/asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/asset.rs)
|
||||
- [crates/console/prometeu-drivers/src/memory_banks.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/memory_banks.rs)
|
||||
- [crates/console/prometeu-hal/src/cartridge_loader.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/cartridge_loader.rs)
|
||||
- Related asset/bank shared types
|
||||
|
||||
### Step 4 - Remove stale type and API remnants
|
||||
|
||||
**What:**
|
||||
Clean out old interfaces that would leave the codebase in a dual-model state.
|
||||
|
||||
**How:**
|
||||
- Remove obsolete references to:
|
||||
- `TileLayer`
|
||||
- `ScrollableTileLayer`
|
||||
- direct old-layer scroll ownership APIs
|
||||
- Keep only the canonical scene model and the viewport-cache/render pipeline required by the decision.
|
||||
|
||||
**File(s):**
|
||||
- HAL and driver modules touched by earlier plans
|
||||
|
||||
### Step 5 - Add full-stack regression coverage
|
||||
|
||||
**What:**
|
||||
Add the minimum test family needed to execute the migration safely one plan at a time.
|
||||
|
||||
**How:**
|
||||
- Add tests for:
|
||||
- canonical scene ownership
|
||||
- viewport-cache update behavior
|
||||
- resolver drift/hysteresis
|
||||
- renderer composition order
|
||||
- scene swap invalidation
|
||||
- absence of stale old-layer APIs
|
||||
- Add at least one integration path that exercises:
|
||||
- scene load
|
||||
- cache population
|
||||
- resolver update
|
||||
- renderer world composition
|
||||
|
||||
**File(s):**
|
||||
- Test modules across HAL, drivers, and system crates as needed
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
- Public/runtime-facing APIs no longer depend on `ScrollableTileLayer`.
|
||||
- Cache, resolver, and renderer modules remain individually covered.
|
||||
|
||||
### Integration Tests
|
||||
- End-to-end scene load -> cache update -> renderer composition path succeeds.
|
||||
- Scene swap invalidates cache and repopulates correctly.
|
||||
|
||||
### Manual Verification
|
||||
- Build the runtime and exercise representative world scenes to confirm no stale assumptions remain in construction or render flow.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Bridge and runtime-facing APIs align with the new scene/cache model.
|
||||
- [ ] Hardware/driver construction paths instantiate the new architecture correctly.
|
||||
- [ ] Asset/bank integration paths accept the scene-backed model.
|
||||
- [ ] Stale old-layer APIs are removed.
|
||||
- [ ] Full-stack regression coverage exists for the migration.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Depends on `PLN-0011`, `PLN-0012`, `PLN-0013`, and `PLN-0014`.
|
||||
- Source decision: `DEC-0013`
|
||||
|
||||
## Risks
|
||||
|
||||
- API cleanup is where hidden dependencies on the old model are most likely to surface.
|
||||
- Asset/bank integration can expand in scope if loader assumptions are too tightly coupled to current bank enums.
|
||||
- If stale APIs are not removed aggressively, the codebase can get stuck in a fragile dual-model transition.
|
||||
Reference in New Issue
Block a user