165 lines
6.6 KiB
Markdown
165 lines
6.6 KiB
Markdown
---
|
|
id: PLN-0016
|
|
ticket: scene-bank-and-viewport-cache-refactor
|
|
title: Plan - Scene Binary Payload Format and Decoder
|
|
status: accepted
|
|
created: 2026-04-13
|
|
completed:
|
|
tags: [asset, runtime, scene, codec, binary-format]
|
|
---
|
|
|
|
## Objective
|
|
|
|
Define the canonical binary payload contract for `SCENE` assets and implement the runtime decoder needed to load `SceneBank` content without JSON-based scene payloads.
|
|
|
|
## Background
|
|
|
|
`DEC-0013` established `SceneBank` as the canonical loaded scene aggregate. `PLN-0011` introduced `BankType::SCENE` and the scene-aware bank slot model, but intentionally left `SCENE` payload decoding open. A temporary `todo!()` now blocks scene payload materialization in the asset manager until the binary contract is closed. This plan isolates that format and decoder work before the final integration pass.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
- Define the binary on-disk/on-wire payload format for `SCENE`.
|
|
- Define the minimum metadata contract needed in `AssetEntry` for `SCENE`.
|
|
- Implement the runtime decoder from payload bytes into `SceneBank`.
|
|
- Add format and decode tests for valid and invalid scene payloads.
|
|
- Re-enable scene asset load/preload coverage once the decoder exists.
|
|
|
|
### Excluded
|
|
- `SceneViewportCache`
|
|
- `SceneViewportResolver`
|
|
- renderer migration
|
|
- cartridge authoring tooling beyond what is strictly needed to encode test fixtures
|
|
- reopening canonical scene/runtime type design
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Define the binary `SCENE` payload contract
|
|
|
|
**What:**
|
|
Close the binary layout for serialized `SceneBank` assets.
|
|
|
|
**How:**
|
|
- Define a versioned binary format with:
|
|
- file/payload prelude or version marker
|
|
- fixed four-layer scene layout
|
|
- per-layer metadata block
|
|
- per-layer tilemap dimensions
|
|
- serialized tile records
|
|
- Keep the format aligned with the canonical runtime shape from `PLN-0011`:
|
|
- `SceneBank`
|
|
- `[SceneLayer; 4]`
|
|
- `motion_factor`
|
|
- `TileMap`
|
|
- `Tile`
|
|
- Document field sizes, endianness, ordering, and validation rules.
|
|
|
|
**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/cartridge_loader.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/cartridge_loader.rs)
|
|
- Additional shared asset-format module(s) if needed
|
|
|
|
### Step 2 - Define `SCENE` metadata requirements in `AssetEntry`
|
|
|
|
**What:**
|
|
Decide what belongs in `AssetEntry.metadata` versus the binary payload itself.
|
|
|
|
**How:**
|
|
- Keep metadata minimal and stable.
|
|
- Add only fields that materially help validation or loader routing.
|
|
- Avoid duplicating large structural scene information in both metadata and payload.
|
|
- Add typed metadata helpers in HAL if required for scene assets.
|
|
|
|
**File(s):**
|
|
- [crates/console/prometeu-hal/src/asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/asset.rs)
|
|
|
|
### Step 3 - Implement the runtime `SCENE` decoder
|
|
|
|
**What:**
|
|
Replace the current `todo!()` loader path with a real binary decoder.
|
|
|
|
**How:**
|
|
- Implement `perform_load_scene_bank(...)` using the accepted binary contract.
|
|
- Decode from slice/reader into canonical runtime objects:
|
|
- `SceneBank`
|
|
- `SceneLayer`
|
|
- `TileMap`
|
|
- `Tile`
|
|
- Add explicit validation for:
|
|
- invalid version
|
|
- short payload
|
|
- invalid tile-size values
|
|
- layer count mismatch
|
|
- tile count mismatch
|
|
- numeric overflow / malformed dimensions
|
|
- Keep decode logic self-contained and free of viewport/cache behavior.
|
|
|
|
**File(s):**
|
|
- [crates/console/prometeu-drivers/src/asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/asset.rs)
|
|
- Supporting HAL/shared modules if decoder helpers are factored out
|
|
|
|
### Step 4 - Re-enable scene asset loading paths and tests
|
|
|
|
**What:**
|
|
Turn scene asset loading back on in the asset manager and restore coverage.
|
|
|
|
**How:**
|
|
- Re-enable the `SCENE` load/preload path currently blocked by the `todo!()`.
|
|
- Add tests for:
|
|
- scene payload decode success
|
|
- scene asset load
|
|
- scene preload on initialization
|
|
- malformed scene payload rejection
|
|
- Ensure glyph/sound behavior remains unchanged.
|
|
|
|
**File(s):**
|
|
- [crates/console/prometeu-drivers/src/asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/asset.rs)
|
|
|
|
### Step 5 - Confirm cartridge-loader and asset-table compatibility
|
|
|
|
**What:**
|
|
Ensure the broader cartridge/asset pipeline accepts the finalized `SCENE` contract cleanly.
|
|
|
|
**How:**
|
|
- Verify `AssetEntry` and cartridge-loading paths accept the new scene metadata contract.
|
|
- Add targeted tests for asset-table parsing or preload validation if needed.
|
|
- Keep this step scoped to compatibility with the finalized binary scene payload, not new tooling features.
|
|
|
|
**File(s):**
|
|
- [crates/console/prometeu-hal/src/cartridge_loader.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/cartridge_loader.rs)
|
|
- [crates/console/prometeu-hal/src/asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/asset.rs)
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
- Valid binary scene payloads decode into the expected `SceneBank`.
|
|
- Invalid payloads fail with explicit decoder errors.
|
|
- Per-layer metadata and tile contents survive round-trip fixture decode.
|
|
|
|
### Integration Tests
|
|
- `SCENE` assets can be loaded and preloaded through `AssetManager`.
|
|
- Scene bank slot installation works without breaking glyph/sound behavior.
|
|
|
|
### Manual Verification
|
|
- Inspect one representative binary scene fixture and confirm the decoded `SceneBank` matches the expected four-layer canonical shape.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] The binary `SCENE` payload format is explicitly defined and versioned.
|
|
- [ ] `AssetEntry` requirements for `SCENE` are documented and implemented.
|
|
- [ ] `perform_load_scene_bank(...)` is implemented without JSON payload parsing.
|
|
- [ ] Scene load/preload tests pass against the finalized binary decoder.
|
|
- [ ] Glyph and sound asset paths remain unaffected.
|
|
|
|
## Dependencies
|
|
|
|
- Depends on `PLN-0011`.
|
|
- Should complete before the final integration/cleanup pass in `PLN-0015`.
|
|
- Source decision: `DEC-0013`
|
|
|
|
## Risks
|
|
|
|
- Overloading `AssetEntry.metadata` can duplicate scene structure and make the contract brittle.
|
|
- A weak binary format definition can create hidden compatibility problems for future scene growth.
|
|
- Decoder validation gaps can surface later as corrupted scene state instead of explicit asset-load failures.
|