gardens-of-nil-3d-u6/discussion/workflow/agendas/AGD-0001-world-editor-journey-spec.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0001	world-editor-journey-spec	World Editor / Journey Spec	accepted	2026-06-19	2026-06-19	DEC-0001	world-editor journey stage-contract architecture

Contexto

O World Editor precisa organizar o macro-mundo jogavel de Gardens of Nil sem assumir responsabilidade de Stage Editor. O modelo proposto separa:

• World Editor: camadas macro, tiles ocupados por Stage, contratos de conexao, regras de travessia, loading/progressao e vizinhanca.
• Stage Editor: geometria interna, props, inimigos, puzzles, floors internos, camera interna, portas finais e navegacao dentro do Stage.

A unidade base proposta e WorldTile = 24m x 24m, com cada tile representando aproximadamente uma tela jogavel. O mundo e editado como 2D por WorldLayer; verticalidade interna continua no Stage Editor, e verticalidade macro fica sob JEndpointLift.

O sistema central de conexao entre Stages se chama Journey. Cada Stage declara JEndpoints, e cada JConnection conecta exatamente dois endpoints. Todo espaco fisico pertence sempre a um Stage; se for necessario corredor, antecamara, sala de loading, elevador longo ou mecanismo de transicao, isso deve virar outro Stage, nao uma conexao com area propria.

Contexto adicional levantado durante a discussao: o Stage Editor ja esta em andamento em Assets/Scripts/Editor/GardensStageEditor, com StageDefinition em Assets/Scripts/Editor/GardensStageEditor/StageDefinition.cs. Esse StageDefinition descreve dados editoriais internos do Stage, como floors, grid/cells e objetos de authoring, e por estar sob Assets/Scripts/Editor nao deve ser assumido como dado consultavel in game.

Direcao proposta pelo usuario: StageDefinition deve permanecer como dado de editor, enquanto os dados de Journey precisam existir em um pacote runtime consultavel pelo jogo, provavelmente em Assets/Scripts/Intrepid/Gameplay/Journey.

Refinamento proposto pelo usuario: podem existir ambos os ScriptableObjects. Um SO pode ser editorial/editor-only, usado durante authoring de Stage e World. Quando o trabalho for consolidado, o editor gera ou atualiza os dados do lado runtime do Journey. A intencao e evitar que edicao em andamento de stages/world afete playtest ou runtime.

Refinamento de fluxo editorial: inicialmente existirao dois editores, um World Editor e um Stage Editor. No futuro eles podem ser consolidados em uma unica experiencia, onde um duplo clique em um Stage no World Editor abre o Stage Editor correspondente. Hoje o Stage Editor recebe o StageDefinition manualmente; a integracao futura deve remover essa friccao.

Nomes aceitos para o contrato inicial: WorldLayoutSO para o SO editorial do World Editor e JGraphSO para o SO runtime consultavel pelo Journey. Elementos do Journey devem usar prefixo J; se forem ScriptableObjects, devem tambem terminar com SO.

Escopo aceito para commit/publicacao do World Editor: o botao de commit gera somente os dados logicos do Journey, como graph, endpoints, connections e metadados necessarios para travessia/loading/progressao. Ele nao gera Stages, cenas, geometria interna, objetos internos ou conteudo do Stage Editor. Cada Stage continua sendo gerado/bakeado a partir do Stage Editor. Os dados publicados do Journey servem como contrato de integracao para que os Stages implementem seus endpoints e conexoes correspondentes.

Fechamentos de V1: WorldTile = 24m e WorldLayerHeight = 24m devem ser defaults configuraveis no WorldLayoutSO, nao constantes hardcoded. Stage, JEndpoint e JConnection devem ter ids estaveis por GUID/string; o sistema de tags existente pode ser util para classificacao/consulta, mas nao substitui identidade estavel. JEndpointLift fica limitado a uma unica JConnection na V1. JEndpointAnchor pode ter multiplas conexoes, mas a selecao de destino ja existe in game e nao precisa ser tratada por esta V1. Loading hints ficam fora da V1; a arquitetura deve apenas permitir adicionar dados depois. O Journey pode ter uma representacao logica de Stage, chamada JStage, mas o Stage de cena nao e gerado pelo botao do World Editor. Na V1, a integracao World Editor -> Stage Editor permanece manual.

