Asset Entry Metadata Normalization Contract
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user