144 lines
6.4 KiB
Markdown
144 lines
6.4 KiB
Markdown
---
|
|
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.
|