125 lines
4.5 KiB
Markdown
125 lines
4.5 KiB
Markdown
---
|
||
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, final integration surfaces, 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. `PLN-0011` already removed the old canonical tile-layer APIs and introduced `BankType::SCENE` plus scene-aware bank slots. The binary `SCENE` payload contract and decoder are now isolated in `PLN-0016`.
|
||
|
||
## Scope
|
||
|
||
### Included
|
||
- Update bridge APIs and exposed runtime surfaces.
|
||
- 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:**
|
||
- Verify `GfxBridge` and adjacent bridge traits stay free of obsolete canonical layer ownership assumptions after cache/resolver integration.
|
||
- 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 the pre-`SceneBank` model.
|
||
|
||
**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 - Remove stale type and API remnants
|
||
|
||
**What:**
|
||
Clean out old interfaces that would leave the codebase in a dual-model state.
|
||
|
||
**How:**
|
||
- Remove any remaining obsolete references to:
|
||
- `TileLayer`
|
||
- `ScrollableTileLayer`
|
||
- direct old-layer scroll ownership APIs
|
||
- transitional commented fallback paths left during migration
|
||
- 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 4 - 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.
|
||
- [ ] Stale old-layer APIs are removed.
|
||
- [ ] Full-stack regression coverage exists for the migration.
|
||
|
||
## Dependencies
|
||
|
||
- Depends on `PLN-0011`, `PLN-0012`, `PLN-0013`, `PLN-0014`, and `PLN-0016`.
|
||
- Source decision: `DEC-0013`
|
||
|
||
## Risks
|
||
|
||
- API cleanup is where hidden dependencies on the old model are most likely to surface.
|
||
- If stale APIs are not removed aggressively, the codebase can get stuck in a fragile dual-model transition.
|