--- 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.