Fechamentos finais de V1: JGraphSO deve registrar metadata minima de publicacao, incluindo sourceWorldLayoutId, publishedAt, schemaVersion e, se barato, contentHash. Requirements ficam como extensao futura de JConnection, sem estrutura concreta obrigatoria na V1. Endpoint obrigatorio sem conexao deve bloquear commit como erro; endpoint opcional sem conexao pode ser warning.

Tecnologia de editor aceita para V1: o World Editor deve usar a mesma abordagem do Stage Editor atual: EditorWindow com UI Toolkit (UnityEngine.UIElements e UnityEditor.UIElements) e canvas custom baseado em VisualElement.generateVisualContent. Isso evita introduzir outro stack de window/editor UI e facilita uma futura integracao entre World Editor e Stage Editor.

Problema

Precisamos transformar a proposta de World Editor / Journey em contrato arquitetural consistente antes de editar specs ou codigo. A proposta ja contem muitas decisoes aparentemente firmes, mas ainda ha pontos que mudam serializacao, validacao, fluxo de edicao, runtime e sincronizacao com Stage Editor.

O risco principal e cristalizar cedo demais um modelo que parece simples no editor, mas que depois nao fecha bem com runtime, loading, authoring de cenas Unity ou validacao entre o contrato runtime do Journey, o StageDefinition editor-only e markers reais na Scene.

Pontos Criticos

• WorldTile e WorldLayer parecem bons como contrato macro, mas precisam ter semantica clara: unidade de authoring, unidade de loading, unidade de progressao, ou apenas visualizacao editorial.
• Stage como conjunto de tiles sem overlap simplifica validacao, mas pode restringir intencoes visuais de mundo se designers tentarem modelar fundo, paralaxe ou volumes sobrepostos no World Editor.
• JConnection sem espaco fisico e uma regra forte. Ela evita corredores invisiveis no grafo, mas exige disciplina para criar Transition Stages quando a travessia tem presenca fisica.
• JEndpointSocket, JEndpointAnchor e JEndpointLift cobrem tres categorias boas, mas a cardinalidade e compatibilidade precisam virar invariantes do modelo.
• StageDefinition existente pertence ao Stage Editor e e editor-only. O Journey precisa de um contrato runtime proprio, separado do asset interno do Stage Editor.
• A fronteira entre dado autoral/editorial e dado runtime precisa ficar explicita: o World Editor pode produzir/validar dados de Journey, mas o jogo nao deve depender de tipos localizados em Assets/Scripts/Editor.
• O modelo pode ter dois niveis de SO: um SO editorial para World Editor/authoring e um SO consolidado runtime em Journey. Ainda falta nomear os tipos e definir a direcao de sync/publicacao.
• O fluxo de edicao tambem precisa considerar integracao entre World Editor e Stage Editor: manter editores separados no inicio, mas desenhar o contrato para permitir abrir o Stage Editor a partir do World Editor.
• Requirements podem pertencer a JConnection como dados simples ou extensao futura; loading hints ficam fora da V1.
• Stage Editor Sync ainda e direcao futura. Na V1, a integracao entre World Editor e Stage Editor permanece manual.
• O World Editor deve seguir a tecnologia de window ja usada no Stage Editor, hoje localizado em Assets/Scripts/Editor/GON/StageEditor.

Opcoes

Opcao A - Aceitar o modelo proposto como arquitetura base

• Abordagem: tratar o texto atual como base quase fechada para uma decisao normativa, mantendo apenas detalhes menores para planos futuros.
• Pro: acelera a criacao de specs e implementacao do editor; reduz ambiguidade no curto prazo.
• Contra: pode esconder decisoes ainda nao maduras, especialmente sync com Stage Editor, requirements e lifts multi-parada.
• Manutenibilidade: boa se as premissas estiverem corretas; cara se for necessario mudar cardinalidade ou identidade de endpoints depois.

Opcao B - Fechar primeiro o contrato minimo do Journey

• Abordagem: separar o nucleo estavel do Journey: WorldLayer, WorldTile, Stage, JEndpoint, JConnection, compatibilidade, cardinalidade e validacoes de erro. Deixar runtime selection, UX detalhada de wiring, requirements avancados e sync Scene como decisoes subsequentes.
• Pro: cria uma base normativa pequena e implementavel sem resolver todo o ecossistema de uma vez.
• Contra: exige mais de uma decisao/plano antes de o sistema completo estar especificado.
• Manutenibilidade: forte, porque preserva invariantes essenciais e deixa extensoes menos maduras fora do contrato inicial.

