296 lines
16 KiB
Markdown
296 lines
16 KiB
Markdown
---
|
|
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.
|