Glyph Bank Domain Naming Contract

This commit is contained in:
2026-04-10 06:00:47 +01:00
parent 59101baf00
commit 54f65f58e6
21 changed files with 700 additions and 220 deletions
@@ -123,7 +123,7 @@ The current asset model works better if you do not treat every bank as equally g
Some banks are specialized:
- `TILES`
- `GLYPH`
- `SOUNDS`
For these, the bank contract already carries most of the important format rules. That means:
@@ -163,7 +163,7 @@ It does not say:
One of the most important asset-management lessons in the current runtime is that `codec = NONE` does not mean "bitwise identical to in-memory layout".
The tile-bank path is the concrete example:
The glyph-bank path is the concrete example:
- there is no additional generic codec layer for the asset;
- the serialized payload stores indexed pixels as packed `4bpp`;
@@ -182,13 +182,13 @@ That is why `AssetEntry.size` and `AssetEntry.decoded_size` must be thought of a
If those two numbers are treated as interchangeable, telemetry, budgets, and validation all become misleading.
## Tile Banks Teach The Real Boundary
## Glyph Banks Teach The Real Boundary
Tile banks are useful because they show the real separation of concerns:
Glyph 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.
- the resident `GlyphBank` is a runtime object, not a direct view over the cold bytes.
This is the right PROMETEU mental model:
@@ -18,7 +18,7 @@ PROMETEU treats graphics as an explicit peripheral, not as a modern GPU.
The right mental model is a retro 2D machine with:
- framebuffer;
- tile banks;
- glyph banks;
- tile layers;
- sprites ordered by draw order;
- deterministic composition per frame.
@@ -67,7 +67,7 @@ That enables:
- HUD themes;
- day and night cycles.
In the current tile-bank v1 baseline, this palette model is intentionally bounded:
In the current glyph-bank v1 baseline, this palette model is intentionally bounded:
- each bank carries `64` palettes;
- each palette carries `16` colors;
@@ -75,7 +75,7 @@ In the current tile-bank v1 baseline, this palette model is intentionally bounde
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
## Glyph Banks Are Decoded Runtime Objects
The most useful intuition is to separate three layers:
@@ -83,13 +83,13 @@ The most useful intuition is to separate three layers:
- serialized cart payload;
- resident runtime bank.
For tile banks in v1:
For glyph 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.
So when reading the graphics model, do not imagine the renderer reading packed nibbles directly from cartridge storage. The renderer consumes a decoded `GlyphBank` object whose memory shape is optimized for runtime lookup, not for transport density.
## Use Cases
@@ -1,7 +1,7 @@
# LSN-0022: Tilemap Empty Cell Semantics and Glyph Convergence
## Context
During the initial runtime design, `tile_id = 0` was used as a sentinel value for "empty" or "missing" tiles in tilemaps. However, as the asset banking and packer systems evolved, it became clear that `0` should be a valid index for any asset bank, including tile banks. This conflict was formally tracked in `AGD-0015`.
During the initial runtime design, `tile_id = 0` was used as a sentinel value for "empty" or "missing" tiles in tilemaps. However, as the asset banking and packer systems evolved, it became clear that `0` should be a valid index for any asset bank, including glyph banks. This conflict was formally tracked in `AGD-0015`.
## Lessons Learned
@@ -16,8 +16,8 @@ O uso de `serde_json::Value` diretamente nos loaders do runtime introduz riscos
Para mitigar isso, implementamos o padrão de **Typed Metadata Helpers**:
1. **Structs Dedicadas**: Criamos structs Rust (ex: `TilesMetadata`, `SoundsMetadata`) que representam o contrato exato de cada banco.
2. **Conversion Methods**: Adicionamos métodos ao `AssetEntry` (ex: `metadata_as_tiles()`) que utilizam `serde_json::from_value` para realizar o "cast" do JSON dinâmico para a struct tipada.
1. **Structs Dedicadas**: Criamos structs Rust (ex: `GlyphsMetadata`, `SoundsMetadata`) que representam o contrato exato de cada banco.
2. **Conversion Methods**: Adicionamos métodos ao `AssetEntry` (ex: `metadata_as_glyphs()`) que utilizam `serde_json::from_value` para realizar o "cast" do JSON dinâmico para a struct tipada.
3. **Fail-Fast**: A falha no parsing dos metadados deve ser tratada como erro de carregamento do asset, garantindo que o motor não opere com metadados corrompidos ou incompletos.
### Benefícios