prometeu-studio/discussion/workflow/plans/PLN-0064-tiled-scene-import-and-tileset-export-interoperability.md

id	ticket	title	status	created	completed	tags
PLN-0064	studio-scene-pack-runtime-binary-contract	Implement Tiled scene import and glyph tileset export as compatibility workflows	done	2026-04-30	2026-04-30	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.