--- id: PLN-0054 ticket: studio-tiled-parser-assets-scene-asset-type title: Tiled XML IO and Scene Bank File Orchestration status: open created: 2026-04-17 completed: tags: - 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.