77 lines
3.0 KiB
Markdown
77 lines
3.0 KiB
Markdown
# 014 Tile Bank Loader Packed Nibbles and Palette Boundary
|
|
|
|
## Briefing
|
|
|
|
O codigo do runtime hoje ainda decodifica `tile bank` como:
|
|
|
|
- `1 byte` por pixel indexado;
|
|
- `2048` bytes fixos de paleta;
|
|
- validacao efetiva de `palette_id` em `0..63`.
|
|
|
|
Se o contrato v1 sera `u4` packed + `RGB565 u16`, o loader e os pontos de validacao do runtime precisam ser corrigidos antes de seguir com o packer-side materialization.
|
|
|
|
## Decisions de Origem
|
|
|
|
- `013-tile-bank-runtime-contract-alignment.md`
|
|
- `docs/packer/decisions/Pack Wizard Pack Execution Semantics Decision.md`
|
|
|
|
## Alvo
|
|
|
|
Atualizar o codigo do runtime para consumir `tile bank` v1 como:
|
|
|
|
1. indices de pixel `u4` packed no payload serializado;
|
|
2. paletas `RGB565 (u16 little-endian)`;
|
|
3. `64` paletas por bank no primeiro wave;
|
|
4. representacao expandida em memoria para `Vec<u8>` somente apos decode;
|
|
5. validacao coerente de `palette_id` no ABI/runtime.
|
|
|
|
## Escopo
|
|
|
|
- atualizar decode de `tile bank` em `prometeu-drivers/src/asset.rs`
|
|
- revisar comentarios e invariantes em `prometeu-hal/src/tile_bank.rs`
|
|
- revisar pontos de validacao e range de `palette_id` no runtime path
|
|
- ajustar testes existentes do runtime que assumem payload `u8` por pixel
|
|
|
|
## Fora de Escopo
|
|
|
|
- introduzir compressao para `tile bank`
|
|
- ampliar `palette_count` para `256`
|
|
- mudar o modelo de `TileBank` para armazenar nibbles packed em memoria
|
|
- mudar o contrato de `sound bank`
|
|
- definir ou implementar `tilemap bank`
|
|
|
|
## Plano de Execucao
|
|
|
|
1. Alterar o decode do payload de `tile bank` para calcular o tamanho esperado de indices como `(width * height + 1) / 2`.
|
|
2. Implementar unpack deterministico de nibbles para a representacao em memoria `Vec<u8>`.
|
|
3. Preservar a leitura das paletas como `u16 little-endian`.
|
|
4. Tornar explicita a quantidade de paletas suportadas em v1 no codigo, evitando magic numbers soltos.
|
|
5. Revisar comentarios/documentacao inline em `TileBank` para diferenciar:
|
|
- payload serializado
|
|
- representacao expandida em memoria
|
|
6. Ajustar testes para cobrir:
|
|
- unpack correto de nibbles
|
|
- transparencias (`0`)
|
|
- limites de paleta
|
|
- rejeicao de buffer curto
|
|
|
|
## Criterios de Aceite
|
|
|
|
- o loader de `tile bank` nao assume mais `1 byte` por pixel no payload serializado
|
|
- o runtime reconstrui corretamente `pixel_indices: Vec<u8>` a partir de nibbles packed
|
|
- o bloco de paletas continua sendo lido como `RGB565 u16 little-endian`
|
|
- o range efetivo de `palette_id` fica coerente com o contrato v1 de `64` paletas
|
|
- os testes do runtime cobrem o novo layout e falhas de tamanho insuficiente
|
|
|
|
## Tests / Validacao
|
|
|
|
- testes unitarios do decode de `tile bank`
|
|
- testes de roundtrip do loader usando payload sintetico
|
|
- validacao de compatibilidade com o contrato normativo atualizado em `docs/runtime/specs`
|
|
|
|
## Riscos
|
|
|
|
- unpack incorreto de nibbles gerar corrupcao visual silenciosa
|
|
- confusao entre `decoded_size` logico e tamanho serializado do payload
|
|
- deixar o codigo parcialmente alinhado com a spec, mas com ranges de ABI ainda antigos ou contraditorios
|