Studio scene pack contract for runtime SCENE binary payload

This commit is contained in:
2026-05-01 06:59:42 +01:00
parent 1182d3ae1f
commit 822e892c82
61 changed files with 120404 additions and 685 deletions
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.