bQUARKz
ea8c81368b
All checks were successful
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 60.67% (15274/25176)
* Branch Coverage: 53.64% (5782/10779)
* Lines of Code: 25176
* Cyclomatic Complexity: 9960
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 11, passed: 545
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good
121 lines
6.1 KiB
Markdown
121 lines
6.1 KiB
Markdown
---
|
|
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.
|