---
id: AGD-0002
ticket: world-stage-editor-sync
title: World Editor / Stage Editor Sync
status: accepted
created: 2026-06-20
resolved: 2026-06-20
decision: DEC-0002
tags:
  - world-editor
  - stage-editor
  - sync
  - stage-definition
---

## Contexto

O World Editor ja possui `WorldLayoutSO` como asset editorial de macro-mundo e consegue criar stages, save points, footprints, sockets, anchors, lifts e connections. O Stage Editor ja possui `StageDefinition`, atualmente em `Assets/Scripts/Editor/GON/StageEditor/StageDefinition.cs`, com floors, cells e objetos internos de stage.

Na decisao anterior, o World Editor ficou responsavel por publicar apenas dados logicos de Journey em `JGraphSO`. O bake e a geometria interna continuam sendo responsabilidade do Stage Editor. Agora existe uma nova necessidade: o World Editor deve ajudar a criar ou sincronizar um `StageDefinition` que o Stage Editor consiga abrir e usar sem configuracao manual repetitiva.

Hoje o `WorldStageAuthoring` ja tem uma referencia opcional para `StageDefinition`, mas essa referencia e manual. Falta definir qual botao/fluxo cria, atualiza, valida ou abre o asset correspondente.

Atualizacao de direcao em 2026-06-20: o usuario prefere que o botao fique dentro do inspector do stage selecionado no World Editor, nao na topbar nem em uma acao global inicial. Esse botao deve operar como **create-or-sync**: se o stage ainda nao possui `StageDefinition`, cria um asset herdando valores relevantes do World Editor; se ja possui, sincroniza os dados de contrato.

## Problema

O designer cria e posiciona stages no World Editor, mas ainda precisa criar ou associar manualmente um `StageDefinition` para trabalhar no Stage Editor. Isso cria friccao e risco de divergencia:

- stage existe no World Editor mas nao tem `StageDefinition`;
- `StageDefinition` existe mas nao sabe de qual world stage veio;
- endpoints declarados no World Editor nao tem markers correspondentes no Stage Editor;
- mudancas no footprint ou no tipo especial do stage podem nao ser refletidas no Stage Editor;
- validacoes entre os dois editores ainda nao tem contrato claro.

Precisamos discutir se o World Editor deve gerar `StageDefinition`, sincronizar metadados, criar markers, abrir o Stage Editor, ou apenas manter referencias.

## Pontos Criticos

- `StageDefinition` e editor-only; nao deve virar runtime Journey.
- `WorldLayoutSO` tambem e editor-only, mas e a fonte autoral do macro-mundo.
- O Stage Editor deve continuar dono da geometria interna, floors, objetos, bake e cena.
- O World Editor sabe o footprint macro, endpoints e tipo do stage, mas nao sabe paredes internas, layout jogavel nem objetos finais.
- Gerar conteudo interno demais a partir do World Editor pode invadir a responsabilidade do Stage Editor.
- Sincronizacao destrutiva pode apagar trabalho manual do Stage Editor.
- Endpoints precisam de algum vinculo futuro com markers internos do stage para validar implementacao.
- Save points podem exigir template inicial especial no Stage Editor.
- O local do botao importa para UX: no inspector do stage selecionado, a acao fica contextual e reduz risco de sincronizar o stage errado.
- Os dados sincronizados precisam ser claramente identificados como "contrato herdado do World Editor", nao como geometria interna autoral do Stage Editor.

## Opcoes

### Opcao A - World Editor apenas cria e associa StageDefinition vazio

- **Abordagem:** adicionar botao no World Editor para criar um `StageDefinition` se o stage selecionado ainda nao tiver um. O asset recebe id/nome derivados do world stage e fica referenciado no `WorldStageAuthoring.stageDefinition`.
- **Pro:** simples, pouco invasivo, reduz friccao imediata.
- **Contra:** nao sincroniza endpoints, footprint, save point ou revisoes.
- **Manutencao:** baixa complexidade, mas pode virar insuficiente rapidamente.

### Opcao B - World Editor cria/atualiza StageDefinition com metadados de sync

- **Abordagem:** `StageDefinition` passa a guardar metadados editoriais de origem: `worldStageId`, world layer, footprint macro, endpoints esperados e possivelmente uma versao/hash de sync. O botao `Sync Stage Definition` fica no inspector do stage selecionado no World Editor e cria ou atualiza esses dados sem mexer na geometria interna.
- **Pro:** cria contrato rastreavel entre editores e permite validacao cruzada.
- **Contra:** exige alterar `StageDefinition` e definir o que e autoritativo em cada campo.
- **Manutencao:** boa se os campos forem claramente de contrato/sync e nao de geometria final.

### Opcao C - World Editor gera templates internos iniciais no StageDefinition

