align packer specs and loader
This commit is contained in:
@@ -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:
|
||||
|
||||
@@ -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`;
|
||||
|
||||
Reference in New Issue
Block a user