gardens-of-nil-3d-u6/discussion/lessons/DSC-0001-world-editor-journey-spec/LSN-0001-editor-authoring-runtime-publication.md

id	ticket	title	created	tags
LSN-0001	world-editor-journey-spec	Separate editor authoring data from runtime Journey publication	2026-06-20	world-editor journey unity scriptableobjects

Context

The Gardens of Nil World Editor needs to organize the macro-world while the Stage Editor owns internal stage content. The first Journey implementation had to support editor iteration without letting unfinished authoring data leak into gameplay playtests.

The resulting model uses two ScriptableObject layers:

• WorldLayoutSO is editor-only authoring data for stages, footprints, endpoints, and connections.
• JGraphSO is the published runtime Journey graph consumed by gameplay code.

Key Decisions

World Editor / Journey V1

What: Keep world authoring data under editor code and publish a separate runtime-safe Journey graph through an explicit commit action.

Why: Designers need to edit incomplete worlds without changing the runtime contract used by playtests. Gameplay code should depend on stable Journey data and must not reference editor-only types.

Trade-offs: The model requires a publication step and validation rules between authoring and runtime data. In exchange, it avoids coupling runtime traversal to mutable editor state and keeps Stage bake ownership separate from world topology authoring.

Patterns and Algorithms

• Treat editor assets as work-in-progress sources of truth, not runtime APIs.
• Publish runtime data through a deliberate commit action after validation.
• Keep generated runtime records plain and queryable: JStage, JEndpoint, JConnection, and JGraphSO.
• Use stable string ids for cross-editor contracts because Unity object references are not enough to bridge World Editor, Stage Editor, and runtime data safely.
• Model physical transition space as stages, not as connections. JConnection remains logical and never owns space.

Pitfalls

• If runtime code reads editor-only data directly, playtests can accidentally depend on incomplete authoring changes.
• If connections own physical space, the boundary between World Editor and Stage Editor becomes ambiguous.
• If validation does not prune stale authoring records, deleted or moved stages can leave invisible data that still affects Journey publication.
• If StageDefinition becomes the runtime Journey contract, the Stage Editor and runtime traversal become coupled too early.

Takeaways

• Use WorldLayoutSO for authoring and JGraphSO for runtime Journey.
• Keep commit/publish explicit and validation-driven.
• Keep Journey runtime code outside Assets/Scripts/Editor.
• Preserve Stage Editor ownership of scene geometry and bake output.