bQUARKz
dd6c9dd718
All checks were successful
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 60.67% (15274/25176)
* Branch Coverage: 53.64% (5782/10779)
* Lines of Code: 25176
* Cyclomatic Complexity: 9960
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 11, passed: 545
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
Reviewed-on: #3 Co-authored-by: bQUARKz <bquarkz@gmail.com> Co-committed-by: bQUARKz <bquarkz@gmail.com>
47 lines
2.0 KiB
Markdown
47 lines
2.0 KiB
Markdown
---
|
|
id: LSN-0015
|
|
ticket: packer-docs-import
|
|
title: Tile bank packing contract legacy lesson
|
|
created: 2026-03-26
|
|
tags:
|
|
- packer
|
|
- legacy-import
|
|
- tile-bank
|
|
- packing-contract
|
|
---
|
|
|
|
## 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`.
|