prometeu-studio/discussion/workflow/agendas/AGD-0033-revise-scene-bank-editorial-model-to-single-tmx-per-scene.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0033	studio-scene-pack-runtime-binary-contract	Revise Scene Bank editorial model to Studio-native scene with TMX import-export	accepted	2026-04-30	2026-04-30	DEC-0030	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

• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.
• 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.