clean up
This commit is contained in:
parent
7b7a633ef4
commit
d4b8229981
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -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<Tile>`;
|
||||
- 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<Tile>` 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.
|
||||
@ -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.<field>`
|
||||
- `metadata.codec.<field>`
|
||||
- `metadata.pipeline.<field>`
|
||||
|
||||
### 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.
|
||||
@ -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.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user