---
id: DEC-0002
ticket: world-stage-editor-sync
title: World Editor / Stage Editor Sync V1
status: accepted
created: 2026-06-20
accepted: 2026-06-20
agenda: AGD-0002
plans:
  - PLN-0005
  - PLN-0006
  - PLN-0007
  - PLN-0008
tags:
  - world-editor
  - stage-editor
  - sync
  - stage-definition
---

## Status

Accepted.

This decision defines the V1 contract for synchronizing a World Editor stage with a Stage Editor `StageDefinition`.

## Contexto

The World Editor owns macro-world authoring through `WorldLayoutSO`: stage placement, WorldLayer, WorldTile footprint, special stage kind, Journey endpoints, and Journey connections.

The Stage Editor owns internal stage authoring through `StageDefinition`: floors, cells, internal objects, markers, scene bake, and generated scene content.

`WorldStageAuthoring` already contains an optional `StageDefinition` reference, but the reference is currently manual. Designers need a contextual way to create or synchronize a `StageDefinition` from the selected World Editor stage without turning the World Editor into a Stage Editor.

## Decisao

The World Editor SHALL provide a contextual `Create/Sync StageDefinition` action inside the inspector for the selected world stage.

The action SHALL be create-or-sync:

- If the selected world stage has no `StageDefinition`, the action MUST create a new `StageDefinition` asset and assign it to `WorldStageAuthoring.stageDefinition`.
- If the selected world stage already has a `StageDefinition`, the action MUST update only world-sync contract data on that asset.

The sync data MUST be stored in a dedicated `StageWorldSyncData` structure inside `StageDefinition`. Sync data MUST NOT be scattered as unrelated top-level fields unless a later decision explicitly revises this model.

The sync action MUST NOT generate internal stage geometry, floor cells, props, enemies, puzzles, baked scene content, or final gameplay objects in V1.

## Rationale

The chosen model reduces authoring friction while preserving editor ownership boundaries.

Keeping sync metadata inside `StageDefinition` gives the Stage Editor enough context to show what the World Editor expects, while still letting the Stage Editor remain responsible for internal playable content.

A contextual inspector button avoids accidental global sync and keeps the operation tied to the selected world stage. A passive sync contract avoids destructive merge problems, keeps V1 focused on read-only guidance, and leaves a clear place for a future explicit endpoint marker model.

## Invariantes / Contrato

### Button Placement

The initial sync button MUST live in the World Editor inspector for the selected stage.

The button label SHOULD be `Create StageDefinition` when no asset is assigned and `Sync StageDefinition` when an asset is already assigned.

The World Editor MAY also expose a contextual `Open Stage Editor` button for the assigned `StageDefinition`.

V1 MUST NOT include `Sync All Stage Definitions`.

### Asset Creation

Generated `StageDefinition` assets MUST be saved by default under a `Stages` folder next to the source `WorldLayoutSO`.

The editor MUST create that `Stages` folder automatically when needed.

Generated assets SHOULD use stable, readable names derived from the world stage display name or id.

### StageWorldSyncData

`StageDefinition` MUST contain a dedicated sync structure named `StageWorldSyncData` or an equivalent clearly named type.

The sync structure MUST contain the world-derived contract data. At minimum it MUST support:

- `worldLayoutId`;
- `worldStageId`;
- `worldStageDisplayName`;
- `worldStageKind`;
- `worldLayer`;
- `worldTileSize`;
- `worldLayerHeight`;
- `worldTiles`;
- derived `worldBounds` or enough data to compute it;
- expected endpoints for the stage;
- `syncedAt`;
- `contractVersion`;
- `contractHash`.

Expected endpoint records MUST support:

- `endpointId`;
- endpoint kind;
- WorldTile coordinate;
- socket face when the endpoint is a socket;
- required flag;
- related connection ids or connected endpoint ids as debug/validation context.

Visual-only world data, such as stage color, MUST NOT be part of `contractHash`.

### Contract Hash

The `contractHash` MUST be computed from stable world contract data:

- world layout id;
- world stage id;
- world stage display name;
- stage kind;
- world layer;
- world tile size;
- world layer height;
- footprint tiles;
- expected endpoint data.

The hash is used to detect whether a `StageDefinition` is out of date relative to the selected world stage.

### Non-Destructive Sync

Sync MUST NOT overwrite Stage Editor authored floors, cells, internal objects, markers, or bake data.

If an endpoint is removed from the World Editor, sync MUST remove it from the passive expected-endpoints contract.

