---
id: AGD-0001
ticket: world-editor-journey-spec
title: World Editor / Journey Spec
status: accepted
created: 2026-06-19
resolved: 2026-06-19
decision: DEC-0001
tags:
  - 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

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