---
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.