V1 has no compatibility requirement for temporary test stages or prototype `StageDefinition` assets already created during editor development. Those assets MAY be recreated, manually updated, or discarded.

### Stage Editor Representation

V1 MUST represent World Editor expectations as passive contract data in `StageWorldSyncData`.

The Stage Editor SHALL render a passive World Sync underlay derived from `StageWorldSyncData`.

Endpoint implementation markers are out of scope for V1. The sync data model SHOULD keep endpoint identity explicit enough to support a later dedicated marker model, preferably a `StageEndpointMarkerDefinition`-style list rather than overloading gameplay `StageObjectDefinition` records.

### World Sync Underlay

The World Sync underlay MUST be read-only visual guidance. It MUST NOT create, edit, delete, or block interaction with Stage Editor cells, objects, markers, floors, or bake data.

The underlay MUST be drawn beneath authored Stage Editor content so it guides the designer without obscuring cells, objects, selections, or editing handles.

The underlay SHOULD be toggleable.

The underlay MUST convert World Editor `WorldTile` coordinates into Stage Editor space using the synced world tile size. With the current V1 defaults, one WorldTile corresponds to a `24x24` cell block when `StageDefinition.cellSize` is `1m`.

The underlay visual language SHALL be:

- WorldTile footprint from the World Editor: magenta hatching.
- WorldTile containing an expected anchor: cyan hatching.
- WorldTile containing an expected lift: red hatching.
- Expected socket: yellow highlight on the corresponding face of the WorldTile block.

Socket face hints MUST be drawn on the face where the World Editor expects the socket, not as a filled tile.

Save points MUST NOT have special visual treatment in the underlay. A save point SHALL be shown like a normal stage: magenta hatching for its footprint and yellow socket face hints when sockets exist. The designer remains responsible for knowing that the synced stage is a save point through metadata, inspector state, and validation, not through a special underlay symbol.

### Save Point

Save points MUST sync as contract metadata only:

- `worldStageKind = SavePoint`;
- footprint `1x1`;
- expected endpoints.

V1 MUST NOT generate a special internal save point template, floor layout, or object set in `StageDefinition`.

### Validation

The World Editor SHOULD warn when a world stage has no assigned `StageDefinition`.

The World Editor MUST treat a `StageDefinition` synced to a different `worldStageId` as an error.

The World Editor or Stage Editor SHOULD warn when `contractHash` is out of date.

## Impactos

### World Editor

The World Editor inspector must gain contextual actions for the selected stage:

- create/sync `StageDefinition`;
- optionally open the assigned `StageDefinition` in the Stage Editor.

The World Editor validator must understand missing, mismatched, and outdated `StageDefinition` sync state.

### Stage Editor

`StageDefinition` must gain sync data that is editor-only and separate from internal geometry.

The Stage Editor must render the passive World Sync underlay beneath authored content. V1 does not require endpoint marker authoring.

### Runtime / Journey

No runtime Journey contract changes are required by this decision.

`StageWorldSyncData` remains editor-only. Runtime code MUST continue to consume `JGraphSO`, not `StageDefinition` or `WorldLayoutSO`.

### Tooling

Asset creation needs deterministic default paths based on the source `WorldLayoutSO` asset location.

## Referencias

- Agenda: `discussion/workflow/agendas/AGD-0002-world-stage-editor-sync.md`
- Existing World Editor / Journey spec: `specs/world-editor-journey-v1.md`
- Lesson from previous decision: `discussion/lessons/DSC-0001-world-editor-journey-spec/LSN-0001-editor-authoring-runtime-publication.md`
- Stage Editor source: `Assets/Scripts/Editor/GON/StageEditor/StageDefinition.cs`
- World Editor source: `Assets/Scripts/Editor/GON/WorldEditor/WorldLayoutSO.cs`

## Propagacao Necessaria

- Add `StageWorldSyncData` and endpoint sync records to `StageDefinition`.
- Add create/sync and open actions to the World Editor stage inspector.
- Implement deterministic StageDefinition asset creation under a `Stages` folder next to the `WorldLayoutSO`.
- Add sync hash generation and stale/mismatch validation.
- Update Stage Editor UI to show passive sync state and render the World Sync underlay.

## Revision Log

- 2026-06-20: Initial accepted decision from AGD-0002.
- 2026-06-21: Added read-only Stage Editor World Sync underlay rules, including hatching colors, socket face hints, and save point visual behavior.
- 2026-06-21: Clarified that V1 has no compatibility requirement for temporary test StageDefinitions while still keeping endpoint identity suitable for a future explicit marker model.
