prometeu-studio/discussion/workflow/plans/PLN-0054-tiled-xml-io-and-scene-bank-file-orchestration.md

id	ticket	title	status	created	completed	tags
PLN-0054	studio-tiled-parser-assets-scene-asset-type	Tiled XML IO and Scene Bank File Orchestration	open	2026-04-17		studio assets scene tiled parser

Objective

Implement the wave-1 XML read/write pipeline for TMX and TSX, including deterministic file placement and reference orchestration between Scene Bank tilemaps and Tileset-specialized glyph-bank assets.

Background

DEC-0027 requires wave-1 XML read/write support for both TMX and TSX, keeps TMX as the maintained scene document, and requires each tilemap to reference exactly one generated TSX. It also keeps naming details implementation-owned, but requires the resulting convention to be canonical and compatible with explicit layer -> tilemap mapping.

The repository already contains example TMX and TSX files under test-projects/main/assets/scenes and test-projects/main/assets/Zelda3, which can be promoted into fixture coverage.

Scope

Included

• Add XML read/write support for supported TMX and TSX surfaces.
• Generate TSX from Tileset-specialized glyph-bank assets.
• Generate and maintain one or more TMX files inside a Scene Bank asset root.
• Define and implement a canonical naming/reference convention for multiple TMX files compatible with scene support metadata.
• Preserve supported wave-1 Tiled features: object layers, properties, flips, and collisions.

Excluded

• Studio UX for validating and accepting external edits.
• Pack/runtime materialization of scene data.
• Support for infinite maps, templates, Wang sets, or animations.

Execution Steps

Step 1 - Introduce Tiled XML domain models and codecs

What: Create the XML-side models and serialization services for supported TMX and TSX.

How: Add parser/writer services that cover the accepted wave-1 subset, preserving round-trip stability for supported fields and producing explicit diagnostics for unsupported constructs. Keep the implementation aligned to XML as the primary interoperability surface and avoid JSON-export dependencies.

File(s):

• new prometeu-studio/src/main/java/p/studio/.../tiled/... package(s) discovered during implementation
• related tests under prometeu-studio/src/test/java/p/studio/.../tiled/...

Step 2 - Generate TSX from Tileset-specialized glyph banks

What: Add the generation path that emits TSX for Glyph Bank assets specialized as Tileset.

How: Extend the asset action/details flow so a Tileset glyph bank can materialize its Tiled-facing TSX file in the asset root. The generated TSX MUST include the supported tileset-side collision/properties surface needed by wave 1 and MUST remain deterministic for later scene references.

File(s):

• prometeu-studio/src/main/java/p/studio/workspaces/assets/details/...
• prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceAssetAction.java
• prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceAssetDetails.java
• implementation packages created for Tiled file generation

Step 3 - Generate and maintain TMX files inside Scene Bank assets

What: Add the file orchestration path for one scene with up to 4 layer-linked tilemaps.

How: Use the scene-bank support metadata from PLN-0053 to generate and maintain one or more canonical TMX files in the scene asset root. Each TMX MUST reference exactly one generated TSX from a Tileset glyph-bank asset, and the chosen naming convention MUST remain stable across regenerate/validate cycles.

File(s):

• scene-bank persistence/orchestration services added under prometeu-studio/src/main/java/p/studio/...
• test fixtures under test-projects/main/assets/scenes and related asset roots

Step 4 - Enforce supported subset and failure behavior

What: Formalize the wave-1 supported subset and rejection behavior for unsupported input.

How: Add diagnostic-producing validation around XML ingest so unsupported Tiled constructs fail explicitly and do not silently normalize away unsupported content. Cover tile-owned collision in TSX and map-owned collision via Object Layer in TMX.

File(s):

• Tiled parser/validator packages introduced in this plan
• diagnostics surfaces reused by the Assets workspace

Test Requirements

Unit Tests

• Add TMX parser/writer round-trip tests for supported map metadata, layers, object layers, properties, flips, and collision cases.
• Add TSX parser/writer round-trip tests for supported tileset metadata and tile-owned collision/properties.
• Add tests for rejection/diagnostics on unsupported features such as infinite maps, templates, Wang sets, and animations.

Integration Tests

• Add end-to-end fixture tests proving a Tileset glyph bank can generate TSX and a Scene Bank can generate one or more TMX files referencing it.
• Add tests proving canonical TMX naming remains stable across regeneration using the same support metadata.

Manual Verification

• Generate TSX from a Tileset glyph bank and open it in Tiled.
• Generate a multi-tilemap scene-bank root and confirm each TMX opens in Tiled and points to the expected TSX.

Acceptance Criteria

• Studio can read and write the supported XML subset for both TMX and TSX.
• Tileset-specialized glyph banks can generate deterministic TSX files.
• Scene Bank assets can maintain multiple canonical TMX files in one asset root.
• Every generated tilemap references exactly one generated TSX in wave 1.
• Unsupported Tiled features fail with explicit diagnostics instead of silent degradation.

Dependencies

• Depends on DEC-0027.
• Depends on PLN-0053 for asset metadata and support-file ownership.
• Unblocks PLN-0055.

Risks

• XML round-trip fidelity can drift if parser and writer models are not designed from the same canonical structure.
• Canonical naming and path resolution may become unstable if they are derived from mutable UI labels instead of explicit metadata.
• TSX generation can accidentally encode Studio-only specialization state into runtime-facing data if the boundary is not kept strict.