align packer specs and loader

This commit is contained in:
2026-03-24 13:40:55 +00:00
parent b532a05612
commit 619ac2c975
6 changed files with 61 additions and 164 deletions
@@ -5,6 +5,7 @@ Companion specs:
- [`../specs/13-cartridge.md`](../specs/13-cartridge.md)
- [`../specs/15-asset-management.md`](../specs/15-asset-management.md)
- [`../specs/04-gfx-peripheral.md`](../specs/04-gfx-peripheral.md)
Origin decision: [`../decisions/011-assets-pa-autocontained-runtime-contract.md`](../decisions/011-assets-pa-autocontained-runtime-contract.md)
@@ -104,6 +105,36 @@ The key point is to separate:
- the asset storage contract;
- the operational strategy for reading and decode.
## Serialized Form Is Not Resident Form
One of the most important asset-management lessons in the current runtime is that `RAW` does not mean "bitwise identical to in-memory layout".
The tile-bank path is the concrete example:
- the serialized payload stores indexed pixels as packed `4bpp`;
- the palette table remains serialized as `RGB565` little-endian;
- the runtime expands pixels into one `u8` index per pixel after decode.
That is why `AssetEntry.size` and `AssetEntry.decoded_size` must be thought of as different concepts:
- `size` is transport cost inside `assets.pa`;
- `decoded_size` is resident-bank cost after materialization.
If those two numbers are treated as interchangeable, telemetry, budgets, and validation all become misleading.
## Tile Banks Teach The Real Boundary
Tile banks are useful because they show the real separation of concerns:
- `assets.pa` defines the serialized envelope and metadata needed to reconstruct the bank;
- the runtime validates that metadata against the expected v1 contract;
- the resident `TileBank` is a runtime object, not a direct view over the cold bytes.
This is the right PROMETEU mental model:
- cartridge asset bytes are transport;
- bank objects are execution state.
## Why This Fits PROMETEU
This model fits the project well because:
+27 -1
View File
@@ -3,6 +3,8 @@
Status: pedagogical
Companion spec: [`../specs/04-gfx-peripheral.md`](../specs/04-gfx-peripheral.md)
Related asset spec: [`../specs/15-asset-management.md`](../specs/15-asset-management.md)
PROMETEU treats graphics as an explicit peripheral, not as a modern GPU.
The right mental model is a retro 2D machine with:
@@ -10,7 +12,7 @@ The right mental model is a retro 2D machine with:
- framebuffer;
- tile banks;
- tile layers;
- sprites por ordem de desenho;
- sprites ordered by draw order;
- deterministic composition per frame.
## Why This Exists
@@ -57,6 +59,30 @@ That enables:
- HUD themes;
- day and night cycles.
In the current tile-bank v1 baseline, this palette model is intentionally bounded:
- each bank carries `64` palettes;
- each palette carries `16` colors;
- `palette_id` is therefore a small runtime-facing selector, not an open-ended color namespace.
That limit is not incidental bookkeeping. It is part of how art packaging, runtime validation, and rendering stay aligned.
## Tile Banks Are Decoded Runtime Objects
The most useful intuition is to separate three layers:
- authored indexed art;
- serialized cart payload;
- resident runtime bank.
For tile banks in v1:
- authored pixels are logical indices `0..15`;
- serialized payload stores those indices as packed `4bpp`;
- runtime memory expands them to one `u8` index per pixel after decode.
So when reading the graphics model, do not imagine the renderer reading packed nibbles directly from cartridge storage. The renderer consumes a decoded `TileBank` object whose memory shape is optimized for runtime lookup, not for transport density.
## Use Cases
- area transition with `Scene Fade`;