- **Abordagem:** alem de metadados, o World Editor cria floors/cells/markers iniciais no Stage Editor baseados no footprint e endpoints. Save point poderia gerar um stage 1x1 com estrutura minima.
- **Pro:** acelera prototipagem e cria um primeiro layout jogavel.
- **Contra:** alto risco de sobrescrever trabalho autoral; mistura macro footprint com geometria interna real; exige regras de merge.
- **Manutencao:** mais caro, porque cada evolucao do Stage Editor precisa considerar geracao/merge.

### Opcao D - Criar um asset intermediario de contrato StageSync

- **Abordagem:** World Editor gera um asset separado de sync por stage, e o Stage Editor le esse asset. `StageDefinition` referencia esse contrato ou importa dele manualmente.
- **Pro:** separa ainda mais contrato de geometria interna.
- **Contra:** cria mais um asset e mais fluxo de authoring; pode ser excesso para V1.
- **Manutencao:** boa para sistemas grandes, pesada para a fase atual.

## Sugestao / Recomendacao

Recomendacao inicial: seguir a **Opcao B** de forma conservadora, com o botao localizado no **inspector do stage selecionado** no World Editor.

O World Editor deve ter um botao contextual de sync para o stage selecionado:

```text
World Stage selecionado
↓
Inspector do Stage
↓
Create/Sync StageDefinition
↓
se nao existir StageDefinition: criar asset
se existir: atualizar somente metadados de contrato/sync
↓
associar StageDefinition ao WorldStageAuthoring
↓
opcionalmente abrir Stage Editor com esse StageDefinition
```

O sync nao deve gerar geometria interna nem objetos finais na V1. Ele deve apenas garantir que o Stage Editor saiba:

- qual `worldStageId` originou o stage;
- qual e o nome/display name esperado;
- qual e o footprint macro;
- qual e o `WorldLayer`;
- quais endpoints o stage deve implementar;
- qual e a versao/hash do contrato sincronizado;
- se o stage e especial, como `SavePoint`.

Isso cria base para validacao futura sem invadir o Stage Editor.

### Dados Relevantes para Sync

Dados que parecem relevantes para gravar no `StageDefinition` como contrato herdado do World Editor:

- `worldLayoutId`: identifica o layout autoral de origem.
- `worldStageId`: id estavel do stage no World Editor.
- `worldStageDisplayName`: nome esperado no macro-mundo.
- `worldStageKind`: stage comum, `SavePoint`, ou futuros tipos especiais.
- `worldLayer`: camada macro onde o stage vive.
- `worldTileSize`: tamanho do WorldTile no momento do sync.
- `worldLayerHeight`: altura macro do layer no momento do sync.
- `worldTiles`: footprint macro ocupado pelo stage.
- `worldBounds`: bounds derivados do footprint, util para visualizacao/validacao.
- `endpoints`: lista dos endpoints esperados para esse stage.
- `connections`: opcionalmente ids das conexoes relacionadas, apenas como contexto de validacao.
- `syncedAt`: timestamp editorial.
- `syncVersion` ou `contractVersion`: versao do formato de sync.
- `contractHash`: hash dos dados herdados para detectar divergencia.

Dados de endpoint relevantes:

- `endpointId`: id estavel do endpoint no World Editor/Journey.
- `kind`: socket, anchor ou lift.
- `worldTile`: tile macro dentro do world layout.
- `socketFace`: apenas para sockets.
- `required`: se a implementacao no Stage Editor deve ser obrigatoria.
- `connectedEndpointIds` ou `connectionIds`: contexto para validacao e debug.

### Representacao no Stage Editor

Ha duas camadas possiveis:

1. **Contrato sincronizado passivo:** uma lista serializada no `StageDefinition`, por exemplo `StageWorldSyncData`, contendo footprint e endpoints esperados. O Stage Editor mostra essa informacao e valida implementacao, mas nao cria objetos jogaveis automaticamente.
2. **Markers internos implementaveis:** objetos/markers no layer `Markers` associados a `endpointId`, indicando onde o designer implementou a porta, portal, lift ou save point dentro do stage real.

Recomendacao atual: comecar pela camada 1 e preparar a arquitetura para a camada 2. O contrato passivo evita sobrescrever trabalho autoral e permite que os markers sejam introduzidos depois com uma decisao menor.

Para V1, o Stage Editor poderia exibir:

- uma secao "World Sync" no inspector do stage;
- status "Not Synced / Synced / Outdated";
- lista de endpoints esperados;
- warnings quando endpoint obrigatorio ainda nao tem marker interno associado;
- destaque especial para `SavePoint`.

Markers internos podem vir depois como extensao de `StageObjectDefinition` ou como uma nova lista especifica de markers. Usar `StageObjectDefinition` agora pode ser conveniente, mas talvez misture objeto jogavel com contrato editorial. Uma lista especifica como `StageEndpointMarkerDefinition` tende a deixar a fronteira mais clara.

## Perguntas em Aberto

