gardens-of-nil-3d-u6/discussion/workflow/plans/PLN-0003-world-editor-authoring.md

id	ticket	title	status	created	decisions	tags
PLN-0003	world-editor-journey-spec	World Editor Authoring UI and WorldLayoutSO	done	2026-06-19	DEC-0001	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.