Intrepid/gardens-of-nil-3d-u6
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
gardens-of-nil-3d-u6/discussion/workflow/decisions/DEC-0001-world-editor-journey-v1.md
Nilton Constantino 7921b95a29
World Editor / Journey Spec
2026-06-19 13:35:31 +01:00

6.4 KiB
Raw Blame History

id ticket title status created accepted agenda plans tags
DEC-0001 world-editor-journey-spec World Editor / Journey V1 accepted 2026-06-19 2026-06-19 AGD-0001
PLN-0001
PLN-0002
PLN-0003
PLN-0004
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.