- [x] O `StageDefinition` deve guardar diretamente `worldStageId`, footprint e endpoints esperados, ou isso deve ficar em uma sub-struct como `StageWorldSyncData`?
- [x] O botao inicial deve ser contextual, dentro do inspector do stage selecionado no World Editor.
- [x] Tambem deve existir futuramente `Sync All Stage Definitions`, ou isso fica fora da V1?
- [x] Onde os assets gerados devem ser salvos por padrao?
- [x] O sync deve criar pastas automaticamente por world/stage?
- [x] O sync deve abrir o Stage Editor automaticamente apos criar/associar o asset?
- [x] Como representar endpoints esperados no Stage Editor: lista passiva de contrato, markers internos, ou ambos?
- [x] Se houver markers internos, eles devem ser `StageObjectDefinition`, nova lista `StageEndpointMarkerDefinition`, ou outro modelo?
- [x] Se um endpoint for removido no World Editor, o sync remove o marker no StageDefinition ou apenas marca como stale?
- [x] Save Point deve gerar algum template inicial no StageDefinition ou apenas metadata `stageKind = SavePoint`?
- [x] Como detectar alteracao manual no StageDefinition desde o ultimo sync?
- [x] O Stage Editor deve validar "endpoint esperado ainda nao implementado" como warning ou erro?
- [x] O sync deve copiar apenas ids/dados estaveis ou tambem dados visuais como cor/nome do World Stage?
- [x] O `contractHash` deve considerar somente footprint/endpoints ou tambem nome/tipo/layer?

## Criterio para Encerrar

A agenda pode virar decisao quando fecharmos:

- o escopo do botao de sync;
- quais dados o `StageDefinition` deve receber;
- como esses dados sao agrupados no `StageDefinition`;
- quais dados o sync nunca pode sobrescrever;
- comportamento para criar asset novo versus atualizar asset existente;
- comportamento de abertura do Stage Editor;
- validacoes minimas entre World Editor e Stage Editor;
- tratamento inicial de Save Point e endpoints.

## Discussion

Entrada inicial em 2026-06-20: o usuario solicitou uma agenda para discutir um botao no World Editor capaz de sincronizar ou gerar um `StageDefinition` legivel pelo Stage Editor, cobrindo dados de sync, comportamento e validacao entre editores.

Atualizacao em 2026-06-20: o usuario definiu preferencia de UX para o botao dentro do inspector do stage selecionado. O botao deve criar o `StageDefinition` com valores herdados do World Editor quando ainda nao existir, ou sincronizar o asset existente quando ja houver referencia. A discussao deve focar quais dados sao relevantes e como representa-los no Stage Editor.

## Resolution

Resolucao em 2026-06-20: a V1 de integracao World Editor / Stage Editor deve seguir a Opcao B conservadora.

Decisoes aceitas para emissao da decisao:

- O botao inicial deve ficar no inspector do stage selecionado no World Editor.
- O botao deve operar como `Create/Sync StageDefinition`.
- Se o stage nao tiver `StageDefinition`, o botao cria um asset novo e associa ao `WorldStageAuthoring`.
- Se o stage ja tiver `StageDefinition`, o botao atualiza apenas dados de contrato/sync herdados do World Editor.
- Os dados herdados devem ficar agrupados em uma sub-struct clara no `StageDefinition`, chamada inicialmente de `StageWorldSyncData`.
- Assets gerados devem ser salvos por padrao em uma pasta `Stages` ao lado do `WorldLayoutSO`, criando a pasta automaticamente quando necessario.
- V1 nao precisa de `Sync All Stage Definitions`.
- O botao principal nao deve abrir automaticamente o Stage Editor. Um segundo botao contextual, `Open Stage Editor`, pode existir no inspector.
- V1 deve representar endpoints esperados como lista passiva de contrato em `StageWorldSyncData`.
- Markers internos de endpoint ficam fora da V1, mas a arquitetura deve permitir uma lista futura especifica como `StageEndpointMarkerDefinition`.
- Sync nao deve remover dados autorais nem markers futuros automaticamente; endpoints removidos no World Editor devem sair do contrato sincronizado, e implementacoes futuras podem ser marcadas como stale.
- Save Point deve sincronizar apenas metadata/contrato (`stageKind = SavePoint`, footprint 1x1 e endpoints esperados), sem gerar template interno de geometria na V1.
- Alteracao/desatualizacao deve ser detectada por `contractHash` calculado sobre os dados herdados do World Editor.
- O hash deve considerar dados de contrato estavel: world layout id, world stage id, display name, stage kind, world layer, tile/layer sizes, footprint e endpoints esperados. Cor visual nao deve fazer parte do hash.
- `StageDefinition` ausente no World stage deve ser warning.
- `StageDefinition` sincronizado com outro `worldStageId` deve ser error.
- Sync desatualizado deve ser warning.
- Endpoint obrigatorio sem implementacao interna deve ser warning na V1, pois markers internos ainda nao sao parte do contrato.
