dev/ajustments-asset-entry (#12)
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good

Reviewed-on: #12
Co-authored-by: bQUARKz <bquarkz@gmail.com>
Co-committed-by: bQUARKz <bquarkz@gmail.com>
This commit was merged in pull request #12.
This commit is contained in:
2026-04-10 05:31:57 +00:00
committed by bquarkz
parent c4aca95635
commit 035e9d5676
32 changed files with 584 additions and 813 deletions
+28 -19
View File
@@ -110,37 +110,46 @@ This table describes content identity and storage layout, not live residency.
### 4.1 `TILES` asset contract in v1
For `BankType::TILES`, the runtime-facing v1 contract is:
Para `BankType::TILES`, o contrato v1 voltado para o runtime é:
- `codec = NONE`
- serialized pixels use packed `u4` palette indices
- serialized palettes use `RGB565` (`u16`, little-endian)
- pixels serializados usam índices de paleta `u4` empacotados
- paletas serializadas usam `RGB565` (`u16`, little-endian)
- `palette_count = 64`
- runtime materialization may expand pixel indices to one `u8` per pixel
- a materialização em runtime pode expandir índices de pixel para um `u8` por pixel
`NONE` for `TILES` means there is no additional generic codec layer beyond the bank contract itself.
`NONE` para `TILES` significa que não há camada de codec genérica adicional além do próprio contrato do banco.
For the current transition window:
Para a janela de transição atual:
- `RAW` is a deprecated legacy alias of `NONE`
- new published material must use `NONE` as the canonical value
- `RAW` é um alias legado e depreciado de `NONE`
- novos materiais publicados devem usar `NONE` como valor canônico
Even with `codec = NONE`, `TILES` still requires deterministic bank-specific decode from its serialized payload. The serialized byte layout is therefore not required to be identical to the in-memory layout.
Mesmo com `codec = NONE`, `TILES` ainda requer decode específico de banco a partir de seu payload serializado. O layout de bytes serializados não precisa, portanto, ser idêntico ao layout em memória.
Required `AssetEntry.metadata` fields for `TILES`:
#### 4.1.1 Metadata Normalization
- `tile_size`: tile edge in pixels; valid values are `8`, `16`, or `32`
- `width`: full bank sheet width in pixels
- `height`: full bank sheet height in pixels
- `palette_count`: number of palettes serialized for the bank
Seguindo a `DEC-0004`, o campo `AssetEntry.metadata` deve ser estruturado de forma segmentada para evitar ambiguidades.
Validation rules for `TILES` v1:
Campos de metadados obrigatórios (efetivos) para `TILES` no nível raiz:
- `palette_count` must be `64`
- `width * height` defines the number of logical indexed pixels in the decoded sheet
- additional metadata may exist, but the runtime contract must not depend on it to reconstruct the bank in memory
- `tile_size`: aresta do tile em pixels; valores válidos são `8`, `16`, ou `32`
- `width`: largura total da folha do banco em pixels
- `height`: altura total da folha do banco em pixels
- `palette_count`: número de paletas serializadas para o banco
Serialized payload layout for `TILES` v1:
Subárvores opcionais e informativas:
- `metadata.codec`: Configuração específica do codec/compressor (ex: dicionários, flags de compressão).
- `metadata.pipeline`: Metadados informativos do processo de build do Studio (ex: source hashes, timestamps, tool versions).
Regras de validação para `TILES` v1:
- `palette_count` deve ser `64`
- `width * height` define o número de pixels indexados lógicos na folha decodificada
- metadados adicionais podem existir, mas o contrato do runtime não deve depender deles para reconstruir o banco em memória (exceto se definidos na raiz como campos efetivos).
#### 4.1.2 Payload Layout
1. packed indexed pixels for the full sheet, using `ceil(width * height / 2)` bytes;
2. palette table, using `palette_count * 16 * 2` bytes.