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