2.0 KiB
| id | ticket | title | created | tags | ||||
|---|---|---|---|---|---|---|---|---|
| LSN-0015 | packer-docs-import | Tile bank packing contract legacy lesson | 2026-03-26 |
|
Context
Legacy import from docs/packer/learn/tile-bank-packing-contract.md.
This lesson preserves the first-wave producer contract for tile-bank assets.
Key Decisions
Tile bank packing emits one canonical payload per asset with explicit normalization and early structural validation
What: The first-wave contract emits one canonical GLYPH/indexed_v1 payload per asset, normalizes artifacts by explicit artifacts[*].index, packs one fixed 256 x 256 row-major sheet with packed u4 pixels and RGB565 palette blocks, treats palette identity as semantic rather than positional, and surfaces structural blockers early in walker/materialization.
Why: The repository needed one explicit producer contract for glyph banks rather than a mix of implicit artifact ordering, late byte-emission surprises, and unstable palette identity.
Trade-offs: This contract is more explicit and restrictive than ad hoc per-artifact packing, but it yields stable reviewability, predictable runtime metadata, and earlier validation.
Patterns and Algorithms
- Treat
1 artifact = 1 tile. - Normalize artifact identity by ascending declared
index. - Emit one canonical bank raster rather than concatenated artifact-local binaries.
- Keep palette identity explicit with
{ index, palette }. - Produce structural diagnostics before late pack-only phases.
Pitfalls
- Treating artifact declaration order as semantic tile identity.
- Embedding per-tile palette choice in packed payload.
- Flattening all metadata into one ambiguous map.
- Discovering tile-bank blockers only during final byte emission.
Takeaways
- The tile-bank producer contract depends on canonical normalization and early structural validation.
- Palette identity should be semantic and explicit, not positional by list order.
- Legacy source attribution:
docs/packer/learn/tile-bank-packing-contract.md.