88 lines
3.5 KiB
Markdown
88 lines
3.5 KiB
Markdown
# 013 Tile Bank Runtime Contract Alignment
|
|
|
|
## Briefing
|
|
|
|
O runtime hoje tem divergencia entre especificacao e implementacao para `tile bank`.
|
|
|
|
O objetivo desta PR e fechar o contrato runtime-side que o packer deve atender antes de prosseguir com a materializacao definitiva de `tile bank` em `assets.pa`.
|
|
|
|
Em especial, o repositorio precisa alinhar:
|
|
|
|
- representacao serializada de indices de pixel;
|
|
- cardinalidade de paletas por bank;
|
|
- shape minimo de metadata usado pelo loader;
|
|
- e semantica de `codec` / `decoded_size` para `TILES`.
|
|
|
|
## Decisions de Origem
|
|
|
|
- `docs/packer/decisions/Pack Wizard Pack Execution Semantics Decision.md`
|
|
- discussao em andamento no packer sobre `Tile Bank Packing Materialization`
|
|
|
|
## Alvo
|
|
|
|
Alinhar o contrato normativo do runtime para `tile bank` v1 com a direcao:
|
|
|
|
1. indices serializados como `u4` packed em `assets.pa`;
|
|
2. paletas serializadas como `RGB565 (u16 little-endian)`;
|
|
3. baseline v1 com `64` paletas por bank;
|
|
4. `palette_id` valido em `0..63`;
|
|
5. `codec = RAW` para tile bank no primeiro wave;
|
|
6. metadata minima suficiente para o loader reconstruir o bank em memoria.
|
|
|
|
## Escopo
|
|
|
|
- revisar `docs/runtime/specs/04-gfx-peripheral.md`
|
|
- revisar `docs/runtime/specs/15-asset-management.md`
|
|
- revisar `docs/runtime/specs/13-cartridge.md` somente se necessario para coerencia de referencia
|
|
- explicitar o contrato runtime-facing de tile bank em termos de:
|
|
- layout serializado;
|
|
- layout em memoria;
|
|
- limites de paleta;
|
|
- metadata minima;
|
|
- `decoded_size`
|
|
|
|
## Fora de Escopo
|
|
|
|
- implementar codigo do loader ou do driver
|
|
- ampliar o numero de paletas para `256`
|
|
- definir formatos comprimidos para `tile bank`
|
|
- definir `tilemap bank`
|
|
- redesenhar o modelo de GFX alem do necessario para coerencia do contrato
|
|
|
|
## Plano de Execucao
|
|
|
|
1. Auditar e registrar as divergencias atuais entre `specs/04`, `specs/15` e o codigo runtime.
|
|
2. Consolidar um baseline unico para `tile bank` v1:
|
|
- payload serializado com indices `u4` packed
|
|
- paletas `64 * 16 * u16`
|
|
- `palette_id` em `0..63`
|
|
3. Explicitar que a representacao em memoria pode continuar expandida para `u8` por pixel mesmo quando a forma serializada usa `u4`.
|
|
4. Definir metadata minima obrigatoria em `AssetEntry.metadata` para tiles:
|
|
- `tile_size`
|
|
- `width`
|
|
- `height`
|
|
- `palette_count`
|
|
- outros campos apenas se realmente necessarios para reconstruir o bank
|
|
5. Fechar a semantica de `decoded_size` para `tile bank` v1.
|
|
6. Revisar exemplos e linguagem normativa para remover contradicoes internas.
|
|
|
|
## Criterios de Aceite
|
|
|
|
- `docs/runtime/specs/04-gfx-peripheral.md` nao contradiz mais o limite de paletas efetivo de `tile bank`
|
|
- `docs/runtime/specs/04-gfx-peripheral.md` define `4bpp` packed como forma serializada do payload
|
|
- `docs/runtime/specs/15-asset-management.md` deixa claro o contrato runtime-facing necessario para reconstruir `TileBank`
|
|
- a distincao entre forma serializada e forma em memoria fica explicita
|
|
- a semantica de `palette_id` e `decoded_size` fica fechada para `tile bank` v1
|
|
|
|
## Tests / Validacao
|
|
|
|
- revisao editorial cruzada entre `specs/04`, `specs/13` e `specs/15`
|
|
- checklist de coerencia contra o codigo existente do loader/runtime
|
|
- validacao com a agenda/decision do packer para garantir que o contrato e implementavel pelo `assets.pa`
|
|
|
|
## Riscos
|
|
|
|
- cristalizar cedo demais um limite de paletas que depois precise ser ampliado
|
|
- documentar `decoded_size` de forma utilitaria demais e gerar custo futuro em telemetry/budget
|
|
- deixar ambiguo o que pertence ao payload versus o que pertence ao `metadata`
|