131 lines
6.9 KiB
Markdown
131 lines
6.9 KiB
Markdown
---
|
|
id: PLN-0061
|
|
ticket: studio-scene-pack-runtime-binary-contract
|
|
title: Compile the canonical Scene Bank request into runtime SCENE in packer
|
|
status: done
|
|
created: 2026-04-29
|
|
completed: 2026-04-29
|
|
tags:
|
|
- 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.
|