---
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.