--- 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.