Opcao B2 - Fechar contrato minimo com separacao editor/runtime

• Abordagem: manter a Opcao B, mas acrescentar como decisao de base que StageDefinition existente e editor-only, e que os tipos/dados consultaveis in game do Journey ficam em Assets/Scripts/Intrepid/Gameplay/Journey.
• Pro: respeita o Stage Editor ja em andamento; evita dependencia runtime em assemblies de editor; cria uma fronteira limpa entre authoring e gameplay.
• Contra: exige mapear como o World Editor sincroniza ou exporta dados para o asset runtime do Journey.
• Manutenibilidade: mais forte que a Opcao B simples, porque separa explicitamente contratos de authoring e contratos de runtime antes de surgirem referencias cruzadas indevidas.

Opcao B3 - Dois SOs com publicacao explicita

• Abordagem: manter um SO editorial para authoring de World/Stage e gerar um SO runtime consolidado para Journey apenas em um passo explicito de publicacao/consolidacao.
• Pro: protege playtest de edicoes incompletas; permite validacoes editoriais mais ricas sem carregar complexidade no runtime; reduz acoplamento entre Stage Editor, World Editor e gameplay.
• Contra: introduz um pipeline de publicacao que precisa ser validado, versionado e facil de diagnosticar quando editor e runtime divergirem.
• Manutenibilidade: forte se o runtime SO for tratado como artefato publicado e verificavel, nao como espelho editado manualmente.

Opcao C - Prototipar editor antes de fechar contrato

• Abordagem: implementar um prototipo Unity do World Editor e deixar a experiencia editorial revelar o melhor modelo.
• Pro: valida rapidamente fluxo de pintura, conexoes, visualizacao por layer e wiring.
• Contra: viola o fluxo do repositorio para mudancas arquiteturais se nao houver decisao e plano antes do codigo; pode gerar codigo descartavel como fonte acidental de verdade.
• Manutenibilidade: arriscada se o prototipo virar contrato implicito.

Sugestao / Recomendacao

Recomendacao inicial: seguir a Opcao B3.

O texto proposto deve virar uma agenda que separa contrato minimo de extensoes. A primeira decisao deveria fechar apenas o nucleo do World Editor / Journey:

• World Editor e 2D por WorldLayer.
• WorldTile = 24m x 24m.
• Stage pertence a uma unica layer e ocupa um conjunto sem overlap de tiles.
• Todo espaco fisico pertence a Stage.
• JConnection nunca possui espaco fisico.
• JEndpointSocket, JEndpointAnchor e JEndpointLift sao os tipos iniciais.
• Compatibilidade inicial e apenas tipo igual com tipo igual.
• JConnection e sempre uma ligacao 1:1.
• Cardinalidade inicial: socket uma conexao, anchor varias conexoes, lift uma conexao.
• Anchor e Lift nao coexistem no mesmo tile; sockets podem coexistir com ambos.
• Validacoes de erro e warning precisam ser classificadas antes de execucao.
• StageDefinition existente em Assets/Scripts/Editor/GardensStageEditor permanece editor-only e nao e a API runtime do Journey.
• Os tipos e assets runtime do Journey devem viver fora de Assets/Scripts/Editor, com local inicial recomendado em Assets/Scripts/Intrepid/Gameplay/Journey.
• O World Editor pode manter um SO editorial proprio e publicar/consolidar um SO runtime do Journey em etapa explicita, para que playtest use apenas dados validados.
• O SO editorial do World Editor deve se chamar WorldLayoutSO.
• O SO runtime do Journey deve se chamar JGraphSO.
• A publicacao inicial do Journey deve ser uma acao explicita no World Editor, provavelmente um botao de commit/publicacao do Journey.
• O commit do Journey gera somente o contrato logico runtime: graph, endpoints, connections e dados relacionados. Stage generation/bake permanece responsabilidade exclusiva do Stage Editor.
• O Journey pode conter JStage como representacao logica runtime/publicada de um Stage no graph.
• O World Editor e o Stage Editor podem nascer separados. Na V1, a integracao entre eles pode continuar manual; a arquitetura deve permitir que futuramente um duplo clique em Stage abra o Stage Editor com o StageDefinition correto.
• WorldTile = 24m e WorldLayerHeight = 24m entram como defaults configuraveis no WorldLayoutSO.
• Stage, JStage, JEndpoint e JConnection devem ter ids estaveis por GUID/string. Tags podem complementar classificacao e consulta, mas nao substituem ids.
• Loading hints ficam fora da V1; JConnection deve continuar extensivel para dados futuros.
• JGraphSO deve registrar metadata minima de publicacao: sourceWorldLayoutId, publishedAt, schemaVersion e opcionalmente contentHash.
• Requirements ficam fora da estrutura concreta obrigatoria da V1, mas JConnection deve permanecer extensivel para recebe-los depois.
• Endpoint obrigatorio sem conexao deve bloquear commit como erro. Endpoint opcional sem conexao pode ser warning.
• A implementacao do World Editor deve usar EditorWindow + UI Toolkit, seguindo o padrao do Stage Editor existente.

