packer (WIP)

This commit is contained in:
2026-03-24 13:42:56 +00:00
parent db8c17864f
commit 67edeaab78
3 changed files with 236 additions and 15 deletions
@@ -138,6 +138,12 @@ Regras recomendadas:
- a ordem de agregação dos artifacts deve ser determinística by `artifacts[*].index`;
- for v1, `1 artifact = 1 tile`;
- for the current target, the canonical tile-bank sheet is always `256 x 256`;
- tile placement inside that fixed sheet is row-major;
- `tile_id` is the linear row-major slot and therefore matches the normalized `artifacts[*].index`;
- resulting capacity is therefore:
- `tile_size = 8` -> `32 x 32 = 1024` tiles
- `tile_size = 16` -> `16 x 16 = 256` tiles
- `tile_size = 32` -> `8 x 8 = 64` tiles
- o payload final do asset deve ter fronteiras e interpretação definidas pelo próprio contrato do formato, não por convenção incidental de concatenação;
- para `TILES/indexed_v1`, o payload v1 já deve assumir:
1. plano de pixels packed `u4`;
@@ -173,6 +179,10 @@ Baseline now fixed by the runtime consumer:
- `palette_count = 64`
- `width` and `height` are bank-sheet helpers, not per-artifact dimensions
- with the current v1 target, the emitted bank sheet is fixed at `256 x 256`
- producer-side metadata normalization must emit what the consumer requires while preserving segmented authoring meaning:
- `asset.json.output.metadata` -> `AssetEntry.metadata`
- `asset.json.output.codec_configuration` -> `AssetEntry.metadata.codec`
- `asset.json.output.pipeline` -> `AssetEntry.metadata.pipeline`
### Metadata Recommendation
@@ -185,10 +195,10 @@ Direção inicial recomendada:
- `width`
- `height`
- `palette_count`;
- `AssetEntry.metadata` should aggregate normalized maps derived from:
- `asset.json.output.metadata`
- `asset.json.output.codec_configuration`
- `asset.json.output.pipeline`;
- `AssetEntry.metadata` should aggregate normalized maps using this structure:
- `asset.json.output.metadata` -> `metadata`
- `asset.json.output.codec_configuration` -> `metadata.codec`
- `asset.json.output.pipeline` -> `metadata.pipeline`
- bank palettes are declared in `asset.json.output.pipeline.palettes` using explicit `{ index, palette }` entries and emitted in ascending numeric `index` order;
- any tile in the bank may be rendered with any palette in the bank;
- palette assignment is therefore not a per-artifact packing contract and remains a runtime draw-time concern;
@@ -208,10 +218,14 @@ O build de `tile bank` deve falhar quando qualquer uma das seguintes condições
Additional first-wave diagnostic expectations:
- bank without declared palettes in `asset.json.output.pipeline.palettes` must emit a diagnostic;
- tile banks whose declared palette list exceeds `64` must fail;
- tiles that use fragile indices, meaning indices not represented safely across the full declared bank palette set, should emit a `WARNING`;
- that fragile-index warning is advisory in the first wave and should not block pack by itself unless later promoted by decision.
- duplicate `artifacts[*].index` is `blocking`;
- gap in normalized `artifacts[*].index` ordering is `blocking`;
- sheet-capacity overflow for the fixed `256 x 256` target is `blocking`;
- bank without declared palettes in `asset.json.output.pipeline.palettes` is `blocking`;
- declared palette list above `64` is `blocking`;
- malformed palette declarations are `blocking`;
- tiles that use fragile indices, meaning indices not represented safely across the full declared bank palette set, emit a `WARNING`;
- that fragile-index warning is advisory in the first wave and does not block pack by itself unless later promoted by decision.
### Packing Boundary Recommendation
@@ -231,13 +245,7 @@ Regras:
## Open Questions
1. Given the fixed `256 x 256` bank target, what is the canonical tile placement rule inside that sheet for `tile_size = 8`, `16`, and `32`?
2. Which normalization diagnostics should be `blocking` versus `warning` specifically for:
- artifact index gaps or duplicates
- sheet capacity overflow
- palette list overflow beyond `64`
- banks without declared palettes
- fragile tile indices across the declared bank palette set?
1. None at this stage for the tile-bank v1 producer contract.
## Expected Follow-up