housekeeping e clean up
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 59.32% (17061/28759)
* Branch Coverage: 51.84% (6536/12607)
* Lines of Code: 28759
* Cyclomatic Complexity: 11399
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 11, passed: 601
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 59.32% (17061/28759)
* Branch Coverage: 51.84% (6536/12607)
* Lines of Code: 28759
* Cyclomatic Complexity: 11399
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 11, passed: 601
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good
This commit is contained in:
@@ -1,247 +0,0 @@
|
||||
---
|
||||
id: AGD-0032
|
||||
ticket: studio-scene-pack-runtime-binary-contract
|
||||
title: Studio scene pack contract for runtime SCENE binary payload
|
||||
status: accepted
|
||||
created: 2026-04-24
|
||||
resolved: 2026-04-27
|
||||
decision:
|
||||
tags: [studio, packer, runtime, scene, asset-pack, binary-format, tiled]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
O runtime ja possui um payload binario `SCENE` versionado e com decoder real, mas o Studio/paker ainda para em `TMX`/`TSX` e nao fecha a publicacao desse asset para `assets.pa`.
|
||||
|
||||
Isso deixa um gap claro entre:
|
||||
|
||||
- authoring/editorial workflow no dominio `studio`;
|
||||
- materializacao e packing no dominio `packer`;
|
||||
- contrato efetivamente consumido no dominio `runtime`.
|
||||
|
||||
Dominio owner desta agenda: `studio`.
|
||||
Boundary explicito: `studio -> packer -> runtime`.
|
||||
|
||||
## Context
|
||||
|
||||
- O runtime define `SCENE` v1 com magic `SCNE`, version `1`, `4` layers fixas, metadata vazio no header do asset table e payload binario por layer.
|
||||
- O decoder de `SCENE` ja valida:
|
||||
version;
|
||||
layer count;
|
||||
tile size;
|
||||
parallax factor;
|
||||
`width * height == tile_count`;
|
||||
`decoded_size`;
|
||||
ausencia de trailing bytes.
|
||||
- O runtime tambem ja instala `SceneBank` em scene slots, mas a dependencia de glyph por layer agora eh `glyph_asset_id`, nao mais `glyph_bank_id`.
|
||||
- O runtime resolve `glyph_asset_id -> glyph slot` internamente durante `bind_scene` e `render_frame`, mantendo a alocacao de slot como concern operacional de runtime.
|
||||
- O Studio hoje trata `Scene Bank` como asset owner de authoring/validation, com `scene-bank.studio.json`, `TMX` por layer e `TSX` gerado por glyph bank especializado em tileset.
|
||||
- A decision consolidada em `DSC-0028` fechou o modelo wave 1 de authoring em `TMX`/`TSX`, mas deixou explicitamente o scene packing runtime como concern posterior.
|
||||
- O packer atual reconhece `SCENE_BANK` como familia e `SCENE/tilemap_v1` como output format, mas ainda nao faz walk/materialization de scene e falha deliberadamente no pack execution para familias fora de `GLYPH_BANK`.
|
||||
|
||||
Findings tecnicos relevantes desta agenda:
|
||||
|
||||
1. O formato binario ja existe no runtime e nao esta “a decidir”.
|
||||
2. O packer atual nao produz payload `SCENE`.
|
||||
3. O maior buraco contratual hoje nao eh o layout binario em si, mas a traducao editorial de `TMX`/`TSX` para os campos exigidos pelo runtime.
|
||||
4. O campo mais sensivel continua sendo a dependencia de glyph por layer, mas o runtime atual passou a usar `glyph_asset_id` no `SCENE` e resolver `asset_id -> slot` internamente.
|
||||
5. Isso remove do Studio/paker a necessidade de conhecer previamente o glyph slot operacional do runtime para serializar a scene.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [x] Quem deve ser o owner da compilacao `TMX`/`TSX -> SCENE`: `prometeu-packer` embutido no Studio, uma camada editorial do Studio, ou outro componente?
|
||||
Resposta atual da discussao:
|
||||
o `Asset Workspace` gera e usa `TMX`/`TSX` apenas como support/editorial surfaces;
|
||||
esses formatos nao devem ser empurrados para o `prometeu-packer`;
|
||||
o `prometeu-packer` deve receber um protocolo proprio de requisicao;
|
||||
o `Scene Bank` no Studio deve validar e extrair, no passo de `Accept`, os dados necessarios dos artefatos editoriais para esse request.
|
||||
- [x] Qual deve ser o contrato canonico da dependencia de glyph por layer?
|
||||
Resposta validada contra o runtime atual:
|
||||
o payload `SCENE` deve carregar `glyph_asset_id`;
|
||||
a resolucao `asset_id -> slot` pertence ao runtime;
|
||||
Studio e packer nao precisam serializar slot de glyph no contrato da scene.
|
||||
- [x] O `Scene Bank` deve persistir `glyph_asset_id` explicitamente no metadata/request do Studio ou derivar isso sempre a partir do asset referenciado na layer?
|
||||
Resposta atual da discussao:
|
||||
`glyph_asset_id` eh derivado do tileset/glyph asset selecionado no form da layer, mantendo uma unica fonte da verdade.
|
||||
- [x] Onde devem viver os `parallax_factor` por layer, que o runtime exige mas o metadata atual do Studio nao modela?
|
||||
Resposta atual da discussao:
|
||||
`parallax_factor` deve ser adicionado ao form da layer no Studio.
|
||||
- [x] De onde vem o `palette_id` por layer/tile no request atual?
|
||||
Resposta atual da discussao:
|
||||
`palette_id` ainda nao existe no workflow atual e deve ser adicionado ao form da layer no Studio, ou em surface editorial equivalente no mesmo nivel.
|
||||
- [x] Como o workflow editorial indica se uma layer entra ou nao na publicacao?
|
||||
Resposta atual da discussao:
|
||||
o checkbox existente no form da layer indica se a layer esta ativa/sera usada.
|
||||
- [x] Qual eh a regra oficial de traducao de tiles do Tiled para records do payload runtime:
|
||||
`gid` base;
|
||||
flip flags;
|
||||
`glyph_id`;
|
||||
`palette_id`?
|
||||
Resposta atual da discussao:
|
||||
cada tile eh mapeado pelo `TSX`, e o `TSX` aponta para o glyph asset;
|
||||
`flip` e `palette_id` por tile podem vir como properties no `TMX`, por serem dados do tile especifico;
|
||||
`glyph_id` ja existe como property no `TSX`.
|
||||
- [x] O wave 1 continua estritamente limitado a um `TSX` por `TMX`/layer tambem no scene pack runtime, ou precisamos abrir espaco para multi-tileset antes de fechar o contrato?
|
||||
Resposta atual da discussao:
|
||||
sim, wave 1 continua com exatamente `1 TSX` por `TMX`/layer.
|
||||
- [x] A aceitacao no Studio deve ser gate obrigatorio para publicar `SCENE` em pack, ou apenas um estado editorial recomendado?
|
||||
Resposta atual da discussao:
|
||||
o criterio continua sendo o usual do workflow: nenhum diagnostic error bloqueante.
|
||||
- [x] O `SCENE/tilemap_v1` no manifest representa o payload binario runtime final, ou ainda esta sendo usado ambiguamente para o estado editorial baseado em `TMX`?
|
||||
Resposta atual da discussao:
|
||||
vamos manter `SCENE/tilemap_v1` por enquanto;
|
||||
o runtime nao exige mudanca desse nome neste momento.
|
||||
- [x] Qual deve ser o shape exato do request `studio -> packer`?
|
||||
Resposta atual da discussao:
|
||||
o request deve ser construido backwards a partir dos dados do payload binario `SCENE`, como um data class o mais proximo possivel do binario final.
|
||||
Shape atual assentado na agenda:
|
||||
```text
|
||||
ScenePackRequest
|
||||
- version: int
|
||||
- layers: [ScenePackLayerRequest; 4]
|
||||
|
||||
ScenePackLayerRequest
|
||||
- active: bool
|
||||
- glyph_asset_id: int
|
||||
- tile_size: int
|
||||
- parallax_factor_x: float
|
||||
- parallax_factor_y: float
|
||||
- width: int
|
||||
- height: int
|
||||
- tiles: List<ScenePackTileRequest>
|
||||
|
||||
ScenePackTileRequest
|
||||
- active: bool
|
||||
- glyph_id: int
|
||||
- palette_id: int
|
||||
- flip_x: bool
|
||||
- flip_y: bool
|
||||
```
|
||||
Observacoes do shape assentado:
|
||||
`request -> SCENE` deve ser quase isomorfico;
|
||||
`tile_count` pode ser derivado de `width * height`;
|
||||
campos reservados do binario nao precisam existir no request.
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Studio Accepts Tiled and Emits a Packer-Owned Scene Request
|
||||
|
||||
- **Approach:** manter o Studio como owner de authoring, validation e acceptance de `TMX`/`TSX`, e fazer o `Scene Bank` aceito extrair um request proprio e estavel para o `prometeu-packer`; o packer compila esse request para o payload binario `SCENE` sem conhecer `TMX`/`TSX`.
|
||||
- **Pro:** preserva `TMX`/`TSX` como concern editorial do Studio e evita contaminar o packer com detalhes de tooling externo.
|
||||
- **Con:** exige fechar um boundary formal novo entre Studio e packer, incluindo o schema desse request.
|
||||
- **Maintainability:** boa, desde que o contrato editorial/runtime fique explicito e versionado.
|
||||
|
||||
### Option B - Add a Studio-Owned Intermediate Scene Representation First
|
||||
|
||||
- **Approach:** antes de empacotar, introduzir um modelo normalizado intermediario no Studio ou em shared tooling, e so depois converter esse modelo para o payload binario runtime.
|
||||
- **Pro:** pode simplificar validacao e testes sem depender diretamente de parsing de `TMX` no packer.
|
||||
- **Con:** reabre o risco de criar uma segunda surface de scene alem de `TMX`, contrariando a direcao recente de evitar schema paralelo cedo demais.
|
||||
- **Maintainability:** media; melhora isolamento interno, mas adiciona outra camada contratual para manter.
|
||||
|
||||
### Option C - Make Packer Parse TMX/TSX Directly
|
||||
|
||||
- **Approach:** fazer o `prometeu-packer` ler `TMX`/`TSX` diretamente e produzir o payload runtime a partir dessas surfaces editoriais.
|
||||
- **Pro:** reduz o numero aparente de etapas entre authoring e pack final.
|
||||
- **Con:** acopla o packer a uma surface editorial do Studio e ao tooling externo, o que contraria a direcao explicitada nesta discussao.
|
||||
- **Maintainability:** fraca; qualquer evolucao do authoring/editorial tende a vazar para o contrato operacional do packer.
|
||||
|
||||
## Discussion
|
||||
|
||||
O estado atual sugere que o layout binario do runtime ja esta suficientemente maduro para servir como contrato de destino. A discussao principal nao deveria voltar para “qual eh o formato binario da scene”, e sim para “como o Studio/paker chegam nele de forma disciplinada”.
|
||||
|
||||
Ha uma restricao importante aqui: a decision anterior sobre `Scene Bank` em Assets e `TMX`/`TSX` como surfaces wave 1 continua valida. Portanto esta agenda nao deve reinterpretar `DSC-0028` como se o Studio precisasse ganhar um scene workspace, um editor pesado ou um schema proprietario paralelo por conveniencia.
|
||||
|
||||
Direcao ja explicitada nesta thread:
|
||||
|
||||
- `TMX` e `TSX` ficam confinados ao dominio editorial do Studio;
|
||||
- o `Asset Workspace` deve conseguir validar e extrair do estado aceito os dados relevantes para pack;
|
||||
- o `prometeu-packer` nao deve conhecer Tiled nem depender de `TMX`/`TSX`;
|
||||
- o boundary Studio -> packer deve ser um protocolo proprio, estavel e independente das surfaces editoriais.
|
||||
|
||||
Os pontos mais arriscados no boundary sao:
|
||||
|
||||
1. `glyph_asset_id`:
|
||||
o runtime agora aceita identidade estavel de asset na scene e resolve `asset_id -> slot` internamente; a discussao ja convergiu que esse valor eh derivado do tileset/glyph asset selecionado no form da layer.
|
||||
2. `parallax_factor`:
|
||||
o runtime exige esse campo por layer; a direcao atual eh adiciona-lo ao form da layer, no mesmo nivel editorial de configuracoes como dimensao do mapa.
|
||||
3. traducao de tiles:
|
||||
a direcao atual ja convergiu que cada tile eh resolvido pelo `TSX`, com `flip` e `palette_id` podendo vir do `TMX`; o request do packer deve preservar esses campos de forma quase isomorfica ao record runtime.
|
||||
4. `palette_id`:
|
||||
a direcao atual eh adiciona-lo ao form da layer, com possibilidade de override por tile via properties editoriais no `TMX`.
|
||||
5. gate editorial:
|
||||
o checkbox de layer ativa ja cobre o uso editorial da layer, e o gate atual para publicar continua sendo ausencia de diagnostic error bloqueante.
|
||||
## Settled So Far
|
||||
|
||||
Os pontos abaixo ficam cravados nesta agenda como direcao atual da discussao:
|
||||
|
||||
1. `TMX` e `TSX` permanecem surfaces editoriais do Studio e nao entram no protocolo operacional do packer.
|
||||
2. `TMX` e `TSX` sao surfaces editoriais suportadas em wave 1, mas nao sao a surface canonica do contrato de publicacao e permanecem substituiveis por outros editores suportados no futuro.
|
||||
3. O `Asset Workspace` deve extrair, no passo de `Accept`, um request proprio para o `prometeu-packer`.
|
||||
4. O payload runtime `SCENE` carrega `glyph_asset_id`, e a resolucao `asset_id -> slot` pertence ao runtime.
|
||||
5. `glyph_asset_id` eh derivado do tileset/glyph asset selecionado no form da layer.
|
||||
6. `parallax_factor` deve existir no form da layer.
|
||||
7. `palette_id` deve existir no form da layer, ou em surface editorial equivalente no mesmo nivel.
|
||||
8. O checkbox da layer define se ela esta ativa/sera usada.
|
||||
9. Cada tile eh resolvido via `TSX`; `glyph_id` ja existe como property no `TSX`.
|
||||
10. `flip` e `palette_id` por tile podem vir como properties no `TMX`.
|
||||
11. Wave 1 continua com exatamente `1 TSX` por `TMX`/layer.
|
||||
12. O gate atual para publicar continua sendo ausencia de diagnostic error bloqueante.
|
||||
13. O request `studio -> packer` deve ser derivado backwards do payload binario e `request -> SCENE` deve ser o mais direto possivel.
|
||||
14. O shape atual assentado do request e:
|
||||
`ScenePackRequest(version, layers[4])`;
|
||||
`ScenePackLayerRequest(active, glyph_asset_id, tile_size, parallax_factor_x, parallax_factor_y, width, height, tiles)`;
|
||||
`ScenePackTileRequest(active, glyph_id, palette_id, flip_x, flip_y)`.
|
||||
15. O manifest permanece com `SCENE/tilemap_v1` por enquanto.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Seguir com a `Option A`.
|
||||
|
||||
Direcao recomendada:
|
||||
|
||||
1. manter `TMX`/`TSX` como surfaces editoriais wave 1 no dominio `studio`;
|
||||
2. registrar explicitamente que `TMX`/`TSX` nao sao a surface canonica do contrato e podem coexistir no futuro com outros editores suportados, desde que materializem o mesmo request canonico;
|
||||
3. fechar uma decision nova para o boundary `studio/packer/runtime` do `Scene Bank`;
|
||||
4. fazer o `Asset Workspace` aceitar e extrair do estado editorial um request proprio para o packer;
|
||||
5. fazer o `prometeu-packer` ser owner apenas da compilacao desse request para o payload binario `SCENE`;
|
||||
6. explicitar na decision:
|
||||
modelagem da dependencia `glyph_asset_id`;
|
||||
modelagem de `parallax_factor`;
|
||||
modelagem de `palette_id`;
|
||||
semantica da layer ativa no request;
|
||||
gate baseado em diagnostics bloqueantes;
|
||||
formato do request `studio -> packer`, derivado backwards do payload binario;
|
||||
semantica oficial de `SCENE/tilemap_v1`;
|
||||
carater nao-canonico e substituivel das surfaces editoriais suportadas.
|
||||
|
||||
Essa direcao reaproveita o que ja existe, mantem o packer livre das ferramentas editoriais do Studio e concentra a publicacao runtime no subsistema que ja monta `assets.pa`.
|
||||
|
||||
## Next Step Suggestion
|
||||
|
||||
Converter esta agenda em uma decision focada no contrato de compilacao/publicacao de `Scene Bank`, cobrindo:
|
||||
|
||||
1. ownership por dominio;
|
||||
2. formato do request `studio -> packer`, backwards a partir do payload binario;
|
||||
3. mapping editorial -> request -> runtime, com `request -> SCENE` o mais direto possivel;
|
||||
4. modelagem e validacao de `glyph_asset_id` por layer;
|
||||
5. gating de diagnostics para pack;
|
||||
6. propagation targets em `prometeu-packer`, `prometeu-studio` e specs relevantes.
|
||||
|
||||
## Resolution
|
||||
|
||||
Agenda aceita.
|
||||
|
||||
Direcao consolidada:
|
||||
|
||||
1. `TMX`/`TSX` permanecem estritamente editoriais no dominio `studio`.
|
||||
2. `TMX`/`TSX` sao surfaces editoriais suportadas em wave 1, mas nao sao a definicao canonica do asset nem do contrato de publicacao.
|
||||
3. Outros editores suportados no futuro podem substituir ou coexistir com `TMX`/`TSX`, desde que materializem o mesmo request canonico `studio -> packer` e passem pelas mesmas regras de validacao e `Accept`.
|
||||
4. O `Scene Bank` aceito deve extrair um request proprio e estavel para o `prometeu-packer`.
|
||||
5. O request `studio -> packer` deve ser derivado backwards do payload binario `SCENE` e `request -> SCENE` deve ser o mais direto possivel.
|
||||
6. O contrato runtime de dependencia de glyph por layer usa `glyph_asset_id`, com resolucao `asset_id -> slot` pertencendo ao runtime.
|
||||
7. O workflow editorial do Studio deve prover `glyph_asset_id` derivado do tileset selecionado, `parallax_factor`, `palette_id`, estado ativo da layer e a traducao por tile a partir de `TSX`/`TMX`.
|
||||
8. Wave 1 permanece com exatamente `1 TSX` por `TMX`/layer.
|
||||
9. O gate para publicacao continua sendo ausencia de diagnostic error bloqueante.
|
||||
10. O manifest permanece com `SCENE/tilemap_v1` por enquanto.
|
||||
|
||||
Proximo passo sugerido: converter esta agenda em uma `decision` normativa para o boundary `studio -> packer -> runtime`.
|
||||
-121
@@ -1,121 +0,0 @@
|
||||
---
|
||||
id: AGD-0033
|
||||
ticket: studio-scene-pack-runtime-binary-contract
|
||||
title: Revise Scene Bank editorial model to Studio-native scene with TMX import-export
|
||||
status: accepted
|
||||
created: 2026-04-30
|
||||
resolved: 2026-04-30
|
||||
decision: DEC-0030
|
||||
tags: [studio, packer, runtime, scene, asset-pack, tiled, revision]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
A direcao aceita em `DEC-0029` e implementada por `PLN-0059` a `PLN-0061` tomou um atalho editorial errado: modelamos `1 layer -> 1 TMX`, com validacao e `Accept` por layer, quando o editor suportado (`Tiled`) opera naturalmente com `1 scene -> 1 TMX` contendo multiplos layers.
|
||||
|
||||
Isso gerou uma friccao estrutural:
|
||||
|
||||
- o fluxo atual separa artificialmente layers que pertencem ao mesmo mapa;
|
||||
- o `Accept` por layer conflita com a necessidade de publicar uma scene coesa;
|
||||
- o modelo atual esconde um erro conceitual ao tratar `TMX` como surface por layer, em vez de surface por scene;
|
||||
- a integracao editorial ficou mais fraca justamente no editor que estamos suportando em wave 1.
|
||||
|
||||
Dominio owner desta agenda: `studio`.
|
||||
Boundary explicito: `studio -> packer -> runtime`.
|
||||
|
||||
## Context
|
||||
|
||||
- `DEC-0029` fechou corretamente que `TMX`/`TSX` sao surfaces editoriais suportadas, nao canonicas, e que o contrato normativo de publicacao continua sendo o request `studio -> packer -> SCENE`.
|
||||
- O erro nao esta nesse boundary canonico; o erro esta no shape editorial escolhido para a integracao com Tiled.
|
||||
- A implementacao atual assumiu:
|
||||
- `1 layer -> 1 TMX`;
|
||||
- `1 TMX -> 1 TSX`;
|
||||
- geracao, validacao e `Accept` com foco em layer.
|
||||
- O problema observado no `tiled2` reforca essa distorcao: o fluxo de workflow passou a tentar aceitar layer isoladamente, quando o valor editorial real esta na scene inteira.
|
||||
- O Tiled comporta um `TMX` com multiplos layers; cada layer pode ter seu proprio tileset referenciado no mapa, e o authoring natural da scene acontece nesse documento unico.
|
||||
- O runtime continua nao dependendo de `TMX`; ele continua dependendo apenas do request canonico aceito e do payload binario `SCENE`.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [x] O modelo wave 1 deve ser formalmente revisado para `1 scene -> 1 TMX` com multiplos layers?
|
||||
Resposta: parcialmente. Essa direcao corrige o erro imediato de `TMX por layer`, mas a escolha final nao eh promover `TMX unico` a surface principal. A direcao escolhida eh um modelo nativo de scene no Studio, com `TMX` tratado como formato suportado de import/export.
|
||||
- [x] Devemos abandonar completamente `validate layer` e `accept layer`, deixando apenas `generate scene`, `validate scene` e `accept scene`?
|
||||
Resposta: sim, e mais do que isso: no modelo escolhido esses verbos deixam de ser a surface principal do workflow editorial. O Studio passa a operar com `import` e `export` via wizard para formatos suportados, com `Tiled` como primeira opcao. A validacao ocorre sobre o formato canonico do asset de scene no `Analyse` ou no `Pack`, nao sobre o formato externo.
|
||||
- [x] Como cada layer da scene referencia seu tileset no editor suportado?
|
||||
Resposta: no caminho de compatibilidade com Tiled, o `TMX` pode carregar multiplos `TSX`, e a scene pode usar ate quatro tilesets distintos. Isso descreve a compatibilidade editorial do import/export, nao o modelo canonico interno do Studio.
|
||||
- [x] Como representar layers com tamanhos independentes dentro da scene?
|
||||
Resposta: o modelo da scene deve aceitar layers com tamanho proprio. No caminho Tiled, mapas infinitos continuam suportados como concern editorial. Camera boundaries ficam para iteracao posterior.
|
||||
- [x] O `scene-bank.studio.json` deve continuar carregando `width`/`height` por layer, ou passar a carregar apenas metadata editorial complementar e bindings?
|
||||
Resposta: o asset de scene deve manter uma entidade canonica propria, distinta do request de pack. `scene-bank.studio.json` pode continuar existindo como persistencia editorial dessa entidade, com metadata como `width` e `height` por layer quando fizer sentido, mas sem se confundir com o request `studio -> packer`.
|
||||
- [x] Como o request canonico deve ser projetado sem reintroduzir dependencia canonica em formato editorial?
|
||||
Resposta: o request `studio -> packer` continua existindo, mas como projeção derivada da entidade canonica do asset de scene, nao como a propria entidade editorial. `TMX` entra apenas como formato suportado de importacao/exportacao; `import` atualiza a entidade canonica a partir do `TMX`, e `export` sobrescreve o `TMX` a partir da entidade canonica.
|
||||
- [x] O `import` de `TMX` deve aceitar qualquer alteracao editorial feita externamente no Tiled?
|
||||
Resposta: nao. O `import` deve aplicar validacoes minimas de compatibilidade antes de alterar a entidade canonica. Mudancas como adicao de novos layers, adicao de novos tilesets, ou alteracao estrutural inesperada de layers/tilesets podem invalidar o `TMX` para importacao. Quando isso ocorrer, o Studio deve recusar o `import` e emitir logs/diagnostics claros de falha.
|
||||
- [x] Como o fluxo de `TSX` deve se comportar para glyph tilesets especializados?
|
||||
Resposta: o glyph tileset pode gerar `TSX`, e isso passa a ser tratado como `export` para formato suportado `TSX (Tiled)`. O `export` sobrescreve o arquivo existente ou cria um novo, seguindo a mesma filosofia do `TMX`.
|
||||
- [x] Quais partes de `DEC-0029` permanecem validas e quais precisam ser substituidas explicitamente?
|
||||
Resposta: permanece valida a parte que fixa `TMX`/`TSX` como surfaces editoriais nao canonicas e o request `studio -> packer` como contrato normativo. Deve ser substituida explicitamente a parte editorial implementada como `TMX por layer` e o workflow `generate / validate / accept` por layer.
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Keep per-layer TMX and patch workflow
|
||||
- **Approach:** Manter `1 layer -> 1 TMX`, corrigir o bug de workflow de `Accept`, e ajustar a UX ao redor disso.
|
||||
- **Pro:** Menor custo imediato sobre a implementacao existente.
|
||||
- **Con:** Preserva o erro de modelagem editorial e continua desalinhado com o uso natural do Tiled.
|
||||
- **Maintainability:** Fraca. Corrige sintomas sem corrigir o modelo.
|
||||
|
||||
### Option B - Revise to single TMX per scene and scene-level workflow
|
||||
- **Approach:** Revisar a decision para `1 scene -> 1 TMX`, com multiplos layers editoriais no mesmo mapa, e mover `generate / validate / accept` para o nivel da scene.
|
||||
- **Pro:** Alinha o Studio ao modelo real do Tiled e fecha um boundary editorial mais coerente.
|
||||
- **Con:** Exige revisao normativa, refatoracao de specs e reimplementacao parcial do fluxo entregue em `PLN-0060` e `PLN-0061`.
|
||||
- **Maintainability:** Forte. Remove a distorcao estrutural e preserva o contrato canonico correto.
|
||||
|
||||
### Option C - Introduce a Studio-native scene model now and demote TMX to import/export
|
||||
- **Approach:** Parar de tratar `TMX` como surface principal e assumir imediatamente um modelo proprio do Studio, usando Tiled apenas como compatibilidade.
|
||||
- **Pro:** Resolve de vez o acoplamento editorial ao Tiled.
|
||||
- **Con:** Exige refatoracao mais profunda agora, incluindo suporte nativo de scene, import/export, migracao editorial e revisao dos plans ja executados.
|
||||
- **Maintainability:** Melhor opcao de longo prazo. Remove o erro estrutural na raiz e abre espaco para multiplos editores suportados.
|
||||
|
||||
Escolha fechada na agenda: `Option C`.
|
||||
|
||||
## Discussion
|
||||
|
||||
A correção necessária parece ser de direcao, nao apenas de bug.
|
||||
|
||||
O problema central nao eh que o request canonico exista ou que o packer compile `SCENE`; isso continua correto. O problema eh que o lado editorial foi fatiado na unidade errada. Ao quebrar scene em `TMX` por layer, o Studio passou a operar contra a gravidade do editor suportado e abriu espaco para workflow incoerente.
|
||||
|
||||
A agenda convergiu para um passo adicional: mesmo o modelo `TMX unico por scene` ainda seria uma otimizacao em torno do Tiled, nao uma surface editorial suficiente para o Studio no medio prazo. A escolha da `Option C` fecha uma direcao mais limpa:
|
||||
|
||||
- preservar o boundary canonico `studio -> packer -> runtime`;
|
||||
- introduzir um modelo nativo de scene no Studio como surface principal;
|
||||
- tratar `TMX`/`TSX` como formatos suportados de importacao/exportacao e compatibilidade;
|
||||
- substituir `generate / validate / accept` por um workflow de `import / export` guiado por wizard para formatos suportados;
|
||||
- aplicar validacoes minimas de compatibilidade no `import`, com recusa e logs claros quando o artefato externo divergir estruturalmente do que o Studio suporta;
|
||||
- validar a entidade canonica da scene no `Analyse` ou no `Pack`;
|
||||
- manter o request canonico de pack como projeção derivada da entidade canonica da scene, e nao como espelho bruto de qualquer formato externo.
|
||||
|
||||
Isso substitui explicitamente a parte editorial errada de `DEC-0029`, sem reabrir a parte do contrato canonico de publicacao que continuou correta.
|
||||
|
||||
## Resolution
|
||||
|
||||
Recomendacao final da agenda:
|
||||
|
||||
- revisar `DEC-0029` para abandonar o modelo `TMX por layer`;
|
||||
- nao promover `TMX unico por scene` a surface principal do produto;
|
||||
- adotar um modelo nativo de scene no Studio como owner editorial principal;
|
||||
- tratar `TMX`/`TSX` como formatos suportados de import/export e compatibilidade;
|
||||
- substituir o workflow de `generate / validate / accept` por `import / export` com wizard;
|
||||
- exigir validacoes minimas no `import` de `TMX`, com falha explicita quando houver divergencia estrutural nao suportada, como novos layers, novos tilesets, ou alteracoes estruturais equivalentes;
|
||||
- tratar a geracao de `TSX` por glyph tileset como `export` para formato suportado `TSX (Tiled)`, com sobrescrita ou criacao do arquivo de destino;
|
||||
- validar a entidade canonica do asset de scene no `Analyse` ou no `Pack`;
|
||||
- preservar a separacao entre:
|
||||
- entidade canonica do asset de scene no Studio;
|
||||
- request `studio -> packer`;
|
||||
- payload binario `SCENE` de runtime;
|
||||
- preservar como normativa a parte de `DEC-0029` que fixa `TMX`/`TSX` como surfaces editoriais nao canonicas e o request `studio -> packer` como contrato de publicacao.
|
||||
|
||||
Proximo passo sugerido:
|
||||
|
||||
- emitir uma nova decision de revisao, substituindo explicitamente a porcao editorial de `DEC-0029`;
|
||||
- derivar novos plans para `specs`, `studio` e `packer`, com migracao do fluxo atual;
|
||||
- tratar a implementacao entregue em `PLN-0060` e `PLN-0061` como baseline a ser revisada, nao como forma final do modelo editorial.
|
||||
Reference in New Issue
Block a user