222 lines
10 KiB
Markdown
222 lines
10 KiB
Markdown
---
|
|
id: AGD-0020
|
|
ticket: tile-bank-vs-glyph-bank-domain-naming
|
|
title: Agenda - Tile Bank vs Glyph Bank Domain Naming
|
|
status: accepted
|
|
created: 2026-04-09
|
|
resolved: 2026-04-10
|
|
decision: DEC-0006
|
|
tags: [gfx, runtime, naming, domain-model]
|
|
---
|
|
|
|
# Agenda - Tile Bank vs Glyph Bank Domain Naming
|
|
|
|
## Contexto
|
|
|
|
Hoje o runtime usa `TileBank`, `tile_bank.rs`, `TileBankPool*` e termos derivados para nomear o banco grafico consumido pelo renderer e pelo pipeline de assets.
|
|
|
|
Ao mesmo tempo, existe a vontade de elevar `Tile` para um conceito mais amplo do dominio, nao restrito ao sheet grafico concreto. Nessa leitura:
|
|
|
|
- `Tile` passa a ser uma ideia mais geral da grade/elemento logico;
|
|
- o que hoje e o artefato grafico concreto chamado `TileBank` deveria passar a se chamar `GlyphBank`;
|
|
- a intencao inicial nao e mudar formato, memoria, payload ou algoritmo, e sim alinhar a linguagem do projeto.
|
|
|
|
Esse tema ja encosta em documentacao e lessons existentes, porque o vocabulario atual mistura:
|
|
|
|
- tile como unidade de composicao visual;
|
|
- tile bank como sheet grafico concreto;
|
|
- referencias esparsas a glyph em lições e agendas.
|
|
|
|
## Problema
|
|
|
|
Se o projeto mudar o centro semantico de `tile` e `glyph` sem uma decisao explicita, o repositorio tende a ficar com vocabulário hibrido:
|
|
|
|
- tipos antigos com nome legado;
|
|
- docs novas com nome novo;
|
|
- renderer e assets falando uma lingua;
|
|
- lessons e discussoes falando outra.
|
|
|
|
O problema principal nao e tecnico-algoritmico. E semantico e operacional: qual vocabulario o projeto quer tornar canonico para o banco grafico concreto, e qual parte dessa mudanca e apenas rename mecanico versus mudanca real de modelo.
|
|
|
|
## Pontos Criticos
|
|
|
|
1. Escopo da mudanca.
|
|
Precisamos separar rename de dominio de qualquer mudanca de formato ou comportamento.
|
|
|
|
2. Contrato externo.
|
|
Precisamos fechar quais contratos externos tambem entram no rename. Ja existe direcao para migrar `BankType::TILES` para `BankType::GLYPH`.
|
|
|
|
3. Consistencia de linguagem.
|
|
A mudanca so vale a pena se atingir codigo, tests, docs e lessons de forma coordenada.
|
|
|
|
4. Custo de churn.
|
|
Mesmo sem mudar comportamento, o rename atravessa muitos modulos (`hal`, `drivers`, renderer, pools, mensagens de erro, tests e docs).
|
|
|
|
5. Fronteira conceitual.
|
|
Precisamos definir o que `Tile` passa a significar depois do rename, para evitar trocar um overload semantico por outro.
|
|
|
|
## Opcoes
|
|
|
|
### Opcao A - Manter `TileBank` como esta
|
|
|
|
- **Abordagem:** preservar `TileBank` como nome canonico do banco grafico concreto e aceitar que `tile` continue carregando tanto o lado logico quanto o lado visual.
|
|
- **Pro:** zero churn nominal imediato e nenhuma migracao de docs/codigo.
|
|
- **Con:** o overload conceitual de `tile` permanece e pode continuar poluindo a linguagem de dominio.
|
|
- **Tradeoff:** economiza trabalho agora ao custo de clareza futura.
|
|
|
|
### Opcao B - Renomear `TileBank` para `GlyphBank` como refactor semantico
|
|
|
|
- **Abordagem:** tratar a mudanca como rename consistente de tipos, modulos, docs, testes e mensagens, sem alterar formato de payload, layout em memoria ou renderer.
|
|
- **Pro:** melhora a linguagem do projeto sem reabrir a arquitetura grafica.
|
|
- **Con:** exige disciplina para manter a promessa de “rename only” e nao misturar isso com redesign.
|
|
- **Tradeoff:** churn mecanico relativamente alto para ganhar clareza conceitual.
|
|
|
|
### Opcao C - Fazer rename parcial
|
|
|
|
- **Abordagem:** adotar `glyph` apenas em docs novas ou em algumas camadas, preservando nomes antigos em APIs e modulos centrais.
|
|
- **Pro:** menor custo inicial.
|
|
- **Con:** cria o pior estado intermediario: dois vocabulários concorrentes para o mesmo conceito.
|
|
- **Tradeoff:** parece barato, mas deixa a linguagem do projeto menos confiavel.
|
|
|
|
## Sugestao / Recomendacao
|
|
|
|
Seguir inicialmente com a **Opcao B**, desde que a discussao confirme que a mudanca e de nomenclatura e nao de semantica operacional.
|
|
|
|
A recomendacao provisoria e:
|
|
|
|
- `GlyphBank` se torna o nome do artefato grafico concreto que hoje chamamos de `TileBank`;
|
|
- `Tile` fica livre para representar um conceito mais geral do dominio;
|
|
- `BankType::TILES` passa a `BankType::GLYPH`;
|
|
- a migracao deve ser consistente em codigo, tests, docs e lessons;
|
|
- `TileLayer` e derivados nao entram automaticamente no rename, porque ja pertencem a outra fronteira de dominio e precisam de triagem separada;
|
|
- a discussao deve explicitar quais superfícies mudam juntas para impedir vocabulario hibrido sem reabrir a arquitetura grafica.
|
|
|
|
## Perguntas em Aberto
|
|
|
|
- Confirmar a superficie exata do rename para evitar misturar banco grafico concreto com conceitos de layer/mapa.
|
|
|
|
## Discussao
|
|
|
|
### Direcao fechada ate aqui
|
|
|
|
1. **Natureza da mudanca**
|
|
A mudanca e `rename-only`. Nao ha intencao de alterar formato, algoritmo, layout em memoria ou comportamento.
|
|
|
|
2. **Contrato externo**
|
|
`BankType::TILES` nao deve permanecer. O contrato deve migrar para `BankType::GLYPH`.
|
|
|
|
3. **Escopo documental**
|
|
A migracao deve ser completa, inclusive em documentacao e lessons historicas.
|
|
|
|
4. **Colisao semantica**
|
|
`glyph` nao colide com outro artefato canonico relevante nesta etapa.
|
|
|
|
### Fronteira importante
|
|
|
|
Nem todo `Tile*` deve migrar automaticamente para `Glyph*`.
|
|
|
|
Existe uma fronteira entre:
|
|
|
|
- nomes que descrevem o banco grafico concreto e seu circuito de carga/uso; e
|
|
- nomes que ja descrevem dominio de layer, mapa, grade ou composicao.
|
|
|
|
Por isso, a proxima resposta que falta precisa ser dada por superficie concreta, e nao por regra global simplista.
|
|
|
|
### Lista para voto `sim` / `nao`
|
|
|
|
Responda `sim` ou `nao` para cada grupo abaixo.
|
|
|
|
1. **Banco concreto e modulo base**
|
|
Inclui `TileBank`, `tile_bank.rs`, comentarios e docs especificos desse tipo.
|
|
|
|
2. **Enum e contrato de asset**
|
|
Inclui `BankType::TILES -> BankType::GLYPH`, mensagens de erro, metadata helpers e referencias equivalentes no path de assets.
|
|
|
|
3. **Pools e interfaces de memoria**
|
|
Inclui `TileBankPoolAccess`, `TileBankPoolInstaller`, `tile_bank_slot`, `install_tile_bank`, campos internos como `tile_bank_pool`.
|
|
|
|
4. **Asset manager e loader path**
|
|
Inclui funcoes como `decode_tile_bank_*`, `perform_load_tile_bank`, variaveis locais, testes e mensagens associadas ao load do banco grafico.
|
|
|
|
5. **Renderer e hardware references ao banco**
|
|
Inclui usos em `gfx.rs` e `hardware.rs` que referenciam o banco concreto, por exemplo campos `tile_banks`, docs sobre VRAM `TileBanks`, parametros `bank: &TileBank`.
|
|
|
|
6. **Modulo e tipos de layer/mapa**
|
|
Inclui `tile_layer.rs`, `TileMap`, `TileLayer`, `ScrollableTileLayer`, `HudTileLayer`.
|
|
Este grupo e o mais sensivel porque pode nao ser rename de banco concreto, e sim outro dominio.
|
|
|
|
7. **TileSize**
|
|
Inclui `TileSize` e referencias ao tamanho de tile como unidade geometrica.
|
|
Este grupo pode continuar como `TileSize` mesmo se o banco virar `GlyphBank`.
|
|
|
|
8. **Strings, fixtures e test names**
|
|
Inclui nomes de testes, helper names, snapshots, mensagens e dados de teste que ainda falam em tile bank.
|
|
|
|
9. **Lessons e docs historicas**
|
|
Inclui lessons ja publicadas e material de discussao/mental model que hoje falam em `TileBank`.
|
|
|
|
### Votos registrados
|
|
|
|
1. **Banco concreto e modulo base**: `sim`
|
|
`TileBank`, `tile_bank.rs`, modulo base e documentacao associada entram na migracao.
|
|
|
|
2. **Enum e contrato de asset**: `sim`
|
|
`BankType::TILES` e o contrato textual equivalente entram na migracao para `GLYPH`.
|
|
|
|
3. **Pools e interfaces de memoria**: `sim`
|
|
`TileBankPool*`, `tile_bank_slot` e derivados entram na migracao.
|
|
|
|
4. **Asset manager e loader path**: `sim`
|
|
Helpers, decode path, mensagens e testes associados ao banco grafico concreto entram na migracao.
|
|
|
|
5. **Renderer e hardware references ao banco**: `sim`
|
|
Referencias ao banco concreto em renderer e hardware entram na migracao.
|
|
|
|
6. **Modulo e tipos de layer/mapa**: `nao`
|
|
`TileLayer`, `TileMap`, `ScrollableTileLayer` e `HudTileLayer` ficam fora desta rodada.
|
|
|
|
7. **TileSize**: `nao`
|
|
`TileSize` permanece como conceito geometrico e nao entra automaticamente no rename.
|
|
|
|
8. **Strings, fixtures e test names**: `sim`
|
|
Helpers, fixtures, mensagens e nomes de testes entram na migracao para evitar residuos do vocabulario antigo.
|
|
|
|
9. **Lessons e docs historicas**: `sim`
|
|
A migracao documental e historica entra no escopo, seguindo a mesma fronteira desta agenda: renomear o banco grafico concreto sem arrastar automaticamente o dominio de layer/mapa.
|
|
|
|
## Resolucao Provisoria
|
|
|
|
Ha consenso provisoriamente estabelecido sobre os seguintes pontos:
|
|
|
|
- a mudanca e `rename-only`;
|
|
- o vocabulario canonico do banco grafico concreto passa de `TileBank` para `GlyphBank`;
|
|
- `BankType::TILES` deve migrar para `BankType::GLYPH`;
|
|
- pools, contrato de asset, loader path, renderer, hardware references, fixtures e nomes de teste entram na migracao;
|
|
- `TileLayer`/`TileMap` e derivados ficam fora desta rodada;
|
|
- `TileSize` fica fora desta rodada;
|
|
- docs e lessons historicas entram no escopo, respeitando essa mesma fronteira.
|
|
|
|
O principal ponto restante para encerrar a agenda e confirmar se essa resolucao ja e suficiente para virar decisao normativa, ou se ainda falta detalhar como a migracao documental deve tratar referencias historicas em texto corrido quando `tile` continuar correto para layer/mapa.
|
|
|
|
## Resolucao
|
|
|
|
A agenda fica encerrada com a seguinte orientacao:
|
|
|
|
- a mudanca e `rename-only`;
|
|
- o banco grafico concreto passa a se chamar `GlyphBank`;
|
|
- `BankType::TILES` passa a `BankType::GLYPH`;
|
|
- pools, contrato de asset, loader path, renderer, hardware references, fixtures, nomes de teste, docs e lessons entram na migracao;
|
|
- `TileLayer`, `TileMap` e derivados ficam fora;
|
|
- `TileSize` fica fora;
|
|
- docs e lessons antigas devem migrar referencias ao banco grafico concreto para `GlyphBank`, mantendo `tile` quando o assunto for layer, mapa, grade ou geometria.
|
|
|
|
## Criterio para Encerrar
|
|
|
|
Esta agenda pode ser encerrada quando houver consenso escrito sobre:
|
|
|
|
- se a mudanca e rename-only ou nao;
|
|
- qual vocabulario passa a ser canonico;
|
|
- quais contratos externos entram no rename;
|
|
- quais grupos concretos entram ou nao na migracao;
|
|
- como evitar que `TileLayer`/`TileMap` sejam arrastados automaticamente sem decisao propria.
|