prometeu-studio/discussion/workflow/plans/PLN-0053-scene-bank-asset-contract-and-studio-metadata-foundations.md

id	ticket	title	status	created	completed	tags
PLN-0053	studio-tiled-parser-assets-scene-asset-type	Scene Bank Asset Contract and Studio Metadata Foundations	open	2026-04-17		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.