As decisoes abertas devem ser registradas como proximos topicos, nao misturadas no primeiro contrato:

• como o runtime escolhe destino de Anchor multi-conexao;
• representacao visual de conexoes unidirecionais;
• estrutura concreta de requirements;
• protocolo de sync entre Stage Editor markers, StageDefinition editor-only e o asset runtime do Journey;
• detalhes de UX de tela propria de wiring;
• loading hints e politicas de streaming.
• consolidacao visual/operacional futura entre World Editor e Stage Editor.

Perguntas em Aberto

• WorldTile = 24m x 24m deve ser hardcoded no contrato inicial ou configuravel por WorldLayoutSO com default 24m?
• WorldLayerHeight = 24m e uma constante normativa, um default editavel, ou apenas uma recomendacao de authoring?
• O StageDefinition existente deve ser tratado como editor-only, nao como fonte runtime do Journey?
• O SO editorial do World Editor deve se chamar WorldLayoutSO, WorldAuthoringSO, ou outro nome?
• O asset runtime consultavel in game deve se chamar JGraphSO, seguindo prefixo J e sufixo SO?
• O World Editor edita diretamente o asset runtime do Journey ou mantem dados editoriais e exporta/sincroniza um asset runtime?
• Qual acao explicita publica/consolida o SO editorial para o SO runtime: botao no editor, menu command, build step, ou combinacao?
• Como o runtime SO registra versao/hash/origem para diagnosticar divergencia entre authoring e playtest?
• O botao de commit do Journey deve apenas validar/publicar JGraphSO, ou tambem atualizar/gerar assets auxiliares?
• A integracao por duplo clique deve abrir o Stage Editor existente passando o StageDefinition do Stage, ou criar uma camada comum de selecao/editor shell?
• Um JEndpointLift deve permanecer limitado a uma unica JConnection no contrato inicial?
• Anchor multi-destino precisa de regra runtime agora, ou basta registrar que o endpoint pode ter varias conexoes e adiar a selecao?
• Requirements devem entrar no contrato inicial como estrutura concreta ou apenas como extensao planejada de JConnection?
• Loading hints entram na primeira decisao ou ficam para uma decisao de streaming/loading?
• O build valido deve exigir todos os endpoints obrigatorios conectados, ou isso fica como validacao por profile/contexto?
• Como identificar estavelmente endpoints: GUID proprio, id derivado do Stage, ou referencia Unity serializada?
• O Stage Editor Sync e requisito do primeiro plano de execucao ou uma fase posterior?
• Qual tecnologia de window/editor UI deve ser usada pelo World Editor?

Criterio para Encerrar

Esta agenda pode virar decisao quando houver acordo sobre:

• quais invariantes entram no contrato inicial do World Editor / Journey;
• quais topicos ficam explicitamente fora do primeiro contrato;
• a fronteira de fonte de verdade entre o asset runtime do Journey e os dados editoriais do World/Stage Editor;
• a fronteira entre StageDefinition editor-only e o asset runtime consultavel pelo Journey;
• a fronteira entre SO editorial de World e SO runtime consolidado de Journey;
• o mecanismo minimo de publicacao/consolidacao entre authoring e runtime;
• que a publicacao do World Editor e limitada aos dados logicos do Journey;
• os nomes WorldLayoutSO e JGraphSO;
• o fluxo inicial de integracao entre World Editor e Stage Editor;
• a cardinalidade inicial de Socket, Anchor e Lift;
• a granularidade minima de Requirements e Loading Hints no primeiro spec;
• a estrategia inicial para ids de Stage, endpoint e connection.
• a tecnologia de editor para a primeira implementacao do World Editor.

