106 lines
5.6 KiB
Markdown
106 lines
5.6 KiB
Markdown
---
|
|
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.
|