138 lines
7.7 KiB
Markdown
138 lines
7.7 KiB
Markdown
---
|
|
id: PLN-0060
|
|
ticket: studio-scene-pack-runtime-binary-contract
|
|
title: Build Scene Bank canonical request projection and acceptance in Studio
|
|
status: done
|
|
created: 2026-04-29
|
|
completed: 2026-04-29
|
|
tags:
|
|
- 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.
|