--- id: AGD-0029 ticket: studio-scene-workspace title: Scene Workspace for SCENE Authoring status: abandoned created: 2026-04-14 resolved: 2026-04-14 decision: DEC-0026 tags: - studio - workspace - scene - tilemap - asset - runtime-alignment --- ## Pain O Studio ainda nao possui um workspace dedicado para autoria e inspecao de scenes. Sem esse workspace: - o Studio nao oferece uma experiencia autoral propria para scenes como dominio editorial; - a equipe fica sem uma superficie visual para editar o artefato intermediario de scene que depois alimenta o asset `SCENE`; - o Studio perde a chance de ensinar o modelo correto de scene como asset versionado, com quatro layers e contrato proprio; - a futura expansao para camera bounds, lights, AABB e outros aspectos acaba sem composicao clara desde a primeira wave. ## Context Domain owner: `studio` Owner documental esperado: - `docs/specs/studio` Cross-domain impact: - `../runtime` para o contrato canonico de `SCENE`, `SceneBank` e `SceneLayer`; - `Assets` workspace apenas na fronteira de criacao/descoberta do asset `SCENE`. Rastro relevante ja existente: - o runtime ja convergiu para `SCENE` como payload binario versionado; - `SceneBank` e o modelo canonico carregado no runtime possuem exatamente `4` layers; - cada `SceneLayer` possui seu proprio `TileMap`, com dimensoes independentes; - viewport cache, camera movement e renderer nao fazem parte do modelo canonico de authoring do scene; - o `Assets` workspace ja define o padrao de navegador customizado, asset-first e path-aware, que deve inspirar a navegacao do `Scene Workspace` sem virar um file explorer generico. Escopo inicial solicitado pelo usuario: - novo workspace chamado `Scene Workspace`; - navegador de scenes na lateral esquerda, similar ao `Assets` workspace; - o `Scene Workspace` trabalha com scenes como scenes, nao como assets; - a scene editada no workspace vira um artefato intermediario de autoria; - o `Scene Workspace` pode criar uma scene nova e, ao fazer isso, criar tambem o asset `SCENE` correspondente; - o `Assets` workspace pode criar um asset `SCENE`, mas nao pinta mapa nem faz configuracoes editoriais da scene; - depois de criado, o trabalho de conteudo e configuracao da scene fica delegado ao `Scene Workspace`; - cada scene como mapa de `4` layers; - cada layer com largura e altura independentes, em estilo similar ao `Tiled`; - faixa superior com abas de aspectos da ferramenta; - primeira aba: `Tilemap`; - aba `Tilemap` com mapa no centro; - painel superior direito com dimensoes e detalhes do tilemap; - painel inferior direito com aquarela/paleta de tiles para selecao e pintura; - tileset vindo de assets, com suporte a selecionar qualquer glyph bank ou marcar glyph banks como tileset apenas no Studio; - outras abas futuras previstas: camera boundaries, lights, AABB, etc., mas fora da primeira wave. ## Open Questions - [x] O `Scene Workspace` deve abrir scenes apenas por seu catalogo proprio, ou tambem aceitar handoff contextual quando um asset `SCENE` for criado no `Assets`? - [x] Qual identidade o navegador da esquerda deve priorizar: scene authoring artifact, path do projeto, ou algum catalogo editorial proprio do `Scene Workspace`? - [x] O Studio deve tratar a edicao de scene como staged editing com `apply/reset`, ou como documento editavel com save integrado? - [x] Como o Studio relaciona uma scene autoral com o asset `SCENE` correspondente: referencia por path, UUID proprio do artefato intermediario, ou binding mediado por metadata do Studio? - [x] Como o Studio seleciona o glyph bank usado como tileset em cada layer ou scene: referencia editorial na scene ou vinculacao resolvida pelo proprio `Scene Workspace`? - [x] O contrato do runtime ja determina metadados suficientes por layer para authoring inicial, ou o Studio precisara propor extensoes antes da implementacao do workspace? - [x] Como representar tiles vazios, brush, fill e selecao sem colidir com a semantica canonica de tile vazio ja aceita no runtime? - [x] A primeira wave deve permitir apenas pintura bruta por tile, ou ja precisa incluir ferramentais como marquee, bucket, eyedropper e multi-layer visibility/lock? - [x] As abas futuras devem ser somente placeholders estruturais agora, ou a wave inicial deve expor apenas a aba `Tilemap` para nao sugerir suporte inexistente? ## Options ### Option A - `Scene Workspace` como workspace dedicado no shell - **Approach:** Criar um workspace proprio de `Scene Workspace`, com navegador de scenes na esquerda, header com tabs de aspecto e composicao interna especializada por aba. - **Pro:** Da visibilidade de primeira classe a `SCENE`, cria uma arquitetura clara para expansao futura por aspectos e preserva a fronteira entre shell e detalhe operacional do workspace. - **Con:** Introduz mais uma entrada no shell e exige decidir como ele se relaciona com a descoberta de assets no fluxo ja existente. - **Maintainability:** Strong, porque estabiliza ownership e composicao desde a primeira wave. ### Option B - editor especializado dentro do `Assets` workspace - **Approach:** Manter tanto o asset `SCENE` quanto a edicao do artefato intermediario dentro do `Assets`, usando a selecao do asset como ponto de entrada do editor. - **Pro:** Reaproveita navegacao asset-first existente e concentra toda a historia de scene em um unico lugar. - **Con:** Colapsa duas naturezas diferentes em uma mesma superficie: gerenciamento de asset packer-facing e authoring de scene como conteudo editorial. - **Maintainability:** Weak, porque incentiva o `Assets` workspace a absorver ownership que nao e dele. ### Option C - workspace autoral proprio com integracao via asset - **Approach:** O `Scene Workspace` edita e cria a scene como dominio proprio; o `Assets` workspace apenas pode criar/mostrar o asset `SCENE` e delega a autoria da scene para o `Scene Workspace`. - **Pro:** Separa claramente authoring editorial de scene da gestao asset-first do `Assets`, sem deixar o `Assets` absorver o editor. - **Con:** Exige fechar um contrato de binding entre scene autoral e asset `SCENE`, alem de definir handoff entre os dois workspaces. - **Maintainability:** Strong, porque o `Scene Workspace` permanece owner do conteudo e o `Assets` fica restrito a criacao/gestao do asset. ## Discussion O ponto mais importante desta discussao nao e apenas layout. O runtime ja tem um contrato canonico claro o bastante para impor restricoes no editor: 1. o payload final `SCENE` nao e um documento arbitrario; e um asset binario versionado com `4` layers fixos; 2. cada layer possui `TileMap` proprio e, portanto, o editor nao deve assumir um canvas unificado com dimensoes compartilhadas; 3. viewport cache, camera drift e outras preocupacoes de renderizacao nao pertencem ao modelo canonico do scene workspace; 4. o `Scene Workspace` nao deve editar o payload final do asset diretamente; ele deve editar um material intermediario proprio; 5. o tileset precisa se alinhar aos glyph banks que ja existem como assets, sem criar um segundo sistema de tiles paralelo no Studio. Tambem existe uma decisao estrutural de produto a ser tomada cedo: - se o `Scene Workspace` for somente um modo interno do `Assets`, o Studio arrisca repetir o anti-pattern de transformar um workspace asset-first em container generico de editores; - se ele nascer como workspace proprio, a arquitetura de abas por aspecto e a expansao futura para boundaries/lights/AABB ficam mais honestas; - como a scene autoral nao e o proprio asset, a costura correta passa por um contrato entre artefato intermediario e asset `SCENE`, nao por subordinacao de um workspace ao outro; - o `Assets` pode oferecer criacao de asset `SCENE`, mas a autoria e manutencao do conteudo da scene devem ser delegadas ao `Scene Workspace`. Outro ponto aberto e a semantica do tileset: - permitir qualquer glyph bank maximiza flexibilidade e reaproveitamento; - exigir uma tag editorial de "tileset" melhora discoverability e reduz selecao invalida; - uma combinacao pode ser a melhor direcao: qualquer glyph bank tecnicamente valido, com tagging opcional no Studio para curadoria UX. Por fim, a primeira wave precisa resistir a overreach: - a aba `Tilemap` ja e um escopo suficientemente grande; - placeholders de abas futuras so fazem sentido se a shell structure realmente precisar reservar esse contrato agora; - caso contrario, placeholders podem comunicar suporte inexistente e gerar pressao artificial sobre uma decision ainda nao tomada. ### Convergence pass - recommended answers for the open questions #### 1. Workspace proprio ou extensao do `Assets` Recomendacao: `Scene Workspace` deve existir como workspace shell-level proprio e nao deve ser subordinado ao `Assets`. Motivo: - o shell ja foi especificado para hospedar workspaces independentes; - o `Assets` workspace deve continuar asset-first e didatico, nao virar um host generico de editores; - a scene autoral tem natureza propria e vira um artefato intermediario, nao o payload final do asset. - o `Scene Workspace` deve aceitar tanto abertura por seu proprio navegador quanto handoff contextual quando o `Assets` criar um asset `SCENE`. #### 2. Identidade do navegador da esquerda Recomendacao: a identidade primaria deve ser a scene autoral, nao o asset `SCENE`. Contexto de apoio: - path continua visivel como contexto secundario; - o workspace pode precisar de um identificador editorial proprio para a scene intermediaria; - o asset `SCENE` correspondente pertence ao `Assets` workspace e deve aparecer apenas como vinculacao ou estado derivado. Direcao adicional: - o navegador deve ser scene-first; - path de projeto entra como contexto secundario; - o asset vinculado pode aparecer como badge, status ou acao contextual, mas nao como unidade primaria de navegacao. #### 3. Modelo de edicao e persistencia Recomendacao: a primeira wave deve tratar a scene como documento/artefato autoral com save proprio, separado de qualquer fluxo de criacao ou gestao do asset no `Assets`. Motivo: - o usuario deixou explicito que o `Scene Manager` trabalha sobre um artefato intermediario proprio; - o `Scene Workspace` e owner do conteudo da scene; - o `Assets` pode continuar com fluxos proprios para criacao/gestao de asset, mas sem absorver a autoria da scene; - misturar save do conteudo autoral com `apply` do asset apagaria a fronteira entre autoria e empacotamento. Direcao adicional: - o `Scene Workspace` salva o artefato intermediario; - criar ou vincular o asset `SCENE` e um passo de integracao entre workspaces, nao a mesma operacao de salvar a scene. #### 4. Binding entre scene autoral e asset `SCENE` Recomendacao: o binding deve ser mediado por metadata do Studio, nao por inferencia de path como regra primaria. Motivo: - path pode mudar por rename ou reorganizacao de projeto; - a scene autoral precisa de identidade mais estavel do que localizacao fisica; - o `Assets` e o `Scene Workspace` precisam compartilhar um vinculo explicito sem colapsar um no outro. Direcao adicional: - a scene autoral deve ter um identificador proprio; - o asset `SCENE` correspondente deve referenciar esse identificador, ou vice-versa, por um contrato editorial do Studio; - path continua relevante como localizacao de arquivo, nao como ancora semantica principal do binding. #### 5. Selecao de glyph bank como tileset Recomendacao: a scene autoral deve poder referenciar glyph banks como tilesets em nivel editorial, e essa escolha deve ser owned pelo `Scene Workspace`. Motivo: - o runtime ja referencia `glyph_bank_id` por layer, nao um tipo separado de tileset; - criar um subtipo obrigatorio de asset agora inventaria uma regra de produto nao exigida pelo contrato canonico; - uma tag editorial ainda pode melhorar descoberta sem restringir um contrato que hoje e genericamente `GLYPH`. Direcao adicional: - a escolha de glyph bank por layer ou por scene deve ser resolvida no `Scene Workspace`; - o `Assets` nao deve redefinir tileset da scene; - tags editoriais opcionais no Studio podem melhorar filtragem e discoverability. #### 6. Metadados por layer Recomendacao: para a primeira wave, o contrato do runtime parece suficiente para authoring inicial de tilemap. Rastro observado no runtime: - `SceneLayer` ja possui `active`; - `glyph_bank_id`; - `tile_size`; - `motion_factor`; - `tilemap` com `width`, `height` e tiles. Conclusao: - isso e suficiente para uma aba `Tilemap` com visibilidade por layer, dimensoes independentes, tileset por layer e pintura; - camera bounds, lights e AABB ficam corretamente fora dessa wave e devem motivar metadados adicionais apenas quando virarem tema de nova decision. #### 7. Tile vazio, brush e pintura Recomendacao: o Studio deve respeitar a semantica canonica de presenca explicita por tile. Consequencias: - `glyph_id = 0` deve permanecer valido; - apagar um tile deve atuar sobre o bit/estado de presenca (`active = false`), nao sobre um glyph magico; - brush, eyedropper e futuras ferramentas devem operar sobre `active`, `glyph_id`, `palette_id`, `flip_x` e `flip_y`. #### 8. Ferramentas da primeira wave Recomendacao: limitar a primeira wave a pintura basica, apagador, seletor de tile e controles de layer como visibilidade/foco. Excluir agora: - marquee complexo; - bucket fill; - multi-select estrutural; - automacoes de brush avancadas. Motivo: - o objetivo da wave 1 e provar o fluxo canonico de scene authoring; - ferramentas mais ricas multiplicam edge cases antes de estabilizar modelo, persistencia e UX base. Direcao adicional: - `multi-layer visibility` e `layer focus` entram na wave 1; - `lock`, `marquee`, `bucket`, `flood fill` e automacoes avancadas ficam explicitamente fora. #### 9. Abas futuras agora ou depois Recomendacao: o workspace deve nascer com uma faixa superior de tabs, mas expor apenas a aba `Tilemap` na primeira wave. Motivo: - a estrutura de tabs faz parte da composicao arquitetural pedida; - tabs placeholder para `Camera`, `Lights` ou `AABB` sugeririam suporte que ainda nao existe; - reservar o componente estrutural agora facilita expansao futura sem mentir sobre cobertura funcional. ## Resolution Abandoned on 2026-04-15 by explicit user request. The accepted direction captured here was superseded before implementation. Follow-up direction: - abandon the dedicated `Scene Workspace` approach; - open a new discussion for a `Tiled` parser; - manage the resulting authoring flow from `Assets` through a new asset type. Direcao recomendada: convergir para **Option C**, em que o `Scene Workspace` e um workspace autoral de primeira classe no shell e o `Assets` workspace permanece apenas como superficie asset-first capaz de criar ou exibir o asset `SCENE`, sem editar o conteudo da scene. Essa recomendacao parte de quatro principios: 1. a scene autoral e um artefato intermediario proprio do dominio `Scene Workspace`; 2. o asset `SCENE` pode ser criado tanto pelo `Scene Workspace` quanto pelo `Assets`, mas o conteudo da scene e owner do `Scene Workspace`; 3. o `Assets` nao pinta mapa nem faz configuracoes editoriais da scene; 4. o binding entre scene autoral e asset `SCENE` deve ser explicito e estavel; 5. a primeira wave deve fechar apenas o aspecto `Tilemap`, sem fingir maturidade para camera bounds, lights ou AABB. Proximo passo sugerido: transformar esta agenda em uma decision que feche: 1. `Scene Workspace` como workspace shell-level proprio e owner do artefato intermediario de scene; 2. identidade primaria do workspace pela scene autoral, nao pelo asset; 3. save proprio da scene autoral no `Scene Workspace`, separado da criacao/gestao do asset no `Assets`; 4. contrato de binding entre scene intermediaria e asset `SCENE`; 5. glyph banks como tilesets validos por contrato, com eventual curadoria editorial no Studio; 6. aba unica `Tilemap` na primeira wave, preservando a shell de tabs para expansao futura; 7. propagacao necessaria para specs do `studio`, incluindo a pequena extensao do `Assets` para criacao de scene asset e o ownership do `Scene Workspace` sobre a autoria da scene.