World Editor / Journey Spec
This commit is contained in:
Nilton Constantino
parent
92ae70ff61
commit
7921b95a29
2
discussion/index.ndjson
Normal file
2
discussion/index.ndjson
Normal file
@ -0,0 +1,2 @@
|
||||
{"type":"meta","next_id":{"DSC":2,"AGD":2,"DEC":2,"PLN":5,"LSN":1,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0001","status":"accepted","ticket":"world-editor-journey-spec","title":"World Editor / Journey Spec","created_at":"2026-06-19","updated_at":"2026-06-19","tags":["world-editor","journey","stage-contract","architecture"],"agendas":[{"id":"AGD-0001","file":"AGD-0001-world-editor-journey-spec.md","status":"accepted","created_at":"2026-06-19","updated_at":"2026-06-19"}],"decisions":[{"id":"DEC-0001","file":"DEC-0001-world-editor-journey-v1.md","status":"accepted","created_at":"2026-06-19","updated_at":"2026-06-19","ref_agenda":"AGD-0001"}],"plans":[{"id":"PLN-0001","file":"PLN-0001-world-journey-spec.md","status":"review","created_at":"2026-06-19","updated_at":"2026-06-19","ref_decisions":["DEC-0001"]},{"id":"PLN-0002","file":"PLN-0002-journey-runtime-model.md","status":"review","created_at":"2026-06-19","updated_at":"2026-06-19","ref_decisions":["DEC-0001"]},{"id":"PLN-0003","file":"PLN-0003-world-editor-authoring.md","status":"review","created_at":"2026-06-19","updated_at":"2026-06-19","ref_decisions":["DEC-0001"]},{"id":"PLN-0004","file":"PLN-0004-journey-commit-validation.md","status":"review","created_at":"2026-06-19","updated_at":"2026-06-19","ref_decisions":["DEC-0001"]}],"lessons":[]}
|
||||
@ -0,0 +1,207 @@
|
||||
---
|
||||
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.
|
||||
@ -0,0 +1,143 @@
|
||||
---
|
||||
id: DEC-0001
|
||||
ticket: world-editor-journey-spec
|
||||
title: World Editor / Journey V1
|
||||
status: accepted
|
||||
created: 2026-06-19
|
||||
accepted: 2026-06-19
|
||||
agenda: AGD-0001
|
||||
plans:
|
||||
- PLN-0001
|
||||
- PLN-0002
|
||||
- PLN-0003
|
||||
- PLN-0004
|
||||
tags:
|
||||
- world-editor
|
||||
- journey
|
||||
- stage-contract
|
||||
- architecture
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
Accepted.
|
||||
|
||||
This decision defines the V1 architecture contract for the Gardens of Nil World Editor and Journey runtime graph.
|
||||
|
||||
## Contexto
|
||||
|
||||
Gardens of Nil needs a World Editor to author the macro-world without taking over Stage Editor responsibilities. The Stage Editor already exists under `Assets/Scripts/Editor/GON/StageEditor` and uses `StageDefinition` for editor-only stage authoring.
|
||||
|
||||
The Journey system is the logical contract for travel between Stages. It MUST be available to gameplay/runtime code and MUST NOT depend on types located under `Assets/Scripts/Editor`.
|
||||
|
||||
## Decisao
|
||||
|
||||
The World Editor V1 SHALL use a two-asset model:
|
||||
|
||||
- `WorldLayoutSO` is the editor/authoring ScriptableObject for the World Editor.
|
||||
- `JGraphSO` is the published runtime ScriptableObject for Journey.
|
||||
|
||||
Journey elements MUST use the `J` prefix. Journey ScriptableObjects MUST also use the `SO` suffix.
|
||||
|
||||
The World Editor SHALL publish Journey data through an explicit commit action in the World Editor UI. This commit MUST generate only logical Journey data: `JGraphSO`, `JStage`, `JEndpoint` records, `JConnection` records, graph topology, validation-relevant flags, and publication metadata.
|
||||
|
||||
The World Editor commit MUST NOT generate Stage scenes, Stage geometry, internal Stage objects, baked Stage content, or Stage Editor data. Stage generation and bake remain Stage Editor responsibilities.
|
||||
|
||||
## Rationale
|
||||
|
||||
Separating `WorldLayoutSO` from `JGraphSO` protects playtest/runtime from incomplete authoring edits. It also keeps editor-only structures out of gameplay assemblies and allows richer authoring data without forcing that complexity into runtime.
|
||||
|
||||
Keeping Stage bake separate preserves the current Stage Editor ownership model. The World Editor defines where Stages are, how they connect, and what Journey contract they expose; the Stage Editor decides how each Stage implements its internal scene.
|
||||
|
||||
Using the same editor window technology as the Stage Editor reduces implementation risk and keeps a future editor consolidation path open.
|
||||
|
||||
## Invariantes / Contrato
|
||||
|
||||
- World Editor is 2D per `WorldLayer`.
|
||||
- `WorldTile` default size is `24m x 24m`.
|
||||
- `WorldLayerHeight` default is `24m`.
|
||||
- `WorldTile` size and `WorldLayerHeight` MUST be configurable on `WorldLayoutSO`; V1 defaults are 24m.
|
||||
- A Stage belongs to exactly one `WorldLayer`.
|
||||
- A Stage occupies a set of WorldTiles.
|
||||
- A WorldTile MUST NOT be occupied by more than one Stage in the same WorldLayer.
|
||||
- Physical space MUST always belong to a Stage.
|
||||
- `JConnection` MUST NOT own physical space.
|
||||
- If a corridor, antecamera, transition room, long lift, or loading mask has physical presence, it MUST be modeled as a Stage.
|
||||
- `JGraphSO` MAY contain a logical Stage representation named `JStage`.
|
||||
- `JStage`, `JEndpoint`, and `JConnection` MUST have stable GUID/string ids.
|
||||
- Tags MAY be used for classification and lookup, but MUST NOT replace stable identity.
|
||||
- Initial endpoint types are `JEndpointSocket`, `JEndpointAnchor`, and `JEndpointLift`.
|
||||
- Endpoint compatibility in V1 is same-type only: socket to socket, anchor to anchor, lift to lift.
|
||||
- `JConnection` connects exactly two endpoints.
|
||||
- `JEndpointSocket` accepts at most one `JConnection`.
|
||||
- `JEndpointAnchor` may have multiple `JConnections`.
|
||||
- `JEndpointLift` accepts exactly one `JConnection` in V1.
|
||||
- `JEndpointAnchor` and `JEndpointLift` MUST NOT coexist on the same WorldTile.
|
||||
- Sockets MAY coexist with anchors or lifts.
|
||||
- Loading hints are out of V1.
|
||||
- Concrete requirement modeling is out of V1; `JConnection` MUST remain extensible so requirements can be added later.
|
||||
- A required endpoint without a connection MUST block World Editor commit as an error.
|
||||
- An optional endpoint without a connection MAY be reported as a warning.
|
||||
- `JGraphSO` MUST record minimum publication metadata: `sourceWorldLayoutId`, `publishedAt`, and `schemaVersion`.
|
||||
- `JGraphSO` SHOULD record `contentHash` when cheap and deterministic enough to be useful.
|
||||
|
||||
## Impactos
|
||||
|
||||
Spec:
|
||||
|
||||
- A future spec pass MUST document `WorldLayoutSO`, `JGraphSO`, `JStage`, endpoint types, connection rules, publication metadata, and validation levels in English.
|
||||
|
||||
Runtime:
|
||||
|
||||
- Runtime Journey code SHALL live outside `Assets/Scripts/Editor`, with initial target path `Assets/Scripts/Intrepid/Gameplay/Journey`.
|
||||
- Runtime MUST consume `JGraphSO`, not `WorldLayoutSO` and not `StageDefinition`.
|
||||
|
||||
Editor:
|
||||
|
||||
- World Editor V1 SHALL use `EditorWindow` with UI Toolkit (`UnityEngine.UIElements` and `UnityEditor.UIElements`).
|
||||
- World Editor V1 SHOULD use a custom canvas based on `VisualElement.generateVisualContent`, matching the current Stage Editor approach.
|
||||
- Stage Editor integration remains manual in V1.
|
||||
- Future integration MAY allow double-clicking a Stage in the World Editor to open the Stage Editor with the correct `StageDefinition`.
|
||||
|
||||
Stage Editor:
|
||||
|
||||
- `StageDefinition` remains editor-only.
|
||||
- Stage bake/generation remains owned by the Stage Editor.
|
||||
- Stage scenes are not generated by the World Editor commit button.
|
||||
|
||||
Firmware:
|
||||
|
||||
- No impact.
|
||||
|
||||
Tooling:
|
||||
|
||||
- A plan is required before code/spec execution.
|
||||
- Validation should distinguish commit-blocking errors from warnings.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- Runtime destination selection UI/logic for multi-connection anchors.
|
||||
- Visual representation of unidirectional connections.
|
||||
- Concrete `JRequirement` structure.
|
||||
- Loading hints and streaming policies.
|
||||
- Deep Stage Editor marker sync.
|
||||
- Unified World/Stage Editor shell.
|
||||
- Automatic Stage Editor opening from the World Editor in V1.
|
||||
|
||||
## Referencias
|
||||
|
||||
- Agenda: `discussion/workflow/agendas/AGD-0001-world-editor-journey-spec.md`
|
||||
- Existing Stage Editor path: `Assets/Scripts/Editor/GON/StageEditor`
|
||||
- Existing Stage Definition: `Assets/Scripts/Editor/GON/StageEditor/StageDefinition.cs`
|
||||
|
||||
## Propagacao Necessaria
|
||||
|
||||
- Create a plan from this decision before implementation.
|
||||
- Add or update English canonical specs for World Editor / Journey before or alongside code execution, depending on the plan.
|
||||
- Implement runtime Journey types under `Assets/Scripts/Intrepid/Gameplay/Journey`.
|
||||
- Implement World Editor authoring types under an editor-only path.
|
||||
- Ensure runtime assemblies do not depend on `Assets/Scripts/Editor` types.
|
||||
|
||||
## Revision Log
|
||||
|
||||
- 2026-06-19: Initial accepted decision from AGD-0001.
|
||||
100
discussion/workflow/plans/PLN-0001-world-journey-spec.md
Normal file
100
discussion/workflow/plans/PLN-0001-world-journey-spec.md
Normal file
@ -0,0 +1,100 @@
|
||||
---
|
||||
id: PLN-0001
|
||||
ticket: world-editor-journey-spec
|
||||
title: World Editor / Journey V1 Spec
|
||||
status: review
|
||||
created: 2026-06-19
|
||||
decisions:
|
||||
- DEC-0001
|
||||
tags:
|
||||
- spec
|
||||
- world-editor
|
||||
- journey
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Write the canonical English specification for the World Editor / Journey V1 contract accepted in DEC-0001. This plan produces documentation only. It does not implement Unity code.
|
||||
|
||||
## Source Decisions
|
||||
|
||||
- `DEC-0001`: World Editor / Journey V1.
|
||||
|
||||
## Target
|
||||
|
||||
Create or update the canonical spec location used by this repository with an English spec covering:
|
||||
|
||||
- `WorldLayoutSO` as editor authoring data.
|
||||
- `JGraphSO` as runtime Journey data.
|
||||
- `JStage`, `JEndpoint`, `JEndpointSocket`, `JEndpointAnchor`, `JEndpointLift`, and `JConnection`.
|
||||
- World tile/layer defaults and configurability.
|
||||
- Commit/publication boundary.
|
||||
- Validation error and warning rules.
|
||||
- V1 exclusions.
|
||||
|
||||
## Scope
|
||||
|
||||
- Inspect the repository for the canonical spec/docs location before editing.
|
||||
- Add an English World Editor / Journey V1 spec if none exists.
|
||||
- If a relevant spec already exists, update it instead of creating a parallel source of truth.
|
||||
- Link the spec back to `DEC-0001`.
|
||||
- Document that runtime Journey code lives outside `Assets/Scripts/Editor`.
|
||||
- Document that Stage bake remains owned by the Stage Editor.
|
||||
|
||||
## Out Of Scope
|
||||
|
||||
- C# implementation.
|
||||
- Unity Editor UI implementation.
|
||||
- Stage Editor changes.
|
||||
- Loading hints, concrete requirements, deep Stage marker sync, and editor unification.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Locate canonical docs/specs.
|
||||
- Use `rg --files` to find existing `spec`, `docs`, or design contract files.
|
||||
- Target the existing canonical location if present.
|
||||
- If no canonical spec location exists, create a minimal `specs/` or repository-approved equivalent only after confirming repo convention from nearby files.
|
||||
|
||||
2. Draft the V1 spec.
|
||||
- Add sections for authoring model, runtime model, endpoint model, connection model, commit flow, validation, and exclusions.
|
||||
- Use normative language: `MUST`, `MUST NOT`, `SHALL`, `SHOULD`, and `MAY`.
|
||||
- Keep the spec in English.
|
||||
|
||||
3. Define V1 data contracts in prose.
|
||||
- `WorldLayoutSO`: default `worldTileSize = 24m`, default `worldLayerHeight = 24m`, stages, occupied tiles, authoring endpoints, and editor metadata.
|
||||
- `JGraphSO`: `sourceWorldLayoutId`, `publishedAt`, `schemaVersion`, optional `contentHash`, `JStage[]`, `JEndpoint[]`, and `JConnection[]`.
|
||||
- `JStage`: logical runtime stage record, not scene generation data.
|
||||
|
||||
4. Define validation levels.
|
||||
- Errors block commit.
|
||||
- Warnings do not block commit.
|
||||
- Required endpoint without connection is an error.
|
||||
- Optional endpoint without connection is a warning.
|
||||
|
||||
5. Document non-goals.
|
||||
- No loading hints in V1.
|
||||
- No concrete requirements in V1.
|
||||
- No Stage scene generation from World Editor commit.
|
||||
- No automatic World Editor to Stage Editor integration in V1.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- The spec is in English.
|
||||
- The spec references `DEC-0001`.
|
||||
- The spec names `WorldLayoutSO` and `JGraphSO`.
|
||||
- The spec states that Journey elements use prefix `J`, and Journey ScriptableObjects use suffix `SO`.
|
||||
- The spec states that World Editor commit publishes only logical Journey data.
|
||||
- The spec states that runtime MUST consume `JGraphSO`, not `WorldLayoutSO` or `StageDefinition`.
|
||||
|
||||
## Validation
|
||||
|
||||
- Review the spec against every invariant in `DEC-0001`.
|
||||
- Search the spec for residual Portuguese text before finalizing.
|
||||
- Confirm no duplicate contradictory spec was created.
|
||||
- No automated tests are required for this plan.
|
||||
|
||||
## Risks
|
||||
|
||||
- The repository may not yet have a canonical specs directory.
|
||||
- If spec location is unclear, stop before creating a new documentation tree and ask for direction.
|
||||
- Over-documenting future features could accidentally make them V1 commitments.
|
||||
110
discussion/workflow/plans/PLN-0002-journey-runtime-model.md
Normal file
110
discussion/workflow/plans/PLN-0002-journey-runtime-model.md
Normal file
@ -0,0 +1,110 @@
|
||||
---
|
||||
id: PLN-0002
|
||||
ticket: world-editor-journey-spec
|
||||
title: Journey Runtime Model
|
||||
status: review
|
||||
created: 2026-06-19
|
||||
decisions:
|
||||
- DEC-0001
|
||||
tags:
|
||||
- runtime
|
||||
- journey
|
||||
- scriptableobject
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement the runtime Journey data model consumed by gameplay. This plan creates runtime-safe types under `Assets/Scripts/Intrepid/Gameplay/Journey` and keeps them independent from editor-only code.
|
||||
|
||||
## Source Decisions
|
||||
|
||||
- `DEC-0001`: World Editor / Journey V1.
|
||||
|
||||
## Target
|
||||
|
||||
Create the runtime Journey model:
|
||||
|
||||
- `JGraphSO`
|
||||
- `JStage`
|
||||
- `JEndpoint`
|
||||
- `JEndpointSocket`
|
||||
- `JEndpointAnchor`
|
||||
- `JEndpointLift`
|
||||
- `JConnection`
|
||||
- supporting enums/value types for endpoint kind, directionality, world tile coordinates, socket face, and validation metadata when needed.
|
||||
|
||||
## Scope
|
||||
|
||||
- Runtime serializable data only.
|
||||
- ScriptableObject asset type for `JGraphSO`.
|
||||
- Stable GUID/string ids for `JStage`, `JEndpoint`, and `JConnection`.
|
||||
- Publication metadata on `JGraphSO`.
|
||||
- Query helpers that do not depend on `UnityEditor`.
|
||||
|
||||
## Out Of Scope
|
||||
|
||||
- World Editor UI.
|
||||
- Commit/publish pipeline.
|
||||
- Stage scene generation.
|
||||
- Stage Editor bake.
|
||||
- Loading hints.
|
||||
- Concrete `JRequirement` structure.
|
||||
- Runtime destination selection UI for multi-anchor connections.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Create runtime folder structure.
|
||||
- Target `Assets/Scripts/Intrepid/Gameplay/Journey`.
|
||||
- Preserve existing `.meta` files if Unity already created the folder.
|
||||
|
||||
2. Add `JGraphSO`.
|
||||
- Implement as a `ScriptableObject`.
|
||||
- Fields: `sourceWorldLayoutId`, `publishedAt`, `schemaVersion`, optional `contentHash`, `List<JStage>`, `List<JEndpoint>`, `List<JConnection>`.
|
||||
- Add read-only query methods for stages, endpoints, and connections by id.
|
||||
- Do not reference `UnityEditor`.
|
||||
|
||||
3. Add `JStage`.
|
||||
- Serializable runtime logical Stage record.
|
||||
- Fields: stable id, display/name field, world layer, occupied world tiles, optional tag references if compatible with existing tag conventions.
|
||||
- Do not include Stage scene generation or Stage bake data.
|
||||
|
||||
4. Add endpoint model.
|
||||
- Use a serializable base record or discriminated model that Unity can serialize reliably.
|
||||
- Include stable id, owning `JStage` id, world tile coordinate, endpoint kind, required flag, and type-specific data.
|
||||
- Socket data includes face.
|
||||
- Anchor data supports multiple connections by model validation, not by embedded scene interaction logic.
|
||||
- Lift data includes vertical alignment requirements by world tile coordinate and distinct world layer.
|
||||
|
||||
5. Add `JConnection`.
|
||||
- Fields: stable id, endpoint A id, endpoint B id, directionality.
|
||||
- Keep extensibility for future requirements without implementing a concrete requirement system in V1.
|
||||
- Do not add loading hints in V1.
|
||||
|
||||
6. Add query helpers.
|
||||
- Connections for endpoint id.
|
||||
- Endpoints for stage id.
|
||||
- Stage lookup by id.
|
||||
- Optional lightweight validation-facing helpers without editor dependencies.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Runtime Journey files live under `Assets/Scripts/Intrepid/Gameplay/Journey`.
|
||||
- No runtime Journey file imports `UnityEditor`.
|
||||
- Journey runtime ScriptableObject is named `JGraphSO`.
|
||||
- Runtime Journey element names use prefix `J`.
|
||||
- `JGraphSO` contains publication metadata required by `DEC-0001`.
|
||||
- `JStage`, `JEndpoint`, and `JConnection` use stable GUID/string ids.
|
||||
- Loading hints and concrete requirements are not implemented as V1 commitments.
|
||||
|
||||
## Validation
|
||||
|
||||
- Unity compile succeeds.
|
||||
- Search `Assets/Scripts/Intrepid/Gameplay/Journey` for `UnityEditor`; it must return no runtime dependency.
|
||||
- Create a temporary `JGraphSO` asset in Unity and verify its serialized fields are visible and persist.
|
||||
- No automated tests are required for this phase.
|
||||
|
||||
## Risks
|
||||
|
||||
- Unity serialization may not handle polymorphic endpoint classes as desired without `[SerializeReference]`; choose a serialization pattern consistent with the Unity version and repository style.
|
||||
- Existing tag APIs may be runtime-safe but should not be forced into V1 if they complicate serialization.
|
||||
- Overbuilding query APIs could harden runtime behavior that is intentionally out of scope.
|
||||
114
discussion/workflow/plans/PLN-0003-world-editor-authoring.md
Normal file
114
discussion/workflow/plans/PLN-0003-world-editor-authoring.md
Normal file
@ -0,0 +1,114 @@
|
||||
---
|
||||
id: PLN-0003
|
||||
ticket: world-editor-journey-spec
|
||||
title: World Editor Authoring UI and WorldLayoutSO
|
||||
status: review
|
||||
created: 2026-06-19
|
||||
decisions:
|
||||
- DEC-0001
|
||||
tags:
|
||||
- editor
|
||||
- world-editor
|
||||
- authoring
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement the editor-only World Editor authoring surface and `WorldLayoutSO`. This plan creates the authoring model and window technology, but does not publish `JGraphSO`; publishing is covered by PLN-0004.
|
||||
|
||||
## Source Decisions
|
||||
|
||||
- `DEC-0001`: World Editor / Journey V1.
|
||||
|
||||
## Target
|
||||
|
||||
Create a V1 World Editor under an editor-only path, using the same window technology as the Stage Editor:
|
||||
|
||||
- `EditorWindow`
|
||||
- UI Toolkit
|
||||
- custom canvas via `VisualElement.generateVisualContent`
|
||||
|
||||
Create `WorldLayoutSO` as the editor/authoring ScriptableObject.
|
||||
|
||||
## Scope
|
||||
|
||||
- Editor-only `WorldLayoutSO`.
|
||||
- Editor window shell.
|
||||
- Top bar with `WorldLayoutSO` selection and create/save controls.
|
||||
- 2D layer selector.
|
||||
- Grid canvas for WorldTiles.
|
||||
- Basic stage footprint authoring.
|
||||
- Authoring data for sockets, anchors, lifts, and required/optional endpoint flags.
|
||||
- Manual Stage Editor integration only.
|
||||
|
||||
## Out Of Scope
|
||||
|
||||
- Runtime `JGraphSO` implementation; covered by PLN-0002.
|
||||
- Commit/publish pipeline; covered by PLN-0004.
|
||||
- Stage scene bake.
|
||||
- Automatic double-click opening of Stage Editor in V1.
|
||||
- Advanced wiring screen.
|
||||
- Loading hints and concrete requirements.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Create editor folder structure.
|
||||
- Target `Assets/Scripts/Editor/GON/WorldEditor`.
|
||||
- Mirror Stage Editor conventions from `Assets/Scripts/Editor/GON/StageEditor`.
|
||||
|
||||
2. Implement `WorldLayoutSO`.
|
||||
- ScriptableObject under editor-only code.
|
||||
- Fields: stable layout id, `worldTileSize` default 24, `worldLayerHeight` default 24, stages, authoring endpoints, authoring connections, and editor metadata.
|
||||
- Stages in `WorldLayoutSO` reference or identify their editor `StageDefinition` where needed, but this remains authoring-only.
|
||||
|
||||
3. Implement authoring records.
|
||||
- World stage record with stable id, display name, layer, occupied tiles, color, optional `StageDefinition` reference.
|
||||
- Authoring endpoint records for socket, anchor, and lift.
|
||||
- Authoring connection records with stable ids and endpoint ids.
|
||||
- Required endpoint flag.
|
||||
|
||||
4. Implement `WorldEditorWindow`.
|
||||
- Use `EditorWindow`.
|
||||
- Use UI Toolkit.
|
||||
- Add menu item under the same family as Stage Editor, e.g. `Tools/Gardens Of Nil/World Editor`.
|
||||
- Top bar: `WorldLayoutSO` object field, create button, save button, validate button placeholder, commit button placeholder or disabled until PLN-0004.
|
||||
|
||||
5. Implement `WorldMapCanvas`.
|
||||
- Use `VisualElement.generateVisualContent`.
|
||||
- Render current `WorldLayer`.
|
||||
- Render grid, stage footprints, occupied tiles, endpoints, and basic connection indicators.
|
||||
- Implement pan/zoom behavior consistent with Stage Editor canvas patterns.
|
||||
|
||||
6. Implement basic editing operations.
|
||||
- Create/select Stage.
|
||||
- Paint or remove occupied WorldTiles for selected Stage.
|
||||
- Prevent obvious same-layer tile overlap at authoring time where possible.
|
||||
- Add socket on free tile face.
|
||||
- Add anchor or lift to tile, enforcing no anchor/lift coexistence.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- World Editor files live under `Assets/Scripts/Editor/GON/WorldEditor`.
|
||||
- `WorldLayoutSO` defaults to 24m tile size and 24m layer height.
|
||||
- World Editor opens from Unity menu.
|
||||
- World Editor uses `EditorWindow` and UI Toolkit.
|
||||
- Canvas uses `VisualElement.generateVisualContent`.
|
||||
- `WorldLayoutSO` is not consumed by runtime Journey code.
|
||||
- Stage Editor integration remains manual in V1.
|
||||
|
||||
## Validation
|
||||
|
||||
- Unity compile succeeds.
|
||||
- Open the World Editor window in Unity.
|
||||
- Create a `WorldLayoutSO` asset.
|
||||
- Author two stages on the same layer and verify same-tile overlap is prevented or reported.
|
||||
- Add socket, anchor, and lift authoring endpoints.
|
||||
- Verify anchor and lift cannot coexist on the same WorldTile.
|
||||
- Verify no generated Stage scene or Stage bake occurs from these authoring actions.
|
||||
- No automated tests are required for this phase.
|
||||
|
||||
## Risks
|
||||
|
||||
- UI scope can grow quickly; keep V1 focused on authoring enough data for commit.
|
||||
- If `StageDefinition` moved or changes namespace, keep references isolated inside editor-only code.
|
||||
- Editor-only `WorldLayoutSO` should not leak into runtime scenes or runtime Journey APIs.
|
||||
118
discussion/workflow/plans/PLN-0004-journey-commit-validation.md
Normal file
118
discussion/workflow/plans/PLN-0004-journey-commit-validation.md
Normal file
@ -0,0 +1,118 @@
|
||||
---
|
||||
id: PLN-0004
|
||||
ticket: world-editor-journey-spec
|
||||
title: Journey Commit and Validation
|
||||
status: review
|
||||
created: 2026-06-19
|
||||
decisions:
|
||||
- DEC-0001
|
||||
tags:
|
||||
- editor
|
||||
- validation
|
||||
- journey
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
Implement the explicit World Editor commit action that validates `WorldLayoutSO` and publishes only logical Journey data into `JGraphSO`.
|
||||
|
||||
## Source Decisions
|
||||
|
||||
- `DEC-0001`: World Editor / Journey V1.
|
||||
|
||||
## Target
|
||||
|
||||
Create the publication pipeline from `WorldLayoutSO` to `JGraphSO`:
|
||||
|
||||
- validation service,
|
||||
- error/warning reporting,
|
||||
- commit button behavior,
|
||||
- deterministic conversion to runtime logical Journey data,
|
||||
- publication metadata.
|
||||
|
||||
## Scope
|
||||
|
||||
- Editor-only validation and commit code.
|
||||
- Conversion from World Editor authoring records to runtime `JGraphSO`.
|
||||
- Generate/update `JStage`, `JEndpoint`, and `JConnection` records.
|
||||
- Preserve stable ids across repeated commits.
|
||||
- Block commit on errors.
|
||||
- Allow commit with warnings.
|
||||
|
||||
## Out Of Scope
|
||||
|
||||
- Stage scene generation.
|
||||
- Stage bake.
|
||||
- Loading hints.
|
||||
- Concrete requirements.
|
||||
- Runtime traversal behavior.
|
||||
- Automatic Stage Editor sync.
|
||||
- Unified editor shell.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Add validation types.
|
||||
- Target `Assets/Scripts/Editor/GON/WorldEditor`.
|
||||
- Create severity enum: error and warning.
|
||||
- Create validation message record with severity, message, and optional authoring object id.
|
||||
|
||||
2. Add `WorldLayoutValidator`.
|
||||
- Validate same-layer tile overlap.
|
||||
- Validate connection endpoints exist.
|
||||
- Validate connection does not connect an endpoint to itself.
|
||||
- Validate endpoint type compatibility.
|
||||
- Validate socket cardinality: at most one connection.
|
||||
- Validate socket face is a free Stage tile face.
|
||||
- Validate sockets connect opposite faces on adjacent tiles when physically connected.
|
||||
- Validate anchor/lift cannot coexist on same WorldTile.
|
||||
- Validate lift alignment by x/y and differing layer.
|
||||
- Validate lift cardinality: exactly one connection when required, at most one connection in all cases.
|
||||
- Validate required endpoint without connection as error.
|
||||
- Validate optional endpoint without connection as warning.
|
||||
|
||||
3. Add `JourneyCommitter`.
|
||||
- Input: `WorldLayoutSO` and target `JGraphSO`.
|
||||
- Run validation before writing.
|
||||
- If errors exist, abort without modifying `JGraphSO`.
|
||||
- If only warnings exist, allow commit and show warnings.
|
||||
- Write `sourceWorldLayoutId`, `publishedAt`, `schemaVersion`, and optional deterministic `contentHash`.
|
||||
- Write `JStage`, endpoint, and connection records only.
|
||||
- Do not create Stage scenes, Stage geometry, Stage objects, or Stage bake artifacts.
|
||||
|
||||
4. Wire commit into `WorldEditorWindow`.
|
||||
- Add or enable commit button.
|
||||
- Let the user choose/create a target `JGraphSO`.
|
||||
- Display validation messages after commit attempt.
|
||||
- Mark changed assets dirty and save through Unity asset APIs.
|
||||
|
||||
5. Add validation display.
|
||||
- Reuse UI Toolkit patterns from the Stage Editor inspector/top bar where practical.
|
||||
- Show errors and warnings clearly.
|
||||
- Keep visual polish secondary to correctness for V1.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Commit button publishes `JGraphSO` only.
|
||||
- Commit button never generates Stage scenes or Stage bake output.
|
||||
- Commit aborts when validation errors exist.
|
||||
- Commit can proceed with warnings.
|
||||
- Required endpoint without connection is an error.
|
||||
- Optional endpoint without connection is a warning.
|
||||
- `JGraphSO` publication metadata is written on successful commit.
|
||||
- Repeated commits preserve stable ids rather than regenerating ids from names or positions.
|
||||
|
||||
## Validation
|
||||
|
||||
- Unity compile succeeds.
|
||||
- Manually verify commit of a minimal valid layout with two stages and a socket connection.
|
||||
- Manually verify commit aborts when two stages overlap on the same WorldLayer tile.
|
||||
- Manually verify commit aborts when a required endpoint has no connection.
|
||||
- Manually verify commit allows an optional unconnected endpoint and reports a warning.
|
||||
- Manually verify no Stage scene, Stage geometry, or Stage bake output is created by commit.
|
||||
- No automated tests are required for this phase.
|
||||
|
||||
## Risks
|
||||
|
||||
- Id preservation can be broken if conversion derives ids from mutable fields; use stored stable ids from authoring data.
|
||||
- Validation and commit can become coupled to UI; keep validation and conversion in separate services.
|
||||
- Content hash can become noisy if it includes non-deterministic ordering or timestamps; omit or narrow it if deterministic hashing is not cheap.
|
||||
Loading…
x
Reference in New Issue
Block a user