packer (WIP)
This commit is contained in:
@@ -58,8 +58,39 @@ Contexto atual de código:
|
||||
- o snapshot atual já consegue expor arquivos candidatos e metadata de walk;
|
||||
- ainda não existe materialização final de payload de `tile bank` dentro de `assets.pa`.
|
||||
|
||||
Consumer baseline now confirmed in `../runtime`:
|
||||
|
||||
- `TILES` now uses `codec = NONE` as the runtime-facing v1 baseline;
|
||||
- serialized tile pixels are packed `u4` palette indices in payload order;
|
||||
- the runtime expands those packed indices into one `u8` logical index per pixel in memory after decode;
|
||||
- tile-bank palettes are serialized as `RGB565` `u16` values in little-endian order;
|
||||
- runtime-facing v1 uses `64` palettes per tile bank;
|
||||
- the runtime loader currently requires the following metadata fields for tile banks:
|
||||
- `tile_size`
|
||||
- `width`
|
||||
- `height`
|
||||
- `palette_count`
|
||||
- for v1, `palette_count` must be `64`;
|
||||
- for v1, the serialized tile-bank payload is:
|
||||
1. packed indexed pixels for the full sheet, using `ceil(width * height / 2)` bytes;
|
||||
2. one palette block of `64 * 16 * 2 = 2048` bytes;
|
||||
- for v1, the runtime-side size expectations are:
|
||||
- `size = ceil(width * height / 2) + 2048`
|
||||
- `decoded_size = (width * height) + 2048`
|
||||
- for the producer-side contract discussed here, `tile_id = 0` remains valid and must not be reserved away by the packer.
|
||||
|
||||
Relevant confirmed runtime references:
|
||||
|
||||
- [`../../../runtime/docs/runtime/specs/15-asset-management.md`](../../../runtime/docs/runtime/specs/15-asset-management.md)
|
||||
- [`../../../runtime/docs/runtime/specs/04-gfx-peripheral.md`](../../../runtime/docs/runtime/specs/04-gfx-peripheral.md)
|
||||
- [`../../../runtime/crates/console/prometeu-drivers/src/asset.rs`](../../../runtime/crates/console/prometeu-drivers/src/asset.rs)
|
||||
- [`../../../runtime/crates/console/prometeu-hal/src/tile_bank.rs`](../../../runtime/crates/console/prometeu-hal/src/tile_bank.rs)
|
||||
- tilemap empty-cell semantics remain under active runtime discussion and must not currently force the packer to reserve `tile_id = 0`:
|
||||
[`../../../runtime/docs/runtime/agendas/023-tilemap-empty-cell-vs-tile-id-zero.md`](../../../runtime/docs/runtime/agendas/023-tilemap-empty-cell-vs-tile-id-zero.md)
|
||||
|
||||
Isso significa que o problema agora não é descoberta de arquivos.
|
||||
É fechamento do contrato `tile bank -> runtime asset entry + payload bytes`.
|
||||
O lado consumidor já está suficientemente claro.
|
||||
O problema agora é fechar o contrato produtor `tile bank -> runtime asset entry + payload bytes` no packer sem contradizer esse baseline runtime.
|
||||
|
||||
## Options
|
||||
|
||||
@@ -104,10 +135,17 @@ O `tile bank` deve produzir um payload binário único por asset incluído no bu
|
||||
Regras recomendadas:
|
||||
|
||||
- o payload é derivado apenas dos artifacts selecionados que realmente entram no build atual;
|
||||
- a ordem de agregação dos artifacts deve ser determinística;
|
||||
- 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`;
|
||||
- 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`;
|
||||
2. bloco de paletas `64 * 16 * u16`;
|
||||
- palettes must always be materialized to `RGB565` during pack emission;
|
||||
- `size` deve representar o tamanho emitido no payload region;
|
||||
- `decoded_size` deve representar o tamanho lógico relevante para o runtime quando o codec exigir distinção entre payload armazenado e materialização decodificada.
|
||||
- `decoded_size` deve seguir a convenção runtime já confirmada:
|
||||
tamanho expandido dos indices em memória mais o bloco de paletas runtime-facing.
|
||||
|
||||
### Runtime Entry Recommendation
|
||||
|
||||
@@ -124,6 +162,18 @@ Cada `tile bank` emitido para o runtime deve preencher, no mínimo:
|
||||
|
||||
O contrato de `bank_type`, `codec` e `decoded_size` não deve ser deixado implícito no packer implementation detail.
|
||||
|
||||
Baseline now fixed by the runtime consumer:
|
||||
|
||||
- `bank_type = TILES`
|
||||
- `codec = NONE`
|
||||
- metadata mínima obrigatória:
|
||||
- `tile_size`
|
||||
- `width`
|
||||
- `height`
|
||||
- `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`
|
||||
|
||||
### Metadata Recommendation
|
||||
|
||||
`AssetEntry.metadata` deve receber apenas os campos runtime-consumable e format-relevant.
|
||||
@@ -131,7 +181,18 @@ O contrato de `bank_type`, `codec` e `decoded_size` não deve ser deixado implí
|
||||
Direção inicial recomendada:
|
||||
|
||||
- metadados declarativos como `tile_size` entram no sink runtime;
|
||||
- metadados derivados necessários para leitura correta do runtime também entram no sink runtime;
|
||||
- metadados derivados necessários para leitura correta do runtime entram no sink runtime, pelo menos:
|
||||
- `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`;
|
||||
- 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;
|
||||
- the packer must nevertheless validate whether the declared bank palette set safely covers the indices used by packed tiles.
|
||||
- detalhes de pipeline úteis apenas para inspeção e tooling não devem dominar `AssetEntry.metadata`;
|
||||
- quando um detalhe interno for necessário apenas para tooling, ele deve preferir companion tooling data em vez de inflar o contrato runtime.
|
||||
|
||||
@@ -145,6 +206,13 @@ O build de `tile bank` deve falhar quando qualquer uma das seguintes condições
|
||||
4. houver colisão ou ambiguidade ao convergir metadata runtime-facing;
|
||||
5. o packer não conseguir derivar de forma determinística os campos exigidos para a entry runtime.
|
||||
|
||||
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.
|
||||
|
||||
### Packing Boundary Recommendation
|
||||
|
||||
O seletor de packing para `tile bank` deve operar sobre os probes já descobertos pelo walker family-oriented.
|
||||
@@ -155,13 +223,21 @@ Regras:
|
||||
- a seleção do que entra no payload final acontece na policy/materialization layer de packing;
|
||||
- somente probes do asset registrado, incluído no build, e efetivamente selecionados pelo contrato do formato entram na materialização final;
|
||||
- quando o `PackerRuntimeMaterializationConfig` estiver em `PACKING`, esses probes relevantes devem carregar bytes opcionais preenchidos para congelar o input do pack.
|
||||
- palette declarations in `asset.json.output.pipeline.palettes` carry explicit semantic identity through `index`;
|
||||
- palette order is ascending numeric `index`, never raw array position;
|
||||
- palette ids are the normalized declared `index` values from that pipeline palette list;
|
||||
- all tiles in the bank may use any palette declared in the bank;
|
||||
- palette selection is a runtime draw concern, not a tile-payload embedding concern.
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. Qual é o payload canônico inicial de `TILES/indexed_v1`: tiles brutos indexados, tiles mais tabela auxiliar, ou outro envelope mínimo?
|
||||
2. Quais campos derivados além de `tile_size` precisam entrar em `AssetEntry.metadata` já na primeira versão?
|
||||
3. `decoded_size` para `tile bank` deve refletir bytes lógicos pós-codec, bytes efetivos em bank, ou ambos via combinação `decoded_size + metadata`?
|
||||
4. O formato inicial do payload precisa carregar múltiplos sub-blocos internos explícitos ou um stream único já é suficiente para `v1`?
|
||||
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?
|
||||
|
||||
## Expected Follow-up
|
||||
|
||||
|
||||
Reference in New Issue
Block a user