prometeu-studio/discussion/workflow/plans/PLN-0061-scene-pack-request-materialization-and-packer-build.md

id	ticket	title	status	created	completed	tags
PLN-0061	studio-scene-pack-runtime-binary-contract	Compile the canonical Scene Bank request into runtime SCENE in packer	done	2026-04-29	2026-04-29	packer scene runtime binary-format build

Objective

Implement the packer-owned path that reads the accepted canonical scene-pack request and emits runtime SCENE binary payloads for Scene Bank assets.

Background

prometeu-packer already recognizes SCENE_BANK and the SCENE/tilemap_v1 output format, but SCENE_BANK currently stops short of real materialization. DEC-0029 locks the rule that packer must compile a canonical request and must not parse TMX or TSX directly.

This plan delivers the missing operational half of the boundary.

Scope

Included

• Introduce packer-side models for the canonical Scene Bank request.
• Validate the accepted request artifact as a packer input.
• Encode runtime SCENE binary payloads from the canonical request.
• Integrate Scene Bank packing into the existing runtime materialization/build flow.

Excluded

• Studio UI and metadata authoring changes.
• Runtime decoder changes beyond what is already assumed by DEC-0029.
• Multi-tileset-per-layer or non-wave-1 scene authoring features.

Execution Steps

Step 1 - Add canonical request models to the packer API

What: Define stable packer-side Java models for the canonical Scene Bank request.

How: Add DTOs/records for ScenePackRequest, ScenePackLayerRequest, and ScenePackTileRequest in prometeu-packer-api, including validation helpers for fixed layer count, required dimensions, and field presence. These models must be editor-agnostic and must not mention TMX or TSX.

File(s):

• prometeu-packer/prometeu-packer-api/src/main/java/p/packer/messages/assets/
• prometeu-packer/prometeu-packer-api/build.gradle.kts if package exports or module wiring need updates

Step 2 - Teach packer to read and validate the accepted request artifact

What: Load Scene Bank publication input from the accepted request artifact rather than from editor files.

How: Extend the Scene Bank walking/materialization path so packer looks for the accepted canonical request artifact in the asset root, validates the fixed four-layer structure, checks width * height against tile counts, rejects missing or malformed request content, and emits structural diagnostics when the request is absent or invalid.

File(s):

• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerAssetWalker.java
• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerRuntimeAssetMaterializer.java
• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java

Step 3 - Encode runtime SCENE payload bytes

What: Turn the canonical request into the runtime binary representation.

How: Implement a Scene Bank packer encoder that maps each canonical layer and tile entry directly into the versioned SCENE payload layout, including glyph_asset_id, tile size, parallax, dimensions, active state, tile activity, palette IDs, flips, and derived tile_count. Keep request-to-binary projection as close to isomorphic as possible and avoid injecting editor-only fields.

File(s):

• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/
• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/models/
• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/

Step 4 - Integrate Scene Bank artifacts into pack output

What: Make Scene Bank assets participate in actual pack output and runtime metadata emission.

How: Update the relevant packer services so SCENE_BANK assets contribute emitted runtime files and asset-table metadata in the same build lane used by other runtime asset families, while preserving SCENE/tilemap_v1 as the declared output format.

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/repositories/PackerRuntimeRegistry.java
• prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/repositories/PackerRuntimeLoader.java

Step 5 - Prove packer/editor boundary discipline with tests

What: Prevent regression toward direct editor parsing in packer.

How: Add tests that succeed with a valid accepted canonical request even when Tiled files are ignored by packer, and tests that fail when the accepted request is missing or structurally invalid. Assert that packer diagnostics talk about the canonical request artifact rather than raw Tiled file concerns.

File(s):

• prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/FileSystemPackerWorkspaceServiceTest.java
• prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/repositories/PackerRuntimeAssetMaterializerTest.java
• prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/testing/

Test Requirements

Unit Tests

• Add model validation tests for the canonical Scene Bank request records.
• Add encoder tests for field-level request-to-binary mapping, including glyph_asset_id, parallax, dimensions, activity flags, palette IDs, and flips.

Integration Tests

• Add workspace/build tests covering a valid Scene Bank asset end to end from accepted request artifact to emitted assets.pa.
• Add failure tests for missing request artifact, invalid layer counts, invalid tile counts, and malformed field values.

Manual Verification

• Run a pack build on a project containing an accepted Scene Bank and inspect the emitted runtime artifact summary to confirm the scene asset is present.
• Verify that modifying only TMX/TSX without regenerating the accepted request does not cause packer to silently read the editor files directly.

Acceptance Criteria

• Packer can read a canonical Scene Bank request artifact without depending on TMX or TSX.
• SCENE_BANK assets produce runtime SCENE payload bytes in pack output.
• Structural diagnostics exist for missing or malformed accepted request artifacts.
• Request-to-binary mapping is covered by automated tests.
• Packer behavior preserves the editor-agnostic boundary locked by DEC-0029.

Dependencies

• DEC-0029 accepted.
• PLN-0060 must land before final end-to-end validation because Studio owns generation of the accepted canonical request artifact.
• PLN-0059 should land first or in parallel so packer implementation aligns to updated specs.

Risks

• The exact runtime SCENE binary layout may still need careful reconciliation with existing runtime decoder assumptions.
• If the accepted request artifact versioning is not explicit from the start, future format evolution may become harder to stage safely.
• Scene Bank integration may touch several packer build phases, increasing regression risk in assets.pa generation.