prometeu-studio/discussion/workflow/plans/PLN-0060-scene-bank-studio-request-projection-and-acceptance.md

id	ticket	title	status	created	completed	tags
PLN-0060	studio-scene-pack-runtime-binary-contract	Build Scene Bank canonical request projection and acceptance in Studio	done	2026-04-29	2026-04-29	studio scene assets tiled acceptance

Objective

Implement the Studio-owned projection from supported editorial scene state into the canonical scene-pack request, with validation and Accept gating aligned to DEC-0029.

Background

Studio already owns Scene Bank support metadata, Tiled generation, diagnostics, validation, and explicit acceptance. Today, however, the acceptance flow persists only validation fingerprints and does not yet materialize the canonical studio -> packer request required by DEC-0029.

This plan turns Accept from a pure approval marker into the normative projection boundary for Scene Bank publication.

Scope

Included

• Extend Scene Bank support metadata and UI/editorial state to carry the fields required by the canonical request.
• Generate and persist the canonical request during Scene Bank Accept.
• Validate the editorial-to-request mapping, including layer defaults and tile overrides.
• Keep Tiled integration as a supported editorial path without making it canonical.

Excluded

• Binary SCENE encoding in packer.
• Runtime decoder or runtime scene-binding changes.
• A new integrated scene editor.

Execution Steps

Step 1 - Expand Scene Bank editorial metadata

What: Add the missing layer-owned editorial fields required by the canonical request.

How: Extend the Scene Bank metadata model and serialization so each layer can carry at minimum parallax_factor_x, parallax_factor_y, and a layer-level default palette_id, while preserving the existing enabled-state, dimensions, tilemap, and tileset_asset_root binding rules.

File(s):

• prometeu-studio/src/main/java/p/studio/workspaces/assets/metadata/AssetStudioSceneBankMetadata.java
• prometeu-studio/src/main/java/p/studio/workspaces/assets/metadata/AssetStudioSceneLayerBinding.java
• prometeu-studio/src/main/java/p/studio/workspaces/assets/metadata/AssetStudioMetadataService.java
• prometeu-studio/src/test/java/p/studio/workspaces/assets/metadata/AssetStudioMetadataServiceTest.java

Step 2 - Surface the new fields in the Scene Bank details UI

What: Make the canonical request inputs editable and reviewable in Studio.

How: Update the Scene Bank layer controls so the layer form exposes parallax values, default palette selection, and clearly ties glyph_asset_id derivation to the selected tileset asset. Preserve the existing enabled checkbox as the layer-level publication toggle.

File(s):

• prometeu-studio/src/main/java/p/studio/workspaces/assets/details/scene/AssetDetailsSceneLayersControl.java
• prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsControl.java
• prometeu-studio/src/main/java/p/studio/utilities/i18n/I18n.java
• prometeu-studio/src/main/resources/i18n/messages.properties

Step 3 - Build canonical request projection from accepted editorial state

What: Materialize the canonical scene-pack request during Accept.

How: Introduce Studio-side request DTOs or records for ScenePackRequest, ScenePackLayerRequest, and ScenePackTileRequest. Update SceneBankWorkflowService so Accept validates the supported editorial inputs, parses TMX/TSX, derives glyph_asset_id, applies layer-default plus per-tile palette_id overrides, resolves per-tile glyph_id, flip_x, flip_y, and persists the resulting canonical request as the accepted publication input for packer consumption.

File(s):

• prometeu-studio/src/main/java/p/studio/workspaces/assets/scene/SceneBankWorkflowService.java
• prometeu-studio/src/main/java/p/studio/workspaces/assets/scene/SceneBankWorkflowResult.java
• prometeu-studio/src/main/java/p/studio/workspaces/assets/tiled/TiledXmlCodec.java
• prometeu-studio/src/main/java/p/studio/workspaces/assets/tiled/TiledMapDocument.java
• prometeu-studio/src/main/java/p/studio/workspaces/assets/tiled/TiledTilesetDocument.java
• prometeu-studio/src/main/java/p/studio/workspaces/assets/tiled/TiledTilesetTile.java

Step 4 - Tighten validation around canonical semantics

What: Ensure Studio rejects editorial states that cannot be projected safely into the canonical request.

How: Extend validation so it blocks acceptance when a layer lacks a resolvable tileset asset, when per-tile data cannot be mapped to a valid glyph_id or palette_id, when unsupported Tiled features would break canonical projection, or when wave-1 constraints such as single-tileset-per-layer are violated.

File(s):

• prometeu-studio/src/main/java/p/studio/workspaces/assets/scene/SceneBankWorkflowService.java
• prometeu-studio/src/test/java/p/studio/workspaces/assets/scene/SceneBankWorkflowServiceTest.java
• prometeu-studio/src/test/java/p/studio/workspaces/assets/tiled/TiledXmlCodecTest.java
• prometeu-studio/src/test/java/p/studio/workspaces/assets/tiled/TiledAssetGenerationServiceTest.java

Step 5 - Expose acceptance artifacts to downstream consumers

What: Make the accepted canonical request visible to the rest of the Studio-to-packer flow.

How: Persist the accepted request in a deterministic asset-local file or equivalent accepted artifact and update the details refresh flow so the accepted/publication-ready state reflects both validation success and presence of the canonical request artifact.

File(s):

• prometeu-studio/src/main/java/p/studio/workspaces/assets/scene/SceneBankWorkflowService.java
• prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceAssetDetails.java
• prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsViewStateFactory.java
• prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceSceneBankValidation.java

Test Requirements

Unit Tests

• Add metadata serialization/deserialization coverage for the new layer fields.
• Add request-projection tests for glyph_asset_id derivation, default palette_id, per-tile palette_id override, and tile flip mapping.

Integration Tests

• Add Scene Bank workflow tests covering validate-then-accept for a valid layer set and failure cases for unsupported or incomplete editorial state.
• Add acceptance-artifact tests proving external file mutation invalidates the accepted state until revalidation and reacceptance.

Manual Verification

• Create or update a Scene Bank asset in the test project, validate it, accept it, and confirm the accepted artifact contains the full canonical request.
• Change a TMX or TSX file after acceptance and confirm Studio returns the asset to a non-ready state.

Acceptance Criteria

• Scene Bank metadata and UI expose the layer-owned fields required by DEC-0029.
• Accept emits a deterministic canonical scene-pack request artifact from the supported editorial state.
• Validation blocks any Scene Bank that cannot be projected into the canonical request without guessing.
• Layer default and per-tile override semantics for palette_id are implemented and tested.
• Studio continues to support Tiled-backed editing without making TMX/TSX the canonical publication surface.

Dependencies

• DEC-0029 accepted.
• PLN-0059 should land first or in parallel so the code aligns to updated specs.

Risks

• The current Tiled parsing model may not yet expose every per-tile property needed for deterministic request projection.
• If the accepted artifact shape is underspecified, packer integration may later depend on unstable serialization details.
• UI additions for layer metadata can introduce partial-state bugs if draft/application flow is not kept consistent.