Intrepid/prometeu-studio
Intrepid/prometeu-studio
3
0
Fork 0
Code Pull Requests 1 Activity
prometeu-studio/discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md
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.
Details
Test / Build skipped: 11, passed: 545
Details
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
Details
dev/glyph-bank-alignment (#3) 
Reviewed-on: #3
Co-authored-by: bQUARKz <bquarkz@gmail.com>
Co-committed-by: bQUARKz <bquarkz@gmail.com>
2026-04-10 06:14:07 +00:00

2.0 KiB
Raw Blame History

id ticket title created tags
LSN-0015 packer-docs-import Tile bank packing contract legacy lesson 2026-03-26
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.