108 lines
5.7 KiB
Markdown
108 lines
5.7 KiB
Markdown
---
|
|
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.
|