Studio scene pack contract for runtime SCENE binary payload
This commit is contained in:
@@ -175,22 +175,23 @@ Os pontos mais arriscados no boundary sao:
|
||||
Os pontos abaixo ficam cravados nesta agenda como direcao atual da discussao:
|
||||
|
||||
1. `TMX` e `TSX` permanecem surfaces editoriais do Studio e nao entram no protocolo operacional do packer.
|
||||
2. O `Asset Workspace` deve extrair, no passo de `Accept`, um request proprio para o `prometeu-packer`.
|
||||
3. O payload runtime `SCENE` carrega `glyph_asset_id`, e a resolucao `asset_id -> slot` pertence ao runtime.
|
||||
4. `glyph_asset_id` eh derivado do tileset/glyph asset selecionado no form da layer.
|
||||
5. `parallax_factor` deve existir no form da layer.
|
||||
6. `palette_id` deve existir no form da layer, ou em surface editorial equivalente no mesmo nivel.
|
||||
7. O checkbox da layer define se ela esta ativa/sera usada.
|
||||
8. Cada tile eh resolvido via `TSX`; `glyph_id` ja existe como property no `TSX`.
|
||||
9. `flip` e `palette_id` por tile podem vir como properties no `TMX`.
|
||||
10. Wave 1 continua com exatamente `1 TSX` por `TMX`/layer.
|
||||
11. O gate atual para publicar continua sendo ausencia de diagnostic error bloqueante.
|
||||
12. O request `studio -> packer` deve ser derivado backwards do payload binario e `request -> SCENE` deve ser o mais direto possivel.
|
||||
13. O shape atual assentado do request e:
|
||||
2. `TMX` e `TSX` sao surfaces editoriais suportadas em wave 1, mas nao sao a surface canonica do contrato de publicacao e permanecem substituiveis por outros editores suportados no futuro.
|
||||
3. O `Asset Workspace` deve extrair, no passo de `Accept`, um request proprio para o `prometeu-packer`.
|
||||
4. O payload runtime `SCENE` carrega `glyph_asset_id`, e a resolucao `asset_id -> slot` pertence ao runtime.
|
||||
5. `glyph_asset_id` eh derivado do tileset/glyph asset selecionado no form da layer.
|
||||
6. `parallax_factor` deve existir no form da layer.
|
||||
7. `palette_id` deve existir no form da layer, ou em surface editorial equivalente no mesmo nivel.
|
||||
8. O checkbox da layer define se ela esta ativa/sera usada.
|
||||
9. Cada tile eh resolvido via `TSX`; `glyph_id` ja existe como property no `TSX`.
|
||||
10. `flip` e `palette_id` por tile podem vir como properties no `TMX`.
|
||||
11. Wave 1 continua com exatamente `1 TSX` por `TMX`/layer.
|
||||
12. O gate atual para publicar continua sendo ausencia de diagnostic error bloqueante.
|
||||
13. O request `studio -> packer` deve ser derivado backwards do payload binario e `request -> SCENE` deve ser o mais direto possivel.
|
||||
14. O shape atual assentado do request e:
|
||||
`ScenePackRequest(version, layers[4])`;
|
||||
`ScenePackLayerRequest(active, glyph_asset_id, tile_size, parallax_factor_x, parallax_factor_y, width, height, tiles)`;
|
||||
`ScenePackTileRequest(active, glyph_id, palette_id, flip_x, flip_y)`.
|
||||
14. O manifest permanece com `SCENE/tilemap_v1` por enquanto.
|
||||
15. O manifest permanece com `SCENE/tilemap_v1` por enquanto.
|
||||
|
||||
## Recommendation
|
||||
|
||||
@@ -199,17 +200,19 @@ Seguir com a `Option A`.
|
||||
Direcao recomendada:
|
||||
|
||||
1. manter `TMX`/`TSX` como surfaces editoriais wave 1 no dominio `studio`;
|
||||
2. fechar uma decision nova para o boundary `studio/packer/runtime` do `Scene Bank`;
|
||||
3. fazer o `Asset Workspace` aceitar e extrair do estado editorial um request proprio para o packer;
|
||||
4. fazer o `prometeu-packer` ser owner apenas da compilacao desse request para o payload binario `SCENE`;
|
||||
5. explicitar na decision:
|
||||
2. registrar explicitamente que `TMX`/`TSX` nao sao a surface canonica do contrato e podem coexistir no futuro com outros editores suportados, desde que materializem o mesmo request canonico;
|
||||
3. fechar uma decision nova para o boundary `studio/packer/runtime` do `Scene Bank`;
|
||||
4. fazer o `Asset Workspace` aceitar e extrair do estado editorial um request proprio para o packer;
|
||||
5. fazer o `prometeu-packer` ser owner apenas da compilacao desse request para o payload binario `SCENE`;
|
||||
6. explicitar na decision:
|
||||
modelagem da dependencia `glyph_asset_id`;
|
||||
modelagem de `parallax_factor`;
|
||||
modelagem de `palette_id`;
|
||||
semantica da layer ativa no request;
|
||||
gate baseado em diagnostics bloqueantes;
|
||||
formato do request `studio -> packer`, derivado backwards do payload binario;
|
||||
semantica oficial de `SCENE/tilemap_v1`.
|
||||
semantica oficial de `SCENE/tilemap_v1`;
|
||||
carater nao-canonico e substituivel das surfaces editoriais suportadas.
|
||||
|
||||
Essa direcao reaproveita o que ja existe, mantem o packer livre das ferramentas editoriais do Studio e concentra a publicacao runtime no subsistema que ja monta `assets.pa`.
|
||||
|
||||
@@ -231,12 +234,14 @@ Agenda aceita.
|
||||
Direcao consolidada:
|
||||
|
||||
1. `TMX`/`TSX` permanecem estritamente editoriais no dominio `studio`.
|
||||
2. O `Scene Bank` aceito deve extrair um request proprio e estavel para o `prometeu-packer`.
|
||||
3. O request `studio -> packer` deve ser derivado backwards do payload binario `SCENE` e `request -> SCENE` deve ser o mais direto possivel.
|
||||
4. O contrato runtime de dependencia de glyph por layer usa `glyph_asset_id`, com resolucao `asset_id -> slot` pertencendo ao runtime.
|
||||
5. O workflow editorial do Studio deve prover `glyph_asset_id` derivado do tileset selecionado, `parallax_factor`, `palette_id`, estado ativo da layer e a traducao por tile a partir de `TSX`/`TMX`.
|
||||
6. Wave 1 permanece com exatamente `1 TSX` por `TMX`/layer.
|
||||
7. O gate para publicacao continua sendo ausencia de diagnostic error bloqueante.
|
||||
8. O manifest permanece com `SCENE/tilemap_v1` por enquanto.
|
||||
2. `TMX`/`TSX` sao surfaces editoriais suportadas em wave 1, mas nao sao a definicao canonica do asset nem do contrato de publicacao.
|
||||
3. Outros editores suportados no futuro podem substituir ou coexistir com `TMX`/`TSX`, desde que materializem o mesmo request canonico `studio -> packer` e passem pelas mesmas regras de validacao e `Accept`.
|
||||
4. O `Scene Bank` aceito deve extrair um request proprio e estavel para o `prometeu-packer`.
|
||||
5. O request `studio -> packer` deve ser derivado backwards do payload binario `SCENE` e `request -> SCENE` deve ser o mais direto possivel.
|
||||
6. O contrato runtime de dependencia de glyph por layer usa `glyph_asset_id`, com resolucao `asset_id -> slot` pertencendo ao runtime.
|
||||
7. O workflow editorial do Studio deve prover `glyph_asset_id` derivado do tileset selecionado, `parallax_factor`, `palette_id`, estado ativo da layer e a traducao por tile a partir de `TSX`/`TMX`.
|
||||
8. Wave 1 permanece com exatamente `1 TSX` por `TMX`/layer.
|
||||
9. O gate para publicacao continua sendo ausencia de diagnostic error bloqueante.
|
||||
10. O manifest permanece com `SCENE/tilemap_v1` por enquanto.
|
||||
|
||||
Proximo passo sugerido: converter esta agenda em uma `decision` normativa para o boundary `studio -> packer -> runtime`.
|
||||
|
||||
+121
@@ -0,0 +1,121 @@
|
||||
---
|
||||
id: AGD-0033
|
||||
ticket: studio-scene-pack-runtime-binary-contract
|
||||
title: Revise Scene Bank editorial model to Studio-native scene with TMX import-export
|
||||
status: accepted
|
||||
created: 2026-04-30
|
||||
resolved: 2026-04-30
|
||||
decision: DEC-0030
|
||||
tags: [studio, packer, runtime, scene, asset-pack, tiled, revision]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
A direcao aceita em `DEC-0029` e implementada por `PLN-0059` a `PLN-0061` tomou um atalho editorial errado: modelamos `1 layer -> 1 TMX`, com validacao e `Accept` por layer, quando o editor suportado (`Tiled`) opera naturalmente com `1 scene -> 1 TMX` contendo multiplos layers.
|
||||
|
||||
Isso gerou uma friccao estrutural:
|
||||
|
||||
- o fluxo atual separa artificialmente layers que pertencem ao mesmo mapa;
|
||||
- o `Accept` por layer conflita com a necessidade de publicar uma scene coesa;
|
||||
- o modelo atual esconde um erro conceitual ao tratar `TMX` como surface por layer, em vez de surface por scene;
|
||||
- a integracao editorial ficou mais fraca justamente no editor que estamos suportando em wave 1.
|
||||
|
||||
Dominio owner desta agenda: `studio`.
|
||||
Boundary explicito: `studio -> packer -> runtime`.
|
||||
|
||||
## Context
|
||||
|
||||
- `DEC-0029` fechou corretamente que `TMX`/`TSX` sao surfaces editoriais suportadas, nao canonicas, e que o contrato normativo de publicacao continua sendo o request `studio -> packer -> SCENE`.
|
||||
- O erro nao esta nesse boundary canonico; o erro esta no shape editorial escolhido para a integracao com Tiled.
|
||||
- A implementacao atual assumiu:
|
||||
- `1 layer -> 1 TMX`;
|
||||
- `1 TMX -> 1 TSX`;
|
||||
- geracao, validacao e `Accept` com foco em layer.
|
||||
- O problema observado no `tiled2` reforca essa distorcao: o fluxo de workflow passou a tentar aceitar layer isoladamente, quando o valor editorial real esta na scene inteira.
|
||||
- O Tiled comporta um `TMX` com multiplos layers; cada layer pode ter seu proprio tileset referenciado no mapa, e o authoring natural da scene acontece nesse documento unico.
|
||||
- O runtime continua nao dependendo de `TMX`; ele continua dependendo apenas do request canonico aceito e do payload binario `SCENE`.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [x] O modelo wave 1 deve ser formalmente revisado para `1 scene -> 1 TMX` com multiplos layers?
|
||||
Resposta: parcialmente. Essa direcao corrige o erro imediato de `TMX por layer`, mas a escolha final nao eh promover `TMX unico` a surface principal. A direcao escolhida eh um modelo nativo de scene no Studio, com `TMX` tratado como formato suportado de import/export.
|
||||
- [x] Devemos abandonar completamente `validate layer` e `accept layer`, deixando apenas `generate scene`, `validate scene` e `accept scene`?
|
||||
Resposta: sim, e mais do que isso: no modelo escolhido esses verbos deixam de ser a surface principal do workflow editorial. O Studio passa a operar com `import` e `export` via wizard para formatos suportados, com `Tiled` como primeira opcao. A validacao ocorre sobre o formato canonico do asset de scene no `Analyse` ou no `Pack`, nao sobre o formato externo.
|
||||
- [x] Como cada layer da scene referencia seu tileset no editor suportado?
|
||||
Resposta: no caminho de compatibilidade com Tiled, o `TMX` pode carregar multiplos `TSX`, e a scene pode usar ate quatro tilesets distintos. Isso descreve a compatibilidade editorial do import/export, nao o modelo canonico interno do Studio.
|
||||
- [x] Como representar layers com tamanhos independentes dentro da scene?
|
||||
Resposta: o modelo da scene deve aceitar layers com tamanho proprio. No caminho Tiled, mapas infinitos continuam suportados como concern editorial. Camera boundaries ficam para iteracao posterior.
|
||||
- [x] O `scene-bank.studio.json` deve continuar carregando `width`/`height` por layer, ou passar a carregar apenas metadata editorial complementar e bindings?
|
||||
Resposta: o asset de scene deve manter uma entidade canonica propria, distinta do request de pack. `scene-bank.studio.json` pode continuar existindo como persistencia editorial dessa entidade, com metadata como `width` e `height` por layer quando fizer sentido, mas sem se confundir com o request `studio -> packer`.
|
||||
- [x] Como o request canonico deve ser projetado sem reintroduzir dependencia canonica em formato editorial?
|
||||
Resposta: o request `studio -> packer` continua existindo, mas como projeção derivada da entidade canonica do asset de scene, nao como a propria entidade editorial. `TMX` entra apenas como formato suportado de importacao/exportacao; `import` atualiza a entidade canonica a partir do `TMX`, e `export` sobrescreve o `TMX` a partir da entidade canonica.
|
||||
- [x] O `import` de `TMX` deve aceitar qualquer alteracao editorial feita externamente no Tiled?
|
||||
Resposta: nao. O `import` deve aplicar validacoes minimas de compatibilidade antes de alterar a entidade canonica. Mudancas como adicao de novos layers, adicao de novos tilesets, ou alteracao estrutural inesperada de layers/tilesets podem invalidar o `TMX` para importacao. Quando isso ocorrer, o Studio deve recusar o `import` e emitir logs/diagnostics claros de falha.
|
||||
- [x] Como o fluxo de `TSX` deve se comportar para glyph tilesets especializados?
|
||||
Resposta: o glyph tileset pode gerar `TSX`, e isso passa a ser tratado como `export` para formato suportado `TSX (Tiled)`. O `export` sobrescreve o arquivo existente ou cria um novo, seguindo a mesma filosofia do `TMX`.
|
||||
- [x] Quais partes de `DEC-0029` permanecem validas e quais precisam ser substituidas explicitamente?
|
||||
Resposta: permanece valida a parte que fixa `TMX`/`TSX` como surfaces editoriais nao canonicas e o request `studio -> packer` como contrato normativo. Deve ser substituida explicitamente a parte editorial implementada como `TMX por layer` e o workflow `generate / validate / accept` por layer.
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Keep per-layer TMX and patch workflow
|
||||
- **Approach:** Manter `1 layer -> 1 TMX`, corrigir o bug de workflow de `Accept`, e ajustar a UX ao redor disso.
|
||||
- **Pro:** Menor custo imediato sobre a implementacao existente.
|
||||
- **Con:** Preserva o erro de modelagem editorial e continua desalinhado com o uso natural do Tiled.
|
||||
- **Maintainability:** Fraca. Corrige sintomas sem corrigir o modelo.
|
||||
|
||||
### Option B - Revise to single TMX per scene and scene-level workflow
|
||||
- **Approach:** Revisar a decision para `1 scene -> 1 TMX`, com multiplos layers editoriais no mesmo mapa, e mover `generate / validate / accept` para o nivel da scene.
|
||||
- **Pro:** Alinha o Studio ao modelo real do Tiled e fecha um boundary editorial mais coerente.
|
||||
- **Con:** Exige revisao normativa, refatoracao de specs e reimplementacao parcial do fluxo entregue em `PLN-0060` e `PLN-0061`.
|
||||
- **Maintainability:** Forte. Remove a distorcao estrutural e preserva o contrato canonico correto.
|
||||
|
||||
### Option C - Introduce a Studio-native scene model now and demote TMX to import/export
|
||||
- **Approach:** Parar de tratar `TMX` como surface principal e assumir imediatamente um modelo proprio do Studio, usando Tiled apenas como compatibilidade.
|
||||
- **Pro:** Resolve de vez o acoplamento editorial ao Tiled.
|
||||
- **Con:** Exige refatoracao mais profunda agora, incluindo suporte nativo de scene, import/export, migracao editorial e revisao dos plans ja executados.
|
||||
- **Maintainability:** Melhor opcao de longo prazo. Remove o erro estrutural na raiz e abre espaco para multiplos editores suportados.
|
||||
|
||||
Escolha fechada na agenda: `Option C`.
|
||||
|
||||
## Discussion
|
||||
|
||||
A correção necessária parece ser de direcao, nao apenas de bug.
|
||||
|
||||
O problema central nao eh que o request canonico exista ou que o packer compile `SCENE`; isso continua correto. O problema eh que o lado editorial foi fatiado na unidade errada. Ao quebrar scene em `TMX` por layer, o Studio passou a operar contra a gravidade do editor suportado e abriu espaco para workflow incoerente.
|
||||
|
||||
A agenda convergiu para um passo adicional: mesmo o modelo `TMX unico por scene` ainda seria uma otimizacao em torno do Tiled, nao uma surface editorial suficiente para o Studio no medio prazo. A escolha da `Option C` fecha uma direcao mais limpa:
|
||||
|
||||
- preservar o boundary canonico `studio -> packer -> runtime`;
|
||||
- introduzir um modelo nativo de scene no Studio como surface principal;
|
||||
- tratar `TMX`/`TSX` como formatos suportados de importacao/exportacao e compatibilidade;
|
||||
- substituir `generate / validate / accept` por um workflow de `import / export` guiado por wizard para formatos suportados;
|
||||
- aplicar validacoes minimas de compatibilidade no `import`, com recusa e logs claros quando o artefato externo divergir estruturalmente do que o Studio suporta;
|
||||
- validar a entidade canonica da scene no `Analyse` ou no `Pack`;
|
||||
- manter o request canonico de pack como projeção derivada da entidade canonica da scene, e nao como espelho bruto de qualquer formato externo.
|
||||
|
||||
Isso substitui explicitamente a parte editorial errada de `DEC-0029`, sem reabrir a parte do contrato canonico de publicacao que continuou correta.
|
||||
|
||||
## Resolution
|
||||
|
||||
Recomendacao final da agenda:
|
||||
|
||||
- revisar `DEC-0029` para abandonar o modelo `TMX por layer`;
|
||||
- nao promover `TMX unico por scene` a surface principal do produto;
|
||||
- adotar um modelo nativo de scene no Studio como owner editorial principal;
|
||||
- tratar `TMX`/`TSX` como formatos suportados de import/export e compatibilidade;
|
||||
- substituir o workflow de `generate / validate / accept` por `import / export` com wizard;
|
||||
- exigir validacoes minimas no `import` de `TMX`, com falha explicita quando houver divergencia estrutural nao suportada, como novos layers, novos tilesets, ou alteracoes estruturais equivalentes;
|
||||
- tratar a geracao de `TSX` por glyph tileset como `export` para formato suportado `TSX (Tiled)`, com sobrescrita ou criacao do arquivo de destino;
|
||||
- validar a entidade canonica do asset de scene no `Analyse` ou no `Pack`;
|
||||
- preservar a separacao entre:
|
||||
- entidade canonica do asset de scene no Studio;
|
||||
- request `studio -> packer`;
|
||||
- payload binario `SCENE` de runtime;
|
||||
- preservar como normativa a parte de `DEC-0029` que fixa `TMX`/`TSX` como surfaces editoriais nao canonicas e o request `studio -> packer` como contrato de publicacao.
|
||||
|
||||
Proximo passo sugerido:
|
||||
|
||||
- emitir uma nova decision de revisao, substituindo explicitamente a porcao editorial de `DEC-0029`;
|
||||
- derivar novos plans para `specs`, `studio` e `packer`, com migracao do fluxo atual;
|
||||
- tratar a implementacao entregue em `PLN-0060` e `PLN-0061` como baseline a ser revisada, nao como forma final do modelo editorial.
|
||||
@@ -0,0 +1,123 @@
|
||||
---
|
||||
id: DEC-0029
|
||||
ticket: studio-scene-pack-runtime-binary-contract
|
||||
title: Studio scene pack contract for runtime SCENE binary payload
|
||||
status: accepted
|
||||
created: 2026-04-29
|
||||
accepted: 2026-04-29
|
||||
agenda: AGD-0032
|
||||
plans:
|
||||
- PLN-0059
|
||||
- PLN-0060
|
||||
- PLN-0061
|
||||
tags:
|
||||
- studio
|
||||
- packer
|
||||
- runtime
|
||||
- scene
|
||||
- asset-pack
|
||||
- binary-format
|
||||
- tiled
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
The canonical publication contract for `Scene Bank` assets SHALL be the `studio -> packer` scene-pack request and its direct compilation into runtime `SCENE` payload bytes.
|
||||
|
||||
`TMX` and `TSX` SHALL remain supported editorial surfaces for wave 1 inside the `studio` domain, but they MUST NOT define the normative publication contract, the runtime asset shape, or the packer boundary.
|
||||
|
||||
The system MAY support additional scene editors in the future. Any supported editor MUST materialize the same canonical scene-pack request and MUST pass the same validation and `Accept` gating rules before publication.
|
||||
|
||||
`prometeu-packer` SHALL compile only the canonical scene-pack request into the runtime `SCENE` payload. It MUST NOT parse `TMX`, `TSX`, or any other editor-specific surface directly.
|
||||
|
||||
The runtime `SCENE` dependency contract SHALL use `glyph_asset_id` per layer. Resolution from `glyph_asset_id` to runtime glyph slot SHALL remain a runtime concern and MUST NOT be serialized by Studio or packer as a pre-resolved slot.
|
||||
|
||||
## Rationale
|
||||
|
||||
This decision preserves the already accepted wave-1 editorial direction from `DSC-0028` while preventing Tiled from becoming the canonical asset model by accident.
|
||||
|
||||
The binary `SCENE` runtime payload already exists and is the true sink of the pipeline. The missing architectural piece is therefore not a new scene schema, but a stable domain boundary that lets Studio accept editorial state and lets packer compile a runtime-owned request without absorbing external-tool concerns.
|
||||
|
||||
Treating `TMX` and `TSX` as supported but non-canonical keeps the current workflow viable, while leaving the door open for future integrated editors or multiple editors without reopening the packer or runtime contract.
|
||||
|
||||
## Technical Specification
|
||||
|
||||
### 1. Domain Ownership
|
||||
|
||||
- `studio` SHALL own editorial scene authoring, validation, diagnostics, and `Accept`.
|
||||
- `packer` SHALL own compilation of the canonical request into binary `SCENE`.
|
||||
- `runtime` SHALL own decoding, binding, and operational slot resolution for glyph dependencies.
|
||||
|
||||
### 2. Supported Editorial Surfaces
|
||||
|
||||
- Wave 1 SHALL support `TMX` and `TSX` as editorial surfaces in `studio`.
|
||||
- These surfaces MUST be treated as replaceable editor integrations, not as canonical publication artifacts.
|
||||
- Future editors MAY replace or coexist with Tiled-backed surfaces if they emit the same canonical request and satisfy the same validation semantics.
|
||||
|
||||
### 3. Canonical `studio -> packer` Request
|
||||
|
||||
The canonical request SHALL be defined as:
|
||||
|
||||
```text
|
||||
ScenePackRequest
|
||||
- version: int
|
||||
- layers: [ScenePackLayerRequest; 4]
|
||||
|
||||
ScenePackLayerRequest
|
||||
- active: bool
|
||||
- glyph_asset_id: int
|
||||
- tile_size: int
|
||||
- parallax_factor_x: float
|
||||
- parallax_factor_y: float
|
||||
- width: int
|
||||
- height: int
|
||||
- tiles: List<ScenePackTileRequest>
|
||||
|
||||
ScenePackTileRequest
|
||||
- active: bool
|
||||
- glyph_id: int
|
||||
- palette_id: int
|
||||
- flip_x: bool
|
||||
- flip_y: bool
|
||||
```
|
||||
|
||||
Normative rules:
|
||||
|
||||
- `request -> SCENE` SHALL be as direct as possible.
|
||||
- `tile_count` SHALL be derived from `width * height`.
|
||||
- Binary reserved fields MUST NOT be mirrored into the request unless they gain explicit editorial meaning.
|
||||
- `layers` SHALL always materialize exactly `4` entries in wave 1.
|
||||
|
||||
### 4. Layer and Tile Semantics
|
||||
|
||||
- `glyph_asset_id` SHALL be derived from the glyph asset/tileset selected for the layer in Studio.
|
||||
- `parallax_factor_x` and `parallax_factor_y` SHALL be modeled as layer-owned editorial fields in Studio.
|
||||
- `palette_id` SHALL be modeled with a layer-level editorial default in Studio, with optional per-tile override when supported by the editorial surface.
|
||||
- `active` at layer scope SHALL indicate whether the layer participates in publication output.
|
||||
- `active` at tile scope SHALL indicate whether the tile contributes an active tile record to the published scene payload.
|
||||
- Wave 1 SHALL remain limited to exactly `1 TSX` per `TMX` per layer.
|
||||
|
||||
### 5. Validation and Acceptance
|
||||
|
||||
- Publication MUST be gated by absence of blocking diagnostic errors.
|
||||
- The `Accept` step in Studio SHALL be the moment where supported editorial state is validated and projected into the canonical request.
|
||||
- Studio MUST NOT silently auto-accept external editor mutations.
|
||||
|
||||
### 6. Manifest and Runtime Projection
|
||||
|
||||
- The manifest output format SHALL remain `SCENE/tilemap_v1` for this wave.
|
||||
- The runtime payload SHALL carry `glyph_asset_id` per layer.
|
||||
- Runtime slot allocation and `asset_id -> slot` resolution MUST remain runtime-internal behavior.
|
||||
|
||||
## Constraints
|
||||
|
||||
- This decision MUST NOT be interpreted as introducing a dedicated scene workspace.
|
||||
- This decision MUST NOT be interpreted as allowing packer to parse editor-specific formats directly.
|
||||
- This decision MUST NOT be interpreted as making Tiled temporary or deprecated; it is supported, but non-canonical.
|
||||
- This decision does not reopen wave-1 limits around single-tileset-per-layer authoring.
|
||||
- Any future change to the canonical request or runtime projection SHALL require explicit decision review.
|
||||
|
||||
## Revision Log
|
||||
|
||||
- 2026-04-29: Initial draft from AGD-0032.
|
||||
- 2026-04-29: Accepted and decomposed into implementation plans PLN-0059, PLN-0060, and PLN-0061.
|
||||
+147
@@ -0,0 +1,147 @@
|
||||
---
|
||||
id: DEC-0030
|
||||
ticket: studio-scene-pack-runtime-binary-contract
|
||||
title: Studio-native scene canonical model with Tiled import-export compatibility
|
||||
status: accepted
|
||||
created: 2026-04-30
|
||||
accepted: 2026-04-30
|
||||
agenda: AGD-0033
|
||||
plans:
|
||||
- PLN-0062
|
||||
- PLN-0063
|
||||
- PLN-0064
|
||||
tags:
|
||||
- studio
|
||||
- packer
|
||||
- runtime
|
||||
- scene
|
||||
- asset-pack
|
||||
- tiled
|
||||
- import-export
|
||||
- revision
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
`Scene Bank` authoring in `studio` SHALL move to a Studio-native canonical scene model.
|
||||
|
||||
`TMX` and `TSX` SHALL remain supported formats, but only as import/export and compatibility surfaces. They MUST NOT be treated as the primary editorial model, the validation target, or the canonical publication state.
|
||||
|
||||
The Studio workflow for scenes SHALL NOT use `generate`, `validate`, or `accept` over `TMX`, per-layer `TMX`, or any equivalent editor-owned surface. Instead, Studio SHALL own:
|
||||
|
||||
- a canonical scene entity for the asset itself;
|
||||
- `import` from supported external formats into that canonical scene entity;
|
||||
- `export` from that canonical scene entity into supported external formats.
|
||||
|
||||
For wave 1 of this revision:
|
||||
|
||||
- `Tiled` SHALL be the first supported import/export option;
|
||||
- `TMX` scene import SHALL update the canonical scene entity from the external file;
|
||||
- `TMX` scene export SHALL overwrite the target `TMX` or create it if missing;
|
||||
- glyph-bank `TSX` generation SHALL be treated as `TSX (Tiled)` export and SHALL overwrite the target `TSX` or create it if missing.
|
||||
|
||||
Validation SHALL occur over the canonical Studio scene entity during `Analyse` and/or `Pack`. The canonical Studio scene entity SHALL remain distinct from the `studio -> packer` scene-pack request, and that request SHALL remain distinct from the runtime `SCENE` binary payload.
|
||||
|
||||
This decision SHALL supersede the editorial-model portion of `DEC-0029`. It SHALL preserve the parts of `DEC-0029` that define:
|
||||
|
||||
- the canonical `studio -> packer` boundary as normative for publication;
|
||||
- `TMX`/`TSX` as non-canonical supported surfaces;
|
||||
- `prometeu-packer` as compiler of the canonical request only;
|
||||
- runtime ownership of `glyph_asset_id -> slot` resolution and of the final `SCENE` payload contract.
|
||||
|
||||
## Rationale
|
||||
|
||||
The previous direction corrected the publication boundary but still modeled the editorial surface around the wrong unit. Treating layers as separate `TMX` files forced the Studio workflow to move against the natural structure of supported external editors and produced a brittle acceptance model.
|
||||
|
||||
Even revising that approach to a single `TMX` per scene would still make the external format too central. The selected direction avoids that trap by making the Studio's own scene entity the owner of editorial truth, while keeping Tiled available as an interoperability surface.
|
||||
|
||||
This preserves long-term flexibility:
|
||||
|
||||
- multiple external scene editors MAY be supported later;
|
||||
- the packer boundary remains editor-agnostic;
|
||||
- the runtime contract remains untouched;
|
||||
- editorial tooling can evolve independently of external file formats.
|
||||
|
||||
## Technical Specification
|
||||
|
||||
### 1. Canonical Scene Ownership
|
||||
|
||||
- `studio` SHALL persist and operate on a canonical scene entity owned by the Studio domain.
|
||||
- That canonical scene entity MUST be the source of truth for scene editorial state.
|
||||
- The canonical scene entity MUST NOT be conflated with a `TMX`, `TSX`, or any other editor-specific file.
|
||||
- The canonical scene entity MUST NOT be conflated with the `studio -> packer` request.
|
||||
|
||||
### 2. External Format Support
|
||||
|
||||
- `TMX` and `TSX` SHALL be treated as supported interoperability formats.
|
||||
- Studio SHALL expose import/export operations for supported formats through wizard-driven workflow.
|
||||
- `Tiled` SHALL be the initial supported option for both scene and glyph-bank interoperability.
|
||||
- Import/export MAY later support additional formats without changing the canonical publication boundary.
|
||||
|
||||
### 3. Import Semantics
|
||||
|
||||
- `import` MUST read a supported external file and project its compatible content into the canonical Studio entity.
|
||||
- `import` MUST perform minimum structural compatibility validation before mutating canonical state.
|
||||
- `import` MUST fail explicitly, with logs or diagnostics, when the external file diverges in unsupported structural ways.
|
||||
|
||||
Examples of structural divergence that MUST be treated as import failures unless explicitly supported by a later decision:
|
||||
|
||||
- unexpected new layers;
|
||||
- unexpected new tilesets;
|
||||
- unexpected structural modification of existing layers or tilesets;
|
||||
- equivalent external mutations that the Studio compatibility contract does not accept.
|
||||
|
||||
- Failed import MUST NOT silently partially rewrite canonical scene state.
|
||||
|
||||
### 4. Export Semantics
|
||||
|
||||
- `export` MUST serialize the canonical Studio entity into the selected supported format.
|
||||
- `TMX` export MUST overwrite the destination file if present, or create it if absent.
|
||||
- `TSX` export for glyph tilesets MUST overwrite the destination file if present, or create it if absent.
|
||||
- Exported files are compatibility artifacts. They MUST NOT become the canonical source of truth by virtue of existing on disk.
|
||||
|
||||
### 5. Validation Surface
|
||||
|
||||
- Validation of scene correctness SHALL target the canonical Studio scene entity.
|
||||
- `Analyse` and `Pack` SHALL be the normative validation surfaces for canonical scene integrity.
|
||||
- External files MAY be validated for import compatibility during import, but that validation does not replace canonical scene validation.
|
||||
- The old `validate layer`, `accept layer`, `validate scene from TMX`, and `accept scene from TMX` workflow MUST be removed or replaced so it no longer defines the editorial lifecycle.
|
||||
|
||||
### 6. Separation of Contracts
|
||||
|
||||
The system SHALL preserve three distinct layers of representation:
|
||||
|
||||
1. the canonical Studio-owned scene entity;
|
||||
2. the canonical `studio -> packer` scene-pack request derived from that entity;
|
||||
3. the runtime `SCENE` binary payload derived by `prometeu-packer`.
|
||||
|
||||
Normative implications:
|
||||
|
||||
- the canonical scene entity MAY evolve editorially without forcing the same shape onto the pack request;
|
||||
- the pack request MUST remain a publication projection, not the editorial persistence model;
|
||||
- packer MUST continue compiling only the canonical request, never `TMX`, `TSX`, or any other editor-native file directly.
|
||||
|
||||
### 7. Preserved Rules from DEC-0029
|
||||
|
||||
This decision intentionally preserves the following normative rules from `DEC-0029`:
|
||||
|
||||
- `TMX`/`TSX` remain supported but non-canonical;
|
||||
- the publication contract remains the canonical `studio -> packer` request;
|
||||
- `prometeu-packer` MUST NOT parse editor-specific formats directly;
|
||||
- runtime `SCENE` continues to depend on `glyph_asset_id` per layer;
|
||||
- runtime slot resolution remains runtime-owned;
|
||||
- any future change to the request shape or runtime payload contract still requires explicit decision review.
|
||||
|
||||
## Constraints
|
||||
|
||||
- This decision MUST NOT be interpreted as making Tiled deprecated or unsupported.
|
||||
- This decision MUST NOT be interpreted as collapsing the canonical Studio scene entity into the pack request.
|
||||
- This decision MUST NOT be interpreted as allowing import to accept arbitrary external edits without compatibility checks.
|
||||
- This decision MUST NOT be interpreted as preserving the old `TMX per layer` model.
|
||||
- This decision does not yet define the full canonical scene schema; that schema SHALL be specified by downstream plans and spec propagation derived from this decision.
|
||||
|
||||
## Revision Log
|
||||
|
||||
- 2026-04-30: Initial draft from AGD-0033.
|
||||
- 2026-04-30: Explicitly supersedes the editorial-model portion of DEC-0029 while preserving its canonical publication boundary.
|
||||
- 2026-04-30: Accepted and decomposed into implementation plans PLN-0062, PLN-0063, and PLN-0064.
|
||||
@@ -0,0 +1,116 @@
|
||||
---
|
||||
id: PLN-0059
|
||||
ticket: studio-scene-pack-runtime-binary-contract
|
||||
title: Propagate DEC-0029 into Studio and packer normative specifications
|
||||
status: done
|
||||
created: 2026-04-29
|
||||
completed: 2026-04-29
|
||||
tags:
|
||||
- studio
|
||||
- packer
|
||||
- specs
|
||||
- scene
|
||||
- runtime-contract
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Update the normative documentation surfaces so DEC-0029 is fully reflected in Studio and packer specs before or alongside code implementation.
|
||||
|
||||
## Background
|
||||
|
||||
DEC-0029 locks the canonical publication contract for `Scene Bank` assets around a `studio -> packer` request that compiles directly into runtime `SCENE` bytes. It also locks `TMX`/`TSX` as supported but non-canonical editorial surfaces.
|
||||
|
||||
The current codebase already contains wave-1 Tiled support and Scene Bank validation flows, but the normative specs do not yet describe:
|
||||
|
||||
- the canonical scene-pack request,
|
||||
- the non-canonical status of `TMX`/`TSX`,
|
||||
- the `Accept` projection boundary,
|
||||
- or packer ownership of binary `SCENE` compilation from a request rather than from editor files.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Update Studio specs to describe Scene Bank editorial ownership, validation, `Accept`, and canonical request projection.
|
||||
- Update packer specs to describe request-owned publication, `SCENE/tilemap_v1`, and the prohibition on direct parsing of editor-specific formats by packer.
|
||||
- Cross-link Studio and packer specs to DEC-0029 and to the existing Scene Bank asset-first wave.
|
||||
|
||||
### Excluded
|
||||
- Java implementation changes in `prometeu-studio`.
|
||||
- Java implementation changes in `prometeu-packer`.
|
||||
- Lesson or housekeeping work for DSC-0030.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Update Studio asset workspace specification
|
||||
|
||||
**What:** Add normative Scene Bank language to the Studio `Assets` workspace spec.
|
||||
|
||||
**How:** Extend the asset-family-specific rules in the Studio spec so Scene Bank authoring is explicitly asset-owned, `TMX`/`TSX` are editorial integrations rather than canonical publication artifacts, and `Accept` is defined as the projection point into the canonical pack request.
|
||||
|
||||
**File(s):**
|
||||
- `docs/specs/studio/4. Assets Workspace Specification.md`
|
||||
|
||||
### Step 2 - Update packer declaration and build-boundary specifications
|
||||
|
||||
**What:** Describe the canonical request and packer-owned build behavior in packer specs.
|
||||
|
||||
**How:** Amend the common asset contract spec and the operational/build specs so `SCENE/tilemap_v1` is documented as a runtime-oriented format whose packer input is the canonical scene-pack request produced by Studio, not raw editor files. Make explicit that editor-specific files remain tooling/editorial surfaces and MUST NOT be parsed directly by packer.
|
||||
|
||||
**File(s):**
|
||||
- `docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md`
|
||||
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`
|
||||
- `docs/specs/packer/5. Diagnostics, Operations, and Studio Integration Specification.md`
|
||||
|
||||
### Step 3 - Record canonical field semantics
|
||||
|
||||
**What:** Add the canonical scene-pack request fields and rules.
|
||||
|
||||
**How:** Document the fixed four-layer request shape, layer-level `glyph_asset_id`, `tile_size`, `parallax_factor`, `width`, `height`, tile-level `active`, `glyph_id`, `palette_id`, `flip_x`, `flip_y`, and the rule that `tile_count` is derived from dimensions. Lock the default-plus-override semantics for `palette_id`.
|
||||
|
||||
**File(s):**
|
||||
- `docs/specs/studio/4. Assets Workspace Specification.md`
|
||||
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`
|
||||
|
||||
### Step 4 - Align gating and future-editor rules
|
||||
|
||||
**What:** Ensure the specs preserve future editor substitution without weakening the current wave.
|
||||
|
||||
**How:** Add explicit normative text that any future editor may replace or coexist with Tiled-backed editing only if it emits the same canonical request and passes the same validation and `Accept` rules. Preserve the wave-1 single-tileset-per-layer restriction.
|
||||
|
||||
**File(s):**
|
||||
- `docs/specs/studio/4. Assets Workspace Specification.md`
|
||||
- `docs/specs/packer/5. Diagnostics, Operations, and Studio Integration Specification.md`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- No code unit tests are required for this editorial plan.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- No automated integration tests are required for this editorial plan.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Review the updated specs side by side with DEC-0029 and confirm that every normative rule in the decision has a corresponding spec statement.
|
||||
- Confirm there is no spec language implying that packer parses `TMX` or `TSX` directly.
|
||||
- Confirm the specs do not describe Tiled as deprecated or temporary.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] The Studio spec defines Scene Bank `Accept` as the projection boundary into the canonical scene-pack request.
|
||||
- [ ] The packer specs define `SCENE/tilemap_v1` publication in terms of the canonical request, not editor files.
|
||||
- [ ] The specs state that `TMX`/`TSX` are supported but non-canonical editorial surfaces.
|
||||
- [ ] The specs allow future additional editors only through the same canonical request and validation path.
|
||||
- [ ] Every normative requirement in DEC-0029 is represented in at least one spec file.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- DEC-0029 accepted.
|
||||
|
||||
## Risks
|
||||
|
||||
- Editorial drift between Studio and packer specs could reintroduce ambiguity about who owns the canonical request.
|
||||
- If the specs omit the field semantics for `palette_id` precedence or tile/layer `active`, code plans may diverge during implementation.
|
||||
+137
@@ -0,0 +1,137 @@
|
||||
---
|
||||
id: PLN-0060
|
||||
ticket: studio-scene-pack-runtime-binary-contract
|
||||
title: Build Scene Bank canonical request projection and acceptance in Studio
|
||||
status: done
|
||||
created: 2026-04-29
|
||||
completed: 2026-04-29
|
||||
tags:
|
||||
- studio
|
||||
- scene
|
||||
- assets
|
||||
- tiled
|
||||
- acceptance
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Implement the Studio-owned projection from supported editorial scene state into the canonical scene-pack request, with validation and `Accept` gating aligned to DEC-0029.
|
||||
|
||||
## Background
|
||||
|
||||
Studio already owns Scene Bank support metadata, Tiled generation, diagnostics, validation, and explicit acceptance. Today, however, the acceptance flow persists only validation fingerprints and does not yet materialize the canonical `studio -> packer` request required by DEC-0029.
|
||||
|
||||
This plan turns `Accept` from a pure approval marker into the normative projection boundary for Scene Bank publication.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Extend Scene Bank support metadata and UI/editorial state to carry the fields required by the canonical request.
|
||||
- Generate and persist the canonical request during Scene Bank `Accept`.
|
||||
- Validate the editorial-to-request mapping, including layer defaults and tile overrides.
|
||||
- Keep Tiled integration as a supported editorial path without making it canonical.
|
||||
|
||||
### Excluded
|
||||
- Binary `SCENE` encoding in packer.
|
||||
- Runtime decoder or runtime scene-binding changes.
|
||||
- A new integrated scene editor.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Expand Scene Bank editorial metadata
|
||||
|
||||
**What:** Add the missing layer-owned editorial fields required by the canonical request.
|
||||
|
||||
**How:** Extend the Scene Bank metadata model and serialization so each layer can carry at minimum `parallax_factor_x`, `parallax_factor_y`, and a layer-level default `palette_id`, while preserving the existing enabled-state, dimensions, `tilemap`, and `tileset_asset_root` binding rules.
|
||||
|
||||
**File(s):**
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/metadata/AssetStudioSceneBankMetadata.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/metadata/AssetStudioSceneLayerBinding.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/metadata/AssetStudioMetadataService.java`
|
||||
- `prometeu-studio/src/test/java/p/studio/workspaces/assets/metadata/AssetStudioMetadataServiceTest.java`
|
||||
|
||||
### Step 2 - Surface the new fields in the Scene Bank details UI
|
||||
|
||||
**What:** Make the canonical request inputs editable and reviewable in Studio.
|
||||
|
||||
**How:** Update the Scene Bank layer controls so the layer form exposes parallax values, default palette selection, and clearly ties `glyph_asset_id` derivation to the selected tileset asset. Preserve the existing enabled checkbox as the layer-level publication toggle.
|
||||
|
||||
**File(s):**
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/scene/AssetDetailsSceneLayersControl.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsControl.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/utilities/i18n/I18n.java`
|
||||
- `prometeu-studio/src/main/resources/i18n/messages.properties`
|
||||
|
||||
### Step 3 - Build canonical request projection from accepted editorial state
|
||||
|
||||
**What:** Materialize the canonical scene-pack request during `Accept`.
|
||||
|
||||
**How:** Introduce Studio-side request DTOs or records for `ScenePackRequest`, `ScenePackLayerRequest`, and `ScenePackTileRequest`. Update `SceneBankWorkflowService` so `Accept` validates the supported editorial inputs, parses `TMX`/`TSX`, derives `glyph_asset_id`, applies layer-default plus per-tile `palette_id` overrides, resolves per-tile `glyph_id`, `flip_x`, `flip_y`, and persists the resulting canonical request as the accepted publication input for packer consumption.
|
||||
|
||||
**File(s):**
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/scene/SceneBankWorkflowService.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/scene/SceneBankWorkflowResult.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/tiled/TiledXmlCodec.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/tiled/TiledMapDocument.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/tiled/TiledTilesetDocument.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/tiled/TiledTilesetTile.java`
|
||||
|
||||
### Step 4 - Tighten validation around canonical semantics
|
||||
|
||||
**What:** Ensure Studio rejects editorial states that cannot be projected safely into the canonical request.
|
||||
|
||||
**How:** Extend validation so it blocks acceptance when a layer lacks a resolvable tileset asset, when per-tile data cannot be mapped to a valid `glyph_id` or `palette_id`, when unsupported Tiled features would break canonical projection, or when wave-1 constraints such as single-tileset-per-layer are violated.
|
||||
|
||||
**File(s):**
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/scene/SceneBankWorkflowService.java`
|
||||
- `prometeu-studio/src/test/java/p/studio/workspaces/assets/scene/SceneBankWorkflowServiceTest.java`
|
||||
- `prometeu-studio/src/test/java/p/studio/workspaces/assets/tiled/TiledXmlCodecTest.java`
|
||||
- `prometeu-studio/src/test/java/p/studio/workspaces/assets/tiled/TiledAssetGenerationServiceTest.java`
|
||||
|
||||
### Step 5 - Expose acceptance artifacts to downstream consumers
|
||||
|
||||
**What:** Make the accepted canonical request visible to the rest of the Studio-to-packer flow.
|
||||
|
||||
**How:** Persist the accepted request in a deterministic asset-local file or equivalent accepted artifact and update the details refresh flow so the accepted/publication-ready state reflects both validation success and presence of the canonical request artifact.
|
||||
|
||||
**File(s):**
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/scene/SceneBankWorkflowService.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceAssetDetails.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsViewStateFactory.java`
|
||||
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceSceneBankValidation.java`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Add metadata serialization/deserialization coverage for the new layer fields.
|
||||
- Add request-projection tests for `glyph_asset_id` derivation, default `palette_id`, per-tile `palette_id` override, and tile flip mapping.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- Add Scene Bank workflow tests covering validate-then-accept for a valid layer set and failure cases for unsupported or incomplete editorial state.
|
||||
- Add acceptance-artifact tests proving external file mutation invalidates the accepted state until revalidation and reacceptance.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Create or update a Scene Bank asset in the test project, validate it, accept it, and confirm the accepted artifact contains the full canonical request.
|
||||
- Change a `TMX` or `TSX` file after acceptance and confirm Studio returns the asset to a non-ready state.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Scene Bank metadata and UI expose the layer-owned fields required by DEC-0029.
|
||||
- [ ] `Accept` emits a deterministic canonical scene-pack request artifact from the supported editorial state.
|
||||
- [ ] Validation blocks any Scene Bank that cannot be projected into the canonical request without guessing.
|
||||
- [ ] Layer default and per-tile override semantics for `palette_id` are implemented and tested.
|
||||
- [ ] Studio continues to support Tiled-backed editing without making `TMX`/`TSX` the canonical publication surface.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- DEC-0029 accepted.
|
||||
- PLN-0059 should land first or in parallel so the code aligns to updated specs.
|
||||
|
||||
## Risks
|
||||
|
||||
- The current Tiled parsing model may not yet expose every per-tile property needed for deterministic request projection.
|
||||
- If the accepted artifact shape is underspecified, packer integration may later depend on unstable serialization details.
|
||||
- UI additions for layer metadata can introduce partial-state bugs if draft/application flow is not kept consistent.
|
||||
+130
@@ -0,0 +1,130 @@
|
||||
---
|
||||
id: PLN-0061
|
||||
ticket: studio-scene-pack-runtime-binary-contract
|
||||
title: Compile the canonical Scene Bank request into runtime SCENE in packer
|
||||
status: done
|
||||
created: 2026-04-29
|
||||
completed: 2026-04-29
|
||||
tags:
|
||||
- packer
|
||||
- scene
|
||||
- runtime
|
||||
- binary-format
|
||||
- build
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Implement the packer-owned path that reads the accepted canonical scene-pack request and emits runtime `SCENE` binary payloads for `Scene Bank` assets.
|
||||
|
||||
## Background
|
||||
|
||||
`prometeu-packer` already recognizes `SCENE_BANK` and the `SCENE/tilemap_v1` output format, but `SCENE_BANK` currently stops short of real materialization. DEC-0029 locks the rule that packer must compile a canonical request and must not parse `TMX` or `TSX` directly.
|
||||
|
||||
This plan delivers the missing operational half of the boundary.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Introduce packer-side models for the canonical Scene Bank request.
|
||||
- Validate the accepted request artifact as a packer input.
|
||||
- Encode runtime `SCENE` binary payloads from the canonical request.
|
||||
- Integrate Scene Bank packing into the existing runtime materialization/build flow.
|
||||
|
||||
### Excluded
|
||||
- Studio UI and metadata authoring changes.
|
||||
- Runtime decoder changes beyond what is already assumed by DEC-0029.
|
||||
- Multi-tileset-per-layer or non-wave-1 scene authoring features.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Add canonical request models to the packer API
|
||||
|
||||
**What:** Define stable packer-side Java models for the canonical Scene Bank request.
|
||||
|
||||
**How:** Add DTOs/records for `ScenePackRequest`, `ScenePackLayerRequest`, and `ScenePackTileRequest` in `prometeu-packer-api`, including validation helpers for fixed layer count, required dimensions, and field presence. These models must be editor-agnostic and must not mention `TMX` or `TSX`.
|
||||
|
||||
**File(s):**
|
||||
- `prometeu-packer/prometeu-packer-api/src/main/java/p/packer/messages/assets/`
|
||||
- `prometeu-packer/prometeu-packer-api/build.gradle.kts` if package exports or module wiring need updates
|
||||
|
||||
### Step 2 - Teach packer to read and validate the accepted request artifact
|
||||
|
||||
**What:** Load Scene Bank publication input from the accepted request artifact rather than from editor files.
|
||||
|
||||
**How:** Extend the Scene Bank walking/materialization path so packer looks for the accepted canonical request artifact in the asset root, validates the fixed four-layer structure, checks `width * height` against tile counts, rejects missing or malformed request content, and emits structural diagnostics when the request is absent or invalid.
|
||||
|
||||
**File(s):**
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerAssetWalker.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerRuntimeAssetMaterializer.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
||||
|
||||
### Step 3 - Encode runtime `SCENE` payload bytes
|
||||
|
||||
**What:** Turn the canonical request into the runtime binary representation.
|
||||
|
||||
**How:** Implement a Scene Bank packer encoder that maps each canonical layer and tile entry directly into the versioned `SCENE` payload layout, including `glyph_asset_id`, tile size, parallax, dimensions, active state, tile activity, palette IDs, flips, and derived `tile_count`. Keep request-to-binary projection as close to isomorphic as possible and avoid injecting editor-only fields.
|
||||
|
||||
**File(s):**
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/`
|
||||
|
||||
### Step 4 - Integrate Scene Bank artifacts into pack output
|
||||
|
||||
**What:** Make Scene Bank assets participate in actual pack output and runtime metadata emission.
|
||||
|
||||
**How:** Update the relevant packer services so `SCENE_BANK` assets contribute emitted runtime files and asset-table metadata in the same build lane used by other runtime asset families, while preserving `SCENE/tilemap_v1` as the declared output format.
|
||||
|
||||
**File(s):**
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerRuntimeRegistry.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerRuntimeLoader.java`
|
||||
|
||||
### Step 5 - Prove packer/editor boundary discipline with tests
|
||||
|
||||
**What:** Prevent regression toward direct editor parsing in packer.
|
||||
|
||||
**How:** Add tests that succeed with a valid accepted canonical request even when Tiled files are ignored by packer, and tests that fail when the accepted request is missing or structurally invalid. Assert that packer diagnostics talk about the canonical request artifact rather than raw Tiled file concerns.
|
||||
|
||||
**File(s):**
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/FileSystemPackerWorkspaceServiceTest.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/PackerRuntimeAssetMaterializerTest.java`
|
||||
- `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/testing/`
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Add model validation tests for the canonical Scene Bank request records.
|
||||
- Add encoder tests for field-level request-to-binary mapping, including `glyph_asset_id`, parallax, dimensions, activity flags, palette IDs, and flips.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- Add workspace/build tests covering a valid Scene Bank asset end to end from accepted request artifact to emitted `assets.pa`.
|
||||
- Add failure tests for missing request artifact, invalid layer counts, invalid tile counts, and malformed field values.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Run a pack build on a project containing an accepted Scene Bank and inspect the emitted runtime artifact summary to confirm the scene asset is present.
|
||||
- Verify that modifying only `TMX`/`TSX` without regenerating the accepted request does not cause packer to silently read the editor files directly.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Packer can read a canonical Scene Bank request artifact without depending on `TMX` or `TSX`.
|
||||
- [ ] `SCENE_BANK` assets produce runtime `SCENE` payload bytes in pack output.
|
||||
- [ ] Structural diagnostics exist for missing or malformed accepted request artifacts.
|
||||
- [ ] Request-to-binary mapping is covered by automated tests.
|
||||
- [ ] Packer behavior preserves the editor-agnostic boundary locked by DEC-0029.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- DEC-0029 accepted.
|
||||
- PLN-0060 must land before final end-to-end validation because Studio owns generation of the accepted canonical request artifact.
|
||||
- PLN-0059 should land first or in parallel so packer implementation aligns to updated specs.
|
||||
|
||||
## Risks
|
||||
|
||||
- The exact runtime `SCENE` binary layout may still need careful reconciliation with existing runtime decoder assumptions.
|
||||
- If the accepted request artifact versioning is not explicit from the start, future format evolution may become harder to stage safely.
|
||||
- Scene Bank integration may touch several packer build phases, increasing regression risk in `assets.pa` generation.
|
||||
+101
@@ -0,0 +1,101 @@
|
||||
---
|
||||
id: PLN-0062
|
||||
ticket: studio-scene-pack-runtime-binary-contract
|
||||
title: Propagate DEC-0030 into Studio and packer specifications
|
||||
status: done
|
||||
created: 2026-04-30
|
||||
completed: 2026-04-30
|
||||
tags: [studio, packer, runtime, scene, specs, import-export]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Update the normative documentation surfaces so DEC-0030 is fully represented before or alongside code changes. The resulting specs must make the Studio-owned canonical scene entity, import/export workflow, and request separation unambiguous.
|
||||
|
||||
## Background
|
||||
|
||||
DEC-0030 supersedes the editorial-model portion of DEC-0029. The publication boundary locked by DEC-0029 remains valid, but the Studio editorial model changes materially:
|
||||
|
||||
- Studio owns a canonical scene entity;
|
||||
- `TMX`/`TSX` become import/export compatibility formats;
|
||||
- validation moves to the canonical scene entity in `Analyse` and `Pack`;
|
||||
- the scene asset model remains distinct from the `studio -> packer` request.
|
||||
|
||||
The existing specs currently describe or imply the older `TMX per layer` and `validate/accept` workflow and therefore require explicit propagation.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Update Studio specs to define the canonical scene entity as the primary editorial model.
|
||||
- Update Studio specs to define `TMX` and `TSX` as import/export formats, not canonical persistence.
|
||||
- Update packer specs to reaffirm that packer consumes only the canonical request derived from the canonical scene entity.
|
||||
- Cross-reference DEC-0029 and DEC-0030 with explicit note about what changed and what remains locked.
|
||||
- Define the validation surface shift from editor files to canonical scene analysis/pack validation.
|
||||
|
||||
### Excluded
|
||||
- Code changes in `prometeu-studio`.
|
||||
- Code changes in `prometeu-packer`.
|
||||
- Final canonical scene schema details beyond what DEC-0030 already locks.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Update Studio normative scene workflow documentation
|
||||
|
||||
**What:** Rewrite the Studio scene authoring spec so it names the Studio-owned canonical scene entity as the source of truth.
|
||||
**How:** Replace language that describes `TMX` generation, per-layer `TMX`, or `validate/accept` as the editorial workflow. Introduce import/export wizard language and preserve the distinction between canonical scene entity and external compatibility files.
|
||||
**File(s):** `docs/studio/specs/...` files that currently define Scene Bank workflow and Tiled integration.
|
||||
|
||||
### Step 2 - Update Studio validation and interoperability specification
|
||||
|
||||
**What:** Document import compatibility checks, export overwrite semantics, and validation ownership.
|
||||
**How:** Add normative statements for:
|
||||
- import compatibility failure on unsupported structural mutations;
|
||||
- diagnostic/logging requirements for failed imports;
|
||||
- `TMX` export overwrite/create behavior;
|
||||
- `TSX` export overwrite/create behavior for glyph tilesets;
|
||||
- canonical scene validation during `Analyse` and `Pack`.
|
||||
**File(s):** Studio scene and glyph tileset spec files.
|
||||
|
||||
### Step 3 - Update packer normative boundary documentation
|
||||
|
||||
**What:** Reaffirm the packer contract after DEC-0030.
|
||||
**How:** Clarify that packer still consumes only the canonical scene-pack request and remains isolated from editor-native formats, even though Studio now owns an additional canonical scene entity layer upstream.
|
||||
**File(s):** `docs/packer/specs/...` scene packing contract files.
|
||||
|
||||
### Step 4 - Record supersession and preserved rules
|
||||
|
||||
**What:** Make the DEC-0029 to DEC-0030 relationship explicit in the relevant specs.
|
||||
**How:** Note that DEC-0030 replaces only the old editorial-model assumptions, while preserving the canonical publication boundary, runtime ownership, and request compilation model.
|
||||
**File(s):** Updated Studio and packer spec references.
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
No code tests. Editorial review only.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
No runtime integration tests. Validate consistency across affected spec surfaces.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Read updated Studio and packer specs side by side with DEC-0030.
|
||||
- Confirm there is no remaining normative language that presents `TMX`/`TSX` as canonical scene persistence.
|
||||
- Confirm there is no remaining normative language that treats `validate/accept` of external editor files as the scene editorial lifecycle.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Every normative requirement in DEC-0030 is represented in at least one spec surface.
|
||||
- [ ] Studio specs clearly distinguish canonical scene entity, external import/export files, and pack request.
|
||||
- [ ] Packer specs clearly preserve the editor-agnostic request compilation boundary.
|
||||
- [ ] Spec language no longer implies `TMX per layer` or `validate/accept` over `TMX` as the primary workflow.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- DEC-0030 accepted.
|
||||
|
||||
## Risks
|
||||
|
||||
- Leaving mixed old/new vocabulary in specs would create implementation ambiguity.
|
||||
- Over-specifying the canonical scene schema here would preempt downstream implementation design that DEC-0030 intentionally leaves for planning.
|
||||
+107
@@ -0,0 +1,107 @@
|
||||
---
|
||||
id: PLN-0063
|
||||
ticket: studio-scene-pack-runtime-binary-contract
|
||||
title: Introduce the Studio canonical scene entity and project it into analysis and pack requests
|
||||
status: done
|
||||
created: 2026-04-30
|
||||
completed: 2026-04-30
|
||||
tags: [studio, scene, canonical-model, analysis, pack-request]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Implement the Studio-owned canonical scene entity and make it the sole editorial source of truth for Scene Bank assets, including canonical validation during `Analyse` and projection into the `studio -> packer` request.
|
||||
|
||||
## Background
|
||||
|
||||
DEC-0030 removes the old `TMX per layer` workflow and replaces it with a Studio-native canonical scene entity. The Studio must now own:
|
||||
|
||||
- canonical scene persistence;
|
||||
- canonical scene analysis/diagnostics;
|
||||
- derivation of the canonical scene-pack request from canonical scene state.
|
||||
|
||||
This is the core refactor that re-centers the domain model. External `TMX`/`TSX` interoperability is handled separately.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Define and persist a canonical scene entity for Scene Bank assets.
|
||||
- Replace old scene validation state that depends on `TMX`/layer acceptance.
|
||||
- Move diagnostics and validation to the canonical scene entity in `Analyse` and asset-pack readiness surfaces.
|
||||
- Derive the canonical `studio -> packer` request from the canonical scene entity.
|
||||
- Remove or retire the old layer-level `validate/accept` workflow from Studio scene handling.
|
||||
|
||||
### Excluded
|
||||
- `TMX` scene import/export implementation details.
|
||||
- `TSX` export implementation details.
|
||||
- Changes to runtime `SCENE` binary decoding.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Define canonical scene persistence and metadata model
|
||||
|
||||
**What:** Introduce the persisted Studio-owned scene entity and associated metadata structures.
|
||||
**How:** Add or revise Scene Bank metadata classes and persistence so the canonical scene entity is stored independently of `TMX` and independently of the pack request artifact. Preserve explicit layer metadata and any required editorial fields without treating external files as the source of truth.
|
||||
**File(s):** `prometeu-studio` Scene Bank metadata models, persistence services, and asset details mappings.
|
||||
|
||||
### Step 2 - Replace old workflow state and actions
|
||||
|
||||
**What:** Remove the old `validate layer`, `accept layer`, and `accept scene from TMX` lifecycle as the authoritative workflow.
|
||||
**How:** Delete or refactor workflow services, action wiring, and UI status logic so Scene Bank readiness is derived from canonical scene analysis rather than per-layer external-file fingerprints.
|
||||
**File(s):** `SceneBankWorkflowService`, asset details controls, scene layer controls, message/status models, and related UI wiring.
|
||||
|
||||
### Step 3 - Implement canonical analysis and diagnostics
|
||||
|
||||
**What:** Make `Analyse` and pack-readiness diagnostics validate the canonical scene entity.
|
||||
**How:** Add validators that check canonical layer structure, glyph asset references, layer/tile invariants, and request derivation preconditions directly from canonical scene data. Ensure diagnostics remain explicit and actionable.
|
||||
**File(s):** Studio analysis services, scene diagnostics, asset details status surfaces, and any supporting validators.
|
||||
|
||||
### Step 4 - Project canonical scene state into the pack request
|
||||
|
||||
**What:** Derive the `studio -> packer` request exclusively from the canonical scene entity.
|
||||
**How:** Replace the old `TMX`-driven request projection with canonical entity projection, preserving the existing request/runtime boundary. Persist the request artifact only as a publication projection, not as canonical editorial state.
|
||||
**File(s):** Scene request projection services, request serialization, asset workflow persistence, and related tests.
|
||||
|
||||
### Step 5 - Migrate or adapt project fixtures and internal examples
|
||||
|
||||
**What:** Update test fixtures and example assets so they reflect the new canonical scene model.
|
||||
**How:** Replace sample assets, metadata fixtures, and scene workflow tests that currently depend on `TMX per layer` acceptance semantics.
|
||||
**File(s):** `test-projects/main`, Studio workflow tests, fixture generators, and scene sample assets.
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Canonical scene persistence round-trip tests.
|
||||
- Canonical scene validation tests for blocking and non-blocking diagnostics.
|
||||
- Request projection tests proving the canonical scene entity, not `TMX`, drives the generated scene-pack request.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- End-to-end Studio asset workflow tests covering scene analysis and pack-request artifact generation from canonical scene state.
|
||||
- Regression tests proving old layer acceptance files no longer define readiness.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Open a Scene Bank asset and confirm there is no primary `validate/accept TMX` workflow.
|
||||
- Run `Analyse` and verify diagnostics reflect canonical scene state.
|
||||
- Confirm pack-request generation occurs from canonical scene state and not from external editor files.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Scene Bank assets persist a Studio-owned canonical scene entity distinct from both `TMX` and the pack request.
|
||||
- [ ] Studio readiness/diagnostics for scenes are driven by canonical scene analysis.
|
||||
- [ ] The old `validate/accept` layer-centric workflow no longer defines scene publication readiness.
|
||||
- [ ] The `studio -> packer` request is derived from canonical scene state only.
|
||||
- [ ] Existing request/runtime boundary semantics from DEC-0029 remain preserved.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- DEC-0030 accepted.
|
||||
- PLN-0062 should land first or in parallel so code aligns with updated specs.
|
||||
|
||||
## Risks
|
||||
|
||||
- Hidden dependencies on old acceptance fingerprint files may remain in the UI or workspace services.
|
||||
- If canonical schema design is underspecified in code, the implementation may accidentally recreate a `TMX-shaped` persistence model under a different name.
|
||||
- Fixture migration may expose broad assumptions in tests and project samples.
|
||||
+105
@@ -0,0 +1,105 @@
|
||||
---
|
||||
id: PLN-0064
|
||||
ticket: studio-scene-pack-runtime-binary-contract
|
||||
title: Implement Tiled scene import and glyph tileset export as compatibility workflows
|
||||
status: done
|
||||
created: 2026-04-30
|
||||
completed: 2026-04-30
|
||||
tags: [studio, tiled, tmx, tsx, import-export, interoperability]
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Implement `Tiled` interoperability as explicit compatibility workflow: scene `TMX` import into the canonical Studio scene entity, scene `TMX` export from that entity, and glyph tileset `TSX` export for Tiled consumption.
|
||||
|
||||
## Background
|
||||
|
||||
DEC-0030 keeps `TMX` and `TSX` as supported formats, but only for import/export. This means external file handling becomes adapter logic around the canonical scene and glyph-bank models, with explicit compatibility checks and overwrite semantics.
|
||||
|
||||
## Scope
|
||||
|
||||
### Included
|
||||
- Wizard-driven `TMX (Tiled)` import flow for Scene Bank assets.
|
||||
- Wizard-driven `TMX (Tiled)` export flow for Scene Bank assets.
|
||||
- Wizard-driven or equivalent `TSX (Tiled)` export flow for glyph tilesets.
|
||||
- Import compatibility validation and failure diagnostics for unsupported structural divergence.
|
||||
- Overwrite/create semantics for exported `TMX` and `TSX`.
|
||||
|
||||
### Excluded
|
||||
- Additional external scene formats beyond Tiled.
|
||||
- Packer-side parsing of `TMX` or `TSX`.
|
||||
- Broader native scene editing UX beyond what is required to support compatibility flow integration.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### Step 1 - Build Tiled import compatibility validation
|
||||
|
||||
**What:** Add import-time structural checks for supported `TMX` scene files.
|
||||
**How:** Validate the incoming `TMX` against the Studio compatibility contract before mutating canonical scene state. Reject unsupported mutations such as unexpected layers, unexpected tilesets, unsupported structural changes, or equivalent divergences. Produce explicit logs/diagnostics on failure.
|
||||
**File(s):** Tiled scene parsing/import services, diagnostics types, and import workflow orchestration.
|
||||
|
||||
### Step 2 - Implement canonical scene mutation from imported TMX
|
||||
|
||||
**What:** Update canonical scene state from accepted `TMX` imports.
|
||||
**How:** Translate compatible Tiled scene content into the canonical Studio scene entity without storing the `TMX` itself as source of truth. Ensure failed imports do not partially mutate canonical state.
|
||||
**File(s):** Scene import services, canonical scene mutation helpers, asset persistence layer, and import wizard state.
|
||||
|
||||
### Step 3 - Implement TMX export from canonical scene state
|
||||
|
||||
**What:** Serialize the canonical scene entity back into `TMX (Tiled)`.
|
||||
**How:** Generate or overwrite the destination `TMX` from canonical scene state using stable export rules. Ensure the output is explicit compatibility output and not the canonical persistence model.
|
||||
**File(s):** Tiled scene export services, wizard flows, and file-writing surfaces.
|
||||
|
||||
### Step 4 - Reframe TSX generation as export
|
||||
|
||||
**What:** Convert glyph tileset `TSX` generation into explicit `TSX (Tiled)` export behavior.
|
||||
**How:** Rename or refactor the current glyph tileset generation flow so it is clearly an export operation, with overwrite/create semantics and no implication that `TSX` is canonical storage.
|
||||
**File(s):** Glyph tileset export/generation services, UI actions, workflow naming, and related tests.
|
||||
|
||||
### Step 5 - Wire import/export into Studio UI and logs
|
||||
|
||||
**What:** Expose the interoperability workflow in the Studio asset UI.
|
||||
**How:** Add wizard entry points, action labels, progress/error reporting, and logs for successful export, successful import, and rejected imports.
|
||||
**File(s):** Asset details UI, Scene Bank controls, glyph tileset controls, event/log surfaces, and i18n messages.
|
||||
|
||||
## Test Requirements
|
||||
|
||||
### Unit Tests
|
||||
|
||||
- Import validation tests for supported and rejected `TMX` structures.
|
||||
- Scene import mutation tests proving canonical state changes only on successful import.
|
||||
- `TMX` export tests proving overwrite/create behavior.
|
||||
- `TSX` export tests proving overwrite/create behavior.
|
||||
|
||||
### Integration Tests
|
||||
|
||||
- End-to-end import workflow test from `TMX` into canonical scene state.
|
||||
- End-to-end export workflow tests for `TMX` and `TSX`.
|
||||
- Regression tests proving failed imports do not partially rewrite canonical state.
|
||||
|
||||
### Manual Verification
|
||||
|
||||
- Import a supported Tiled scene and confirm canonical scene state updates.
|
||||
- Import an unsupported Tiled scene mutation and confirm the import is rejected with clear logs.
|
||||
- Export a scene to `TMX` and confirm the destination file is overwritten or created.
|
||||
- Export a glyph tileset to `TSX` and confirm the destination file is overwritten or created.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Scene `TMX` import exists as explicit compatibility workflow and validates minimum structural compatibility before mutation.
|
||||
- [ ] Failed imports emit clear diagnostics/logs and do not partially rewrite canonical state.
|
||||
- [ ] Scene `TMX` export exists as explicit compatibility workflow with overwrite/create semantics.
|
||||
- [ ] Glyph tileset `TSX` export exists as explicit compatibility workflow with overwrite/create semantics.
|
||||
- [ ] Studio UI reflects `import/export` terminology rather than the old `generate/validate/accept` model for Tiled interoperability.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- DEC-0030 accepted.
|
||||
- PLN-0063 must land before final import/export integration because import/export targets the canonical scene entity owned by Studio.
|
||||
- PLN-0062 should land first or in parallel so UI and code terminology align with updated specs.
|
||||
|
||||
## Risks
|
||||
|
||||
- If import compatibility rules are too loose, external files will silently reshape canonical scene state.
|
||||
- If import compatibility rules are too strict, Tiled interoperability will be noisy and frustrating.
|
||||
- UI naming may remain half-migrated if old action labels or logs are left behind.
|
||||
Reference in New Issue
Block a user