Glyph Bank Domain Naming Contract
This commit is contained in:
+5
-5
@@ -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:
|
||||
|
||||
|
||||
+5
-5
@@ -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
-1
@@ -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
|
||||
|
||||
|
||||
+2
-2
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user