122 lines
10 KiB
Markdown
122 lines
10 KiB
Markdown
---
|
|
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.
|