tiled parser discussion
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

This commit is contained in:
2026-04-18 16:33:45 +01:00
parent 5098365eda
commit ea8c81368b
7 changed files with 563 additions and 19 deletions
@@ -0,0 +1,121 @@
---
id: PLN-0053
ticket: studio-tiled-parser-assets-scene-asset-type
title: Scene Bank Asset Contract and Studio Metadata Foundations
status: open
created: 2026-04-17
completed:
tags:
- studio
- assets
- scene
- tiled
- metadata
---
## Objective
Establish the asset contract and Studio-owned metadata foundations required by `DEC-0027` so `Scene Bank` assets and specialized `Glyph Bank` assets can exist in the `Assets` workspace without reintroducing a dedicated scene workspace or a separate normalized scene schema.
## Background
`DEC-0027` locks the following requirements that must be reflected in the asset contract before parser and UX work can be implemented safely:
- `Scene Bank` is an asset owned by the `Assets` workspace.
- `Glyph Bank` remains the base runtime asset family, with Studio-only specialization flags such as `Tileset`, `Sprites`, and `UI`.
- `TMX` remains the maintained scene document format.
- `Scene Bank` support files own the explicit `layer -> tilemap` mapping.
- one scene may contain multiple tilemaps, with up to `4` layers in wave 1.
The current repo already has the asset creation and detail surfaces under `prometeu-studio/src/main/java/p/studio/workspaces/assets` and the asset manifest/runtime contract under `prometeu-packer/prometeu-packer-v1`.
## Scope
### Included
- Add `Scene Bank` as a first-class asset option in the Studio asset creation and details pipeline.
- Add the Studio-only specialization model for `Glyph Bank` assets, including `Tileset`, `Sprites`, and `UI`.
- Define where Studio-owned scene support files and specialization metadata live relative to existing asset roots.
- Add summary/details projection support so the `Assets` workspace can display base family plus specialization chip.
- Define the wave-1 metadata contract for scene-layer mapping and scene-bank limits.
### Excluded
- TMX/TSX XML parsing and serialization logic.
- External-edit acceptance UI or file-diff validation flows.
- Pack publication of scene assets into runtime binary formats.
## Execution Steps
### Step 1 - Extend asset family and metadata models
**What:** Introduce the data models needed for `Scene Bank` assets and Studio-only glyph-bank specialization.
**How:** Update the packer/studio shared asset declarations and detail projection pipeline so `Scene Bank` can be created, read, and surfaced by the `Assets` workspace while keeping `Glyph Bank` as the underlying runtime family for specializations. Define the Studio-only specialization enum and the scene-bank support metadata surface that will later carry `layer -> tilemap` mapping and wave-1 constraints.
**File(s):**
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerAssetDeclarationParser.java`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerAssetDetailsService.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceAssetSummary.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceAssetDetails.java`
- additional shared DTOs or catalogs discovered from the asset declaration flow
### Step 2 - Add creation and details support in Assets workspace
**What:** Make `Scene Bank` and glyph-bank specialization available in the actual Studio asset workflow.
**How:** Extend the add-asset wizard to expose `Scene Bank` as an asset type and add the minimum specialization capture or follow-up action path for `Glyph Bank`. Update details/summary rendering to show `Glyph Bank / Tileset`-style presentation and to surface scene-bank metadata ownership in the details view without inventing a separate workspace region.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/wizards/AddAssetWizard.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/summary/AssetDetailsSummaryControl.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsControl.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsUiSupport.java`
- `prometeu-studio/src/main/resources/i18n/messages.properties`
### Step 3 - Define on-disk scene-bank support-file baseline
**What:** Establish the first implementation-owned support-file baseline for scene banks.
**How:** Introduce a concrete but implementation-scoped support-file format that records scene layer count, `layer -> tilemap` mapping, and references needed by the `Assets` workspace. The plan MUST preserve the decision rule that the exact shape can be discovered during implementation, but the result MUST be explicit, deterministic, and colocated with the scene asset root.
**File(s):**
- asset-root support files under `test-projects/main/assets/...` fixtures
- implementation targets discovered while wiring Studio asset persistence
- related tests in `prometeu-studio/src/test/java/p/studio/workspaces/assets/...` and `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/...`
## Test Requirements
### Unit Tests
- Add parser/service tests proving `Scene Bank` assets can be created and read through the asset declaration pipeline.
- Add Studio projection tests proving summary/details surfaces can represent base family plus specialization.
- Add tests for the support-file metadata model, including `1..4` layer constraints and explicit `layer -> tilemap` mapping requirements.
### Integration Tests
- Extend asset workspace service tests to verify end-to-end creation of a `Scene Bank` asset root and detail retrieval.
- Add or update test fixtures under `test-projects/main/assets` to cover specialized glyph banks and scene-bank roots with multiple tilemaps.
### Manual Verification
- Create a new `Scene Bank` from the Assets workspace and confirm the asset appears in the list/details flow.
- Create or mark a `Glyph Bank` as `Tileset` and confirm the summary shows base family plus specialization chip.
## Acceptance Criteria
- [ ] `Scene Bank` exists as a first-class asset choice in the Studio asset flow.
- [ ] Studio-only glyph-bank specialization is represented by a closed metadata set and does not redefine the runtime asset family.
- [ ] The Assets workspace can display base family and specialization together in the summary/details flow.
- [ ] Scene-bank support metadata explicitly records `layer -> tilemap` mapping and enforces the wave-1 `4`-layer limit.
- [ ] No plan step introduces a dedicated scene workspace or a normalized Studio-owned scene format.
## Dependencies
- Depends on `DEC-0027`.
- Unblocks `PLN-0054` and `PLN-0055`.
## Risks
- The current asset declaration pipeline may assume existing family/output combinations too rigidly, which can force deeper changes in packer services than the UI suggests.
- If specialization metadata is embedded in the wrong layer, Studio-only editorial flags may leak into runtime-facing contracts.
- If the support-file baseline is too vague, later parser and validation work will drift on naming and ownership.
@@ -0,0 +1,120 @@
---
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.
@@ -0,0 +1,120 @@
---
id: PLN-0055
ticket: studio-tiled-parser-assets-scene-asset-type
title: Assets Workspace Scene Bank Validation and Acceptance Flow
status: open
created: 2026-04-17
completed:
tags:
- studio
- assets
- scene
- validation
- ux
---
## Objective
Implement the `Assets` workspace flow that validates external `Tiled` edits, surfaces diagnostics, and requires explicit Studio-side acceptance before a `Scene Bank` is considered ready.
## Background
`DEC-0027` requires the initial workflow to be:
1. create the scene asset in Studio;
2. edit generated `TMX`/`TSX` in `Tiled`;
3. return to Studio;
4. validate;
5. explicitly accept the converged changes.
The decision explicitly forbids silent auto-acceptance and requires the same general diagnostic discipline already used for glyph assets. The current `Assets` workspace already contains refresh, detail, action, and diagnostics surfaces that can host this flow without creating a dedicated scene workspace.
## Scope
### Included
- Add scene-bank validation state to the `Assets` workspace projections.
- Add explicit actions to validate and accept external scene-bank changes.
- Surface scene/Tiled diagnostics in the existing asset details/logging patterns.
- Ensure readiness/build participation reflects acceptance state for scene banks.
### Excluded
- Automatic merge/convergence of external edits.
- A dedicated scene-editing workspace.
- Pack/runtime publication.
## Execution Steps
### Step 1 - Extend asset details state for scene-bank validation
**What:** Add the projection/state needed to represent scene-bank validation and acceptance status in the assets UI.
**How:** Extend the asset workspace message and detail-state models so scene-bank assets can expose pending external changes, validation result, acceptance readiness, and scene-specific actions while reusing the current details/action host rather than adding a separate workspace.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceAssetDetails.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceDetailsViewState.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceAssetAction.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsControl.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/dialogs/AssetDiagnosticsDialog.java`
### Step 2 - Add validate/accept actions to existing assets action surface
**What:** Add the concrete user actions for scene-bank validation and explicit acceptance.
**How:** Extend the existing asset actions surface so scene-bank assets can trigger validation against current `TMX`/`TSX` and then explicitly accept the converged result. Keep these actions stacked with existing asset actions, in line with `DEC-0027`, and ensure availability is driven by asset family/state rather than a new intermediate panel.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/summary/AssetDetailsSummaryControl.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsUiSupport.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/...` action-host controls discovered during implementation
- `prometeu-studio/src/main/resources/i18n/messages.properties`
### Step 3 - Connect validation results to diagnostics and readiness gates
**What:** Make validation outcome meaningful to the workflow.
**How:** Reuse the current diagnostic/log/event patterns so unsupported references, broken paths, invalid tilemap-to-layer mapping, and unsupported Tiled constructs surface as diagnostics. Mark the scene bank as not ready until validation succeeds and explicit acceptance is recorded. Reflect this status in build participation or equivalent readiness signals without implementing pack publication itself.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/events/...`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetLogsPane.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java`
- any validation coordinator/services created for scene-bank acceptance
## Test Requirements
### Unit Tests
- Add tests for scene-bank details state transitions: created, externally changed, validation failed, validation passed, accepted.
- Add tests proving accept is unavailable when validation diagnostics remain.
- Add tests proving scene-bank actions are hosted in the existing asset actions surface.
### Integration Tests
- Add assets workspace tests covering refresh after external file edits, validation, diagnostics surfacing, and explicit acceptance.
- Add fixture-backed tests covering invalid TSX references, unsupported TMX features, and broken layer-to-tilemap mappings.
### Manual Verification
- Create a scene bank in Studio, edit its `TMX`/`TSX` externally in Tiled, return to Studio, validate, and explicitly accept.
- Confirm the asset stays unready when diagnostics remain and becomes ready only after successful validation plus explicit acceptance.
## Acceptance Criteria
- [ ] Scene-bank assets expose validate/accept actions in the existing asset action surface.
- [ ] Studio surfaces scene-bank diagnostics using the existing general diagnostic discipline.
- [ ] Studio does not silently auto-accept external `Tiled` edits.
- [ ] A scene bank is not considered ready until validation succeeds and the user explicitly accepts the result.
- [ ] No part of the workflow introduces a dedicated scene workspace.
## Dependencies
- Depends on `DEC-0027`.
- Depends on `PLN-0053` for asset/state foundations.
- Depends on `PLN-0054` for TMX/TSX ingest and validation inputs.
## Risks
- If refresh and validation state are coupled too loosely, the UI can show stale readiness after external edits.
- If acceptance is represented only in transient UI state, Studio may lose the required gate after reload.
- If diagnostics are not normalized with existing asset flows, scene-bank errors will feel like a separate subsystem.