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
122 lines
7.0 KiB
Markdown
122 lines
7.0 KiB
Markdown
---
|
|
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.
|