dev/ajustments-asset-entry (#12)
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Reviewed-on: #12 Co-authored-by: bQUARKz <bquarkz@gmail.com> Co-committed-by: bQUARKz <bquarkz@gmail.com>
This commit was merged in pull request #12.
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
|
||||
|
||||
|
||||
+20
@@ -0,0 +1,20 @@
|
||||
# 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 glyph banks. This conflict was formally tracked in `AGD-0015`.
|
||||
|
||||
## Lessons Learned
|
||||
|
||||
### 1. Explicit Presence Over Magic Values
|
||||
Modeling absence with a magic value (like `tile_id = 0`) creates friction when that value is also a valid member of the domain (index 0). The project moved towards explicit presence checks.
|
||||
|
||||
### 2. Convergence During Parallel Implementation
|
||||
The resolution of the tilemap empty cell semantics (moving to explicit presence) was crystallized during the implementation of the `glyph` system. Instead of maintaining two different ways of handling "empty" slots, the tilemap logic was harmonized with the newer, cleaner approach used for glyphs and other render paths.
|
||||
|
||||
### 3. Impact on Render Pipeline
|
||||
By allowing `tile_id = 0` to be a valid tile, the render pipeline now relies on a separate bit or `Option`-like structure to determine if a cell should be drawn. This makes the code more robust and the asset indices more intuitive.
|
||||
|
||||
## References
|
||||
- Discussion: `DSC-0016`
|
||||
- Agenda: `AGD-0015` (Tilemap Empty Cell vs Tile ID Zero)
|
||||
- Implementation: Glyph system integration
|
||||
+33
@@ -0,0 +1,33 @@
|
||||
# LSN-0023: Typed Helpers for Asset Metadata
|
||||
|
||||
Status: Published
|
||||
Decisions: [[DEC-0004]]
|
||||
Tags: [asset, runtime, rust, pattern]
|
||||
|
||||
## Contexto
|
||||
|
||||
A decisão [[DEC-0004]] estabeleceu um contrato de metadados segmentados para assets, mantendo campos críticos na raiz do JSON e detalhes técnicos em subárvores (`codec`, `pipeline`). No entanto, o `AssetEntry.metadata` no runtime é um `serde_json::Value` dinâmico.
|
||||
|
||||
## Lição
|
||||
|
||||
O uso de `serde_json::Value` diretamente nos loaders do runtime introduz riscos de runtime (erros de tipo, campos ausentes) e polui o código com chamadas repetitivas de `.get()`, `.as_u64()`, etc.
|
||||
|
||||
### Abordagem Adotada
|
||||
|
||||
Para mitigar isso, implementamos o padrão de **Typed Metadata Helpers**:
|
||||
|
||||
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
|
||||
|
||||
- **Segurança de Tipo**: Erros de estrutura de metadados são detectados no momento do carregamento.
|
||||
- **Ergonomia**: O código dos drivers passa a usar `meta.tile_size` em vez de parsing manual.
|
||||
- **Desacoplamento**: A complexidade do JSON fica encapsulada nos helpers de conversão.
|
||||
|
||||
## Referências
|
||||
|
||||
- DEC-0004: Asset Entry Metadata Normalization Contract
|
||||
- `prometeu-hal/src/asset.rs`
|
||||
- `prometeu-drivers/src/asset.rs`
|
||||
+45
@@ -0,0 +1,45 @@
|
||||
---
|
||||
id: LSN-0024
|
||||
ticket: asset-entry-codec-enum-with-metadata
|
||||
title: String on the Wire, Enum in the Runtime
|
||||
created: 2026-04-09
|
||||
tags: [asset, runtime, codec, rust, contract]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
This discussion closed the contract for `AssetEntry.codec` in the runtime asset model. The system already serialized `assets.pa` as JSON produced by the Studio in Java, while the runtime consumed that JSON in Rust. The original runtime model kept `codec` as a free-form `String`, which allowed legacy aliases such as `RAW` and pushed validation and branching into scattered string comparisons.
|
||||
|
||||
The implemented change moved the runtime to a typed enum while preserving the existing transport simplicity of the pack format.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Asset Entry Codec Enum Contract
|
||||
|
||||
**What:**
|
||||
Keep `codec` as a JSON string in `assets.pa`, but deserialize it directly into a Rust enum in `AssetEntry`. The initial codec set contains only `None`, serialized canonically as `NONE` in `SCREAMING_SNAKE_CASE`.
|
||||
|
||||
**Why:**
|
||||
This preserves a simple cross-language wire contract for the Studio packer while making the runtime honest about the domain model it operates on. The loader now rejects unknown codecs early, and runtime consumers branch on enum variants instead of raw strings.
|
||||
|
||||
**Trade-offs:**
|
||||
The runtime loses open-ended tolerance for arbitrary codec names, which is intentional. Future codecs with payload-specific metadata still require a dedicated follow-up decision once a real codec exists.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Use a stable textual discriminant on the wire and a typed enum in the runtime model.
|
||||
- Let deserialization enforce the supported variant set instead of adding compatibility shims deeper in the execution path.
|
||||
- Keep the discriminant contract canonical across producers and consumers; do not allow per-producer aliases.
|
||||
- Preserve editorial or bank-specific metadata outside the codec discriminant so future codec payload metadata can be added without collapsing the whole asset model into an untyped blob.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- A runtime that accepts legacy aliases such as `RAW` keeps historical ambiguity alive and makes it harder to reason about the true contract.
|
||||
- If fixtures are constructed directly in tests, typed metadata helpers can expose missing required fields that were previously masked by weaker validation.
|
||||
- Cross-language contracts become fragile if the wire spelling is not explicitly canonized. The producer must conform exactly to the runtime contract.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Use a string on the wire when cross-language transport simplicity matters, but deserialize into an enum as soon as the runtime needs semantic guarantees.
|
||||
- Canonical spelling belongs to the shared contract, not to whichever producer happens to serialize first.
|
||||
- Rejecting unknown codec values at asset-entry validation time keeps failures local, early, and easier to debug.
|
||||
+45
@@ -0,0 +1,45 @@
|
||||
---
|
||||
id: LSN-0025
|
||||
ticket: tile-bank-vs-glyph-bank-domain-naming
|
||||
title: Rename Artifact by Meaning, Not by Token
|
||||
created: 2026-04-10
|
||||
tags: [gfx, runtime, naming, refactor, documentation]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
The runtime used `TileBank` as the name of the concrete graphical bank artifact while also using `tile` for map, layer, and geometric concepts such as `TileLayer`, `TileMap`, and `TileSize`. This overloaded the term `tile` across two different meanings.
|
||||
|
||||
The implemented migration renamed only the concrete bank artifact to `GlyphBank` and renamed the corresponding asset-bank contract from `BankType::TILES` to `BankType::GLYPH`, while explicitly preserving `TileLayer`, `TileMap`, and `TileSize`.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Glyph Bank Domain Naming Contract
|
||||
|
||||
**What:**
|
||||
Rename the concrete graphical bank artifact and its runtime interfaces to `GlyphBank`, but keep tile-domain structures unchanged where `tile` still correctly describes layers, maps, grids, and geometry.
|
||||
|
||||
**Why:**
|
||||
The goal was domain clarity, not behavior change. The project needed a more precise name for the concrete graphical bank without reopening rendering architecture or erasing valid uses of `tile`.
|
||||
|
||||
**Trade-offs:**
|
||||
This requires more care than a blind search-and-replace. The migration is broader editorially, but safer semantically, because it avoids damaging concepts that still belong in the tile domain.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
- Rename by artifact meaning, not by string token frequency.
|
||||
- When a term is overloaded, split the rename along domain boundaries instead of trying to enforce total lexical uniformity.
|
||||
- Let the runtime contract adopt the new canonical artifact name (`GlyphBank`, `BankType::GLYPH`) while preserving existing terms for excluded concepts (`TileLayer`, `TileMap`, `TileSize`).
|
||||
- Apply the same semantic rule to docs and lessons, not only to code.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Blind replacement would have incorrectly renamed tile-layer and tile-size concepts that were intentionally out of scope.
|
||||
- Partial renames create mixed vocabulary, which is worse than either old or new terminology used consistently.
|
||||
- Historical documentation is especially easy to corrupt if rewritten mechanically instead of by artifact meaning.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- A naming refactor can be rename-only in behavior while still requiring architectural discipline in wording.
|
||||
- Use one canonical name per artifact, but do not force unrelated domains to share that rename.
|
||||
- Documentation migrations should follow the same semantic boundary as code migrations, or the codebase will drift back into conceptual ambiguity.
|
||||
Reference in New Issue
Block a user