---
id: PLN-0006
ticket: world-stage-editor-sync
title: World Editor StageDefinition Sync Action
status: open
created: 2026-06-21
completed:
tags:
  - world-editor
  - stage-definition
  - sync
---

## Objective

Implement the contextual `Create/Sync StageDefinition` action in the World Editor stage inspector.

## Background

`DEC-0002` requires a create-or-sync action inside the inspector for the selected world stage. It must create a `StageDefinition` if missing, or update only passive sync contract data if present.

## Decisions of Origin

- `DEC-0002`: World Editor / Stage Editor Sync V1.

## Scope

### Included

- Add a contextual `Create StageDefinition` / `Sync StageDefinition` button to the World Editor stage inspector.
- Create generated assets under a `Stages` folder next to the source `WorldLayoutSO`.
- Assign generated assets to `WorldStageAuthoring.stageDefinition`.
- Populate `StageWorldSyncData` from `WorldLayoutSO` and the selected stage.
- Compute `contractHash` from stable world contract data.
- Add optional contextual `Open Stage Editor` button for assigned assets.

### Excluded

- Stage Editor underlay rendering.
- Stage Editor validation UI.
- Runtime Journey changes.
- `Sync All Stage Definitions`.
- Compatibility migration for temporary prototype assets.

## Execution Steps

### Step 1 - Add sync helper

**What:** Create a helper responsible for converting a selected `WorldStageAuthoring` into `StageWorldSyncData`.

**How:** Add an editor class such as `StageDefinitionSyncer` under World Editor or shared editor tooling. It should:

- collect world layout id;
- collect stage id, display name, kind, layer, footprint, tile size, and layer height;
- collect endpoints owned by the stage;
- collect related connection ids or connected endpoint ids;
- compute `contractHash` excluding visual-only color.

**File(s):**

- `Assets/Scripts/Editor/GON/WorldEditor/StageDefinitionSyncer.cs`
- `Assets/Scripts/Editor/GON/WorldEditor/WorldLayoutSO.cs`
- `Assets/Scripts/Editor/GON/StageEditor/StageDefinition.cs`

### Step 2 - Implement deterministic asset path

**What:** Generate new `StageDefinition` assets in the required default location.

**How:** Resolve `AssetDatabase.GetAssetPath(worldLayout)`, create a sibling `Stages` folder if missing, sanitize a readable asset filename from stage display name or id, and create the asset there.

**File(s):**

- `Assets/Scripts/Editor/GON/WorldEditor/StageDefinitionSyncer.cs`

### Step 3 - Add inspector actions

**What:** Add contextual buttons to the selected stage inspector.

**How:** In `WorldInspectorPanel.BuildStageInspector`, add:

- `Create StageDefinition` when `stage.stageDefinition` is null;
- `Sync StageDefinition` when assigned;
- optional `Open Stage Editor` when assigned.

Use `owner.MutateLayout` or an equivalent undo-safe mutation for assignment and dirty state.

**File(s):**

- `Assets/Scripts/Editor/GON/WorldEditor/WorldInspectorPanel.cs`
- `Assets/Scripts/Editor/GON/WorldEditor/WorldEditorWindow.cs`

### Step 4 - Sync only contract data

**What:** Ensure sync does not mutate authored Stage Editor data.

**How:** Sync must only update `StageDefinition.worldSync` and asset metadata necessary for identification. It must not edit floors, cells, objects, markers, or bake data.

**File(s):**

- `Assets/Scripts/Editor/GON/WorldEditor/StageDefinitionSyncer.cs`

### Step 5 - Open Stage Editor

**What:** Add a button to open the assigned `StageDefinition`.

**How:** Expose a safe Stage Editor entry point if one does not already exist, or set `Selection.activeObject` and open the existing Stage Editor window with the selected asset.

**File(s):**

- `Assets/Scripts/Editor/GON/StageEditor/StageEditorWindow.cs`
- `Assets/Scripts/Editor/GON/WorldEditor/WorldInspectorPanel.cs`

## Test Requirements

### Unit Tests

- None required unless an editor test harness exists.

### Integration Tests

- Compile `Assembly-CSharp-Editor`.

### Manual Verification

- Select a world stage with no `StageDefinition`, click create, and confirm an asset appears under sibling `Stages`.
- Confirm the world stage now references the created asset.
- Change the world stage footprint/endpoints, click sync, and confirm only `worldSync` changes.
- Confirm floors/cells/objects remain unchanged after sync.
- Open the assigned Stage Editor asset from the inspector.

## Acceptance Criteria

- [ ] World stage inspector contains contextual create/sync action.
- [ ] Missing `StageDefinition` is created under `<WorldLayoutFolder>/Stages`.
- [ ] Existing `StageDefinition` receives updated `StageWorldSyncData`.
- [ ] Sync does not change authored floors, cells, objects, markers, or bake data.
- [ ] Contract hash excludes visual-only stage color.
- [ ] Optional `Open Stage Editor` action opens the assigned asset.
- [ ] `Assembly-CSharp-Editor` compiles.

## Dependencies

- `PLN-0005` must be implemented first.

## Risks

- Asset path generation can produce duplicate names; implementation must avoid overwriting existing assets.
- Opening the Stage Editor may require a small public API on `StageEditorWindow`.