Discussion

Entrada inicial recebida em 2026-06-19: proposta "Gardens of Nil - World Editor / Journey Spec" com vinte secoes cobrindo objetivo, principios, unidades, Stage, Journey, endpoints, conexoes, validacoes, fluxo de edicao, visualizacao, decisoes confirmadas e questoes abertas.

Atualizacao de discussao em 2026-06-19: o usuario apontou que o Stage Editor ja esta em andamento em Assets/Scripts/Editor/GardensStageEditor, incluindo StageDefinition. A orientacao proposta e que StageDefinition seja usado somente no editor, enquanto os dados de Journey devem ser consultaveis in game e ficar em Assets/Scripts/Intrepid/Gameplay/Journey. Verificacao local confirmou que StageDefinition.cs esta sob Assets/Scripts/Editor/GardensStageEditor e modela dados internos/editoriais do Stage.

Atualizacao de discussao em 2026-06-19: o usuario propôs manter ambos os SOs: um SO editorial para edicao de Stage/World e um SO runtime consolidado no lado Journey. A motivacao e evitar que edicoes em andamento afetem playtest. A recomendacao da agenda foi ajustada para dois SOs com publicacao explicita.

Atualizacao de discussao em 2026-06-19: o usuario definiu os nomes WorldLayoutSO para o SO editorial do World Editor e JourneyGraphSO para o SO runtime do Journey. Tambem indicou que havera dois editores inicialmente, World e Stage, com possibilidade futura de unificacao; o fluxo desejado e duplo clique em um Stage no World Editor abrir o Stage Editor com o StageDefinition correto. Para publicacao, a preferencia inicial e um botao no World Editor para commitar/publicar o Journey.

Atualizacao de discussao em 2026-06-19: o usuario fechou que o botao de commit do World Editor gera somente as coisas do Journey: graph, connections, endpoints e demais dados logicos. Stages continuam sendo gerados a partir de cada Stage no Stage Editor, pois sao outra preocupacao. Os SOs de endpoints e connections publicados pelo World Editor devem facilitar a integracao posterior com os Stages.

Atualizacao de discussao em 2026-06-19: o usuario fechou os defaults e escopo de V1. WorldTile e WorldLayerHeight ficam como defaults configuraveis de 24m no WorldLayoutSO. Identidade deve usar GUID/string estavel, com tags como apoio de classificacao quando util. JEndpointLift fica 1:1. Anchor multi-destino pode existir no graph, sem tratar selecao nesta V1 porque a selecao ja existe in game. Loading hints ficam fora da V1. O Journey pode ter JStage como representacao logica de Stage. O botao do World Editor nao gera Stage de cena; bake continua no Stage Editor. Integracao World/Stage Editor fica manual na V1.

Atualizacao de discussao em 2026-06-19: o usuario definiu a convencao de nomes do Journey: elementos usam prefixo J e ScriptableObjects terminam com SO. Com isso, o runtime graph passa a ser JGraphSO. Tambem aceitou as sugestoes finais: metadata minima de publicacao no SO runtime, requirements como extensao futura de JConnection, e validacao onde endpoint obrigatorio sem conexao e erro enquanto endpoint opcional sem conexao e warning.

Atualizacao de discussao em 2026-06-19: o usuario definiu que o World Editor deve usar a mesma tecnologia ja usada no Stage Editor para gerenciamento da Window. Verificacao local mostrou que o Stage Editor atual esta em Assets/Scripts/Editor/GON/StageEditor, usando EditorWindow, UI Toolkit (UnityEngine.UIElements / UnityEditor.UIElements) e canvas custom via VisualElement.generateVisualContent.

Resolution

Aceita em 2026-06-19.

Resolucao: emitir uma decisao V1 para o World Editor / Journey com WorldLayoutSO como SO editorial do World Editor e JGraphSO como SO runtime publicado do Journey. O commit do World Editor publica somente dados logicos do Journey: JStage, endpoints, connections, graph e metadata de publicacao. Stage scene generation e bake permanecem no Stage Editor. O World Editor V1 deve usar EditorWindow + UI Toolkit seguindo o Stage Editor existente. Requirements concretos, loading hints, sync profundo com Stage Editor, wiring avancado e consolidacao visual dos editores ficam fora da V1.