diff --git a/docs/runtime/agendas/023-tilemap-empty-cell-vs-tile-id-zero.md b/docs/runtime/agendas/023-tilemap-empty-cell-vs-tile-id-zero.md new file mode 100644 index 00000000..469e1505 --- /dev/null +++ b/docs/runtime/agendas/023-tilemap-empty-cell-vs-tile-id-zero.md @@ -0,0 +1,99 @@ +# Tilemap Empty Cell vs Tile ID Zero + +## Contexto + +O runtime hoje usa `tile.id == 0` como atalho para "tile ausente" no caminho de render de tilemap. + +Ao mesmo tempo, o contrato de `tile bank` em evolucao no packer quer permitir que `tile_id = 0` seja um tile real e valido dentro do bank. + +Isso cria conflito direto entre: + +- semantica atual do tilemap no runtime; +- e o contrato de packing/runtime asset bank que trata `tile_id` como indice valido do bank desde zero. + +## Problema + +Precisamos decidir qual e a semantica correta para representar ausencia de tile em tilemaps. + +Hoje o comportamento implicito e: + +- `tile.id == 0` significa "nao desenhar"; +- portanto o tile de indice `0` no bank fica inutilizavel no caminho de tilemap; +- sprites, por outro lado, nao carregam a mesma semantica implicita de vazio. + +Isso deixa o modelo inconsistente: + +1. o mesmo `tile_id` nao significa a mesma coisa em todos os consumidores; +2. o bank `TileBank` nao explicita reserva de `tile_id = 0`; +3. o packer teria que compensar uma regra de consumidor que nao esta modelada no contrato do asset bank. + +## Pontos Criticos + +- `tile_id` deve representar um indice valido no bank, nao um sentinel escondido, sempre que possivel; +- ausencia de tile e um conceito de tilemap/layer, nao necessariamente de bank asset; +- usar indices fora da faixa como sentinel tende a piorar validacao e debug; +- mudar o shape do tilemap pode ter custo de ABI/runtime, mas pode deixar o contrato mais honesto; +- manter o comportamento atual preserva compatibilidade local, mas cristaliza uma semantica implicita fraca. + +## Opcoes + +### Opcao A - Manter `tile.id == 0` como empty sentinel + +O runtime segue tratando `tile_id = 0` como ausencia de tile no tilemap. + +Consequencia: + +- o primeiro tile real do bank precisaria comecar em `1` para o caminho de tilemap; +- o packer precisaria compensar isso; +- sprites e tilemaps continuariam com semanticas diferentes para o mesmo id. + +### Opcao B - Tornar vazio explicito no tilemap model + +O tilemap passa a representar vazio explicitamente, por exemplo com: + +- `Option`; +- ou `Tile { active/present, ... }`. + +Consequencia: + +- `tile_id = 0` volta a ser um tile valido no bank; +- ausencia de tile deixa de depender de valor especial do id; +- o runtime fica semanticamente mais consistente. + +### Opcao C - Usar sentinel fora da faixa valida + +O tilemap passa a tratar um `tile_id >= tile_capacity` como "empty". + +Consequencia: + +- evita usar `0` como sentinel; +- mas cria acoplamento ruim entre tilemap e capacidade do bank; +- e torna a validacao mais fragil e menos didatica. + +## Sugestao / Recomendacao + +Adotar `Opcao B`. + +Ausencia de tile deve ser modelada explicitamente no tilemap/layer, e nao por um `tile_id` especial. + +Direcao recomendada: + +1. `tile_id` deve significar apenas "indice do tile no bank"; +2. `tile_id = 0` deve ser permitido como tile real; +3. tilemaps devem ter vazio explicito no proprio modelo; +4. o render do tilemap deve testar esse estado explicito, nao `tile.id == 0`. + +## Perguntas em Aberto + +1. Qual shape e melhor para o primeiro wave: + `Option` ou `Tile` com flag `active/present`? +2. Essa mudanca afeta apenas o tilemap path ou tambem deve harmonizar outros consumidores do modelo `Tile`? +3. Precisamos de estrategia de compatibilidade/migracao para codigo e testes que hoje assumem `tile.id == 0` como vazio? + +## Criterio para Encerrar + +Esta agenda pode ser encerrada quando houver decisao clara sobre: + +- como vazio e representado no tilemap; +- se `tile_id = 0` volta a ser indice valido universal do bank; +- e quais pontos de spec/codigo do runtime precisam de propagacao. diff --git a/docs/runtime/agendas/024-asset-entry-metadata-normalization-contract.md b/docs/runtime/agendas/024-asset-entry-metadata-normalization-contract.md new file mode 100644 index 00000000..e3bf00e9 --- /dev/null +++ b/docs/runtime/agendas/024-asset-entry-metadata-normalization-contract.md @@ -0,0 +1,89 @@ +# 024-asset-entry-metadata-normalization-contract + +Status: Open +Domain Owner: `docs/runtime` +Cross-Domain Impact: `../studio/docs/packer`, `shipper`, `asset` loader + +## Purpose + +Normatizar como `AssetEntry.metadata` deve preservar a convergencia entre metadata autoral, metadata de codec e metadata de pipeline sem colapsar tudo num mapa plano ambiguo. + +## Problem + +O lado produtor (`packer`) ja convergiu para um contrato em que o runtime precisa ler campos obrigatorios diretamente de `AssetEntry.metadata`, mas tambem precisa manter segmentacao suficiente para nao perder significado entre: + +- `asset.json.output.metadata` +- `asset.json.output.codec_configuration` +- `asset.json.output.pipeline` + +Sem um contrato explicito no runtime: + +- o packer pode materializar estruturas diferentes entre formatos; +- o loader/runtime pode passar a depender de flattening incidental; +- tooling e debug surfaces perdem previsibilidade; +- futuros formatos tendem a misturar metadata efetiva com detalhe interno de pipeline. + +## Context + +No ciclo atual de `tile bank`, o produtor ja fechou esta direcao: + +- `asset.json.output.metadata` -> `AssetEntry.metadata` +- `asset.json.output.codec_configuration` -> `AssetEntry.metadata.codec` +- `asset.json.output.pipeline` -> `AssetEntry.metadata.pipeline` + +Ao mesmo tempo, o runtime ainda consome alguns campos obrigatorios do tile bank diretamente no nivel raiz de `AssetEntry.metadata`, em especial: + +- `tile_size` +- `width` +- `height` +- `palette_count` + +A agenda precisa fechar se esse shape vira contrato geral de runtime para metadata normalizada de assets, e como o consumidor deve tratar campos obrigatorios format-specific versus subtrees segmentadas. + +## Options + +### Option A - Flat effective metadata map only + +Tudo converge para um unico mapa plano em `AssetEntry.metadata`. + +### Option B - Root effective metadata plus stable segmented subtrees + +Campos runtime-obrigatorios ficam legiveis no nivel raiz, enquanto dados de codec e pipeline ficam em subtrees estaveis: + +- `metadata.` +- `metadata.codec.` +- `metadata.pipeline.` + +### Option C - Fully segmented metadata only + +Nada fica no nivel raiz; todo consumo passa por subtrees por origem. + +## Tradeoffs + +- Option A simplifica leitura curta, mas perde origem semantica e aumenta risco de colisao. +- Option B preserva leitura direta para campos obrigatorios do runtime e mantem segmentacao estavel para evolucao futura. +- Option C e semanticamente limpa, mas quebra o consumo direto atual de formatos como `tile bank` e introduz custo de migracao desnecessario agora. + +## Recommendation + +Adotar `Option B`. + +Direcao recomendada: + +- campos format-specific obrigatorios para decode/runtime continuam legiveis no nivel raiz de `AssetEntry.metadata`; +- `output.codec_configuration` materializa em `AssetEntry.metadata.codec`; +- `output.pipeline` materializa em `AssetEntry.metadata.pipeline`; +- o runtime nao deve exigir flattening total para consumir metadata segmentada; +- specs format-specific devem declarar explicitamente quais campos sao obrigatorios no nivel raiz. + +## Open Questions + +1. O contrato deve tratar o subtree raiz como semanticamente equivalente a `output.metadata` ou como effective metadata map mais amplo? +2. Quais readers/helpers do runtime devem ser criados para evitar parsing manual disperso de `metadata.codec` e `metadata.pipeline`? + +## Expected Follow-up + +1. Converter esta agenda em decision no `runtime`. +2. Propagar a decisao para `15-asset-management.md`. +3. Ajustar loaders format-specific para usar helpers consistentes de metadata quando necessario. +4. Alinhar o `packer` e testes de conformance com o shape final. diff --git a/docs/runtime/agendas/README.md b/docs/runtime/agendas/README.md index 50c745d0..f5801110 100644 --- a/docs/runtime/agendas/README.md +++ b/docs/runtime/agendas/README.md @@ -24,6 +24,7 @@ As agendas atuais são: - `020-perf-host-debug-overlay-isolation.md` - `021-perf-vm-allocation-and-copy-pressure.md` - `022-perf-cartridge-boot-and-program-ownership.md` +- `024-asset-entry-metadata-normalization-contract.md` ## Sequenciamento Recomendado [PERF] Ordem sugerida para discussao das agendas de performance: @@ -87,3 +88,4 @@ Regra de uso: - se a implementação exigir decisão estrutural, ela deve nascer daqui antes de virar PR de código; - se uma agenda já estiver resolvida, a PR derivada deve citar explicitamente qual decisão foi tomada; - se a agenda revelar ambiguidade demais, ela não deve ser convertida em PR até o alvo ficar preciso. +