---
id: PLN-0008
ticket: world-stage-editor-sync
title: Stage Editor World Sync Underlay
status: open
created: 2026-06-21
completed:
tags:
  - stage-editor
  - world-sync
  - underlay
---

## Objective

Render the passive World Sync underlay in the Stage Editor using `StageWorldSyncData`.

## Background

`DEC-0002` requires the Stage Editor to render read-only guidance under authored content. The underlay must show World Editor footprint and expected endpoints without changing cells, objects, markers, floors, or bake data.

## Decisions of Origin

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

## Scope

### Included

- Draw synced WorldTile footprint as magenta hatching.
- Draw WorldTiles containing expected anchors as cyan hatching.
- Draw WorldTiles containing expected lifts as red hatching.
- Draw expected socket faces as yellow highlights on the correct WorldTile block face.
- Draw under authored cells, objects, selections, and editing handles.
- Add a toggle for the underlay.
- Treat save points like normal stages in the underlay.

### Excluded

- Creating stage cells from the underlay.
- Creating endpoint markers.
- Special save point symbol/template in Stage Editor.
- Runtime Journey changes.

## Execution Steps

### Step 1 - Add underlay toggle state

**What:** Add a UI/state flag controlling underlay visibility.

**How:** Add a bool to `StageEditorState` or `StageEditorWindow`, defaulting to visible when sync data exists. Add a compact toggle in the Stage Editor UI.

**File(s):**

- `Assets/Scripts/Editor/GON/StageEditor/StageEditorState.cs`
- `Assets/Scripts/Editor/GON/StageEditor/StageEditorWindow.cs`
- `Assets/Scripts/Editor/GON/StageEditor/StageInspectorPanel.cs`

### Step 2 - Convert WorldTile blocks to stage cells

**What:** Compute underlay rectangles in Stage Editor cell space.

**How:** Use `StageDefinition.worldSync.worldTileSize / StageDefinition.cellSize` to derive cells per WorldTile. With defaults this is `24`. Convert each synced world tile into a `RectInt` block.

**File(s):**

- `Assets/Scripts/Editor/GON/StageEditor/StageMapCanvas.cs`

### Step 3 - Draw underlay before authored content

**What:** Render guidance beneath existing stage content.

**How:** In `StageMapCanvas.OnGenerateVisualContent`, draw the underlay after background/grid if appropriate but before cells, objects, selection, and handles.

**File(s):**

- `Assets/Scripts/Editor/GON/StageEditor/StageMapCanvas.cs`

### Step 4 - Implement hatching and face hints

**What:** Add visual primitives for hatching and socket face highlights.

**How:** Add helper methods to draw diagonal hatching inside `Rect` blocks and thick yellow lines on block faces. Use:

- magenta for footprint;
- cyan for anchor tiles;
- red for lift tiles;
- yellow for socket faces.

**File(s):**

- `Assets/Scripts/Editor/GON/StageEditor/StageMapCanvas.cs`
- `Assets/Scripts/Editor/GON/StageEditor/StageEditorColors.cs`

### Step 5 - Keep save point visual behavior normal

**What:** Ensure save point has no special Stage Editor symbol.

**How:** Do not draw `S`, special color, or special geometry for `worldStageKind = SavePoint`. It uses normal footprint hatching and socket face hints.

**File(s):**

- `Assets/Scripts/Editor/GON/StageEditor/StageMapCanvas.cs`

## Test Requirements

### Unit Tests

- None required unless an editor test harness exists.

### Integration Tests

- Compile `Assembly-CSharp-Editor`.

### Manual Verification

- Open a synced `StageDefinition` in Stage Editor and confirm underlay appears below authored content.
- Confirm `24m` world tile maps to `24x24` cells when `cellSize = 1`.
- Confirm footprint, anchor, lift, and socket face colors match DEC-0002.
- Confirm underlay does not block selection, painting, moving, or resizing authored stage objects.
- Confirm save point sync shows no special symbol.
- Toggle underlay off and on.

## Acceptance Criteria

- [ ] Underlay renders beneath authored cells and objects.
- [ ] Magenta hatching appears for synced footprint.
- [ ] Cyan hatching appears for expected anchor tiles.
- [ ] Red hatching appears for expected lift tiles.
- [ ] Yellow socket face hints appear on correct block faces.
- [ ] Save points have no special underlay symbol or color.
- [ ] Underlay is toggleable.
- [ ] Underlay does not mutate `StageDefinition` authored content.
- [ ] `Assembly-CSharp-Editor` compiles.

## Dependencies

- `PLN-0005` must be implemented first.
- `PLN-0006` is needed to produce real synced data for manual verification.

## Risks

- Underlay can become visually noisy; draw it beneath content and keep colors translucent/hatch-based.
- Cell-size conversions must avoid fractional rendering ambiguity. Use stable integer or float conversion rules and document the behavior.
