117 lines
5.3 KiB
Markdown
117 lines
5.3 KiB
Markdown
---
|
|
id: PLN-0059
|
|
ticket: studio-scene-pack-runtime-binary-contract
|
|
title: Propagate DEC-0029 into Studio and packer normative specifications
|
|
status: done
|
|
created: 2026-04-29
|
|
completed: 2026-04-29
|
|
tags:
|
|
- studio
|
|
- packer
|
|
- specs
|
|
- scene
|
|
- runtime-contract
|
|
---
|
|
|
|
## Objective
|
|
|
|
Update the normative documentation surfaces so DEC-0029 is fully reflected in Studio and packer specs before or alongside code implementation.
|
|
|
|
## Background
|
|
|
|
DEC-0029 locks the canonical publication contract for `Scene Bank` assets around a `studio -> packer` request that compiles directly into runtime `SCENE` bytes. It also locks `TMX`/`TSX` as supported but non-canonical editorial surfaces.
|
|
|
|
The current codebase already contains wave-1 Tiled support and Scene Bank validation flows, but the normative specs do not yet describe:
|
|
|
|
- the canonical scene-pack request,
|
|
- the non-canonical status of `TMX`/`TSX`,
|
|
- the `Accept` projection boundary,
|
|
- or packer ownership of binary `SCENE` compilation from a request rather than from editor files.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
- Update Studio specs to describe Scene Bank editorial ownership, validation, `Accept`, and canonical request projection.
|
|
- Update packer specs to describe request-owned publication, `SCENE/tilemap_v1`, and the prohibition on direct parsing of editor-specific formats by packer.
|
|
- Cross-link Studio and packer specs to DEC-0029 and to the existing Scene Bank asset-first wave.
|
|
|
|
### Excluded
|
|
- Java implementation changes in `prometeu-studio`.
|
|
- Java implementation changes in `prometeu-packer`.
|
|
- Lesson or housekeeping work for DSC-0030.
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Update Studio asset workspace specification
|
|
|
|
**What:** Add normative Scene Bank language to the Studio `Assets` workspace spec.
|
|
|
|
**How:** Extend the asset-family-specific rules in the Studio spec so Scene Bank authoring is explicitly asset-owned, `TMX`/`TSX` are editorial integrations rather than canonical publication artifacts, and `Accept` is defined as the projection point into the canonical pack request.
|
|
|
|
**File(s):**
|
|
- `docs/specs/studio/4. Assets Workspace Specification.md`
|
|
|
|
### Step 2 - Update packer declaration and build-boundary specifications
|
|
|
|
**What:** Describe the canonical request and packer-owned build behavior in packer specs.
|
|
|
|
**How:** Amend the common asset contract spec and the operational/build specs so `SCENE/tilemap_v1` is documented as a runtime-oriented format whose packer input is the canonical scene-pack request produced by Studio, not raw editor files. Make explicit that editor-specific files remain tooling/editorial surfaces and MUST NOT be parsed directly by packer.
|
|
|
|
**File(s):**
|
|
- `docs/specs/packer/3. Asset Declaration and Virtual Asset Contract Specification.md`
|
|
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`
|
|
- `docs/specs/packer/5. Diagnostics, Operations, and Studio Integration Specification.md`
|
|
|
|
### Step 3 - Record canonical field semantics
|
|
|
|
**What:** Add the canonical scene-pack request fields and rules.
|
|
|
|
**How:** Document the fixed four-layer request shape, layer-level `glyph_asset_id`, `tile_size`, `parallax_factor`, `width`, `height`, tile-level `active`, `glyph_id`, `palette_id`, `flip_x`, `flip_y`, and the rule that `tile_count` is derived from dimensions. Lock the default-plus-override semantics for `palette_id`.
|
|
|
|
**File(s):**
|
|
- `docs/specs/studio/4. Assets Workspace Specification.md`
|
|
- `docs/specs/packer/4. Build Artifacts and Deterministic Packing Specification.md`
|
|
|
|
### Step 4 - Align gating and future-editor rules
|
|
|
|
**What:** Ensure the specs preserve future editor substitution without weakening the current wave.
|
|
|
|
**How:** Add explicit normative text that any future editor may replace or coexist with Tiled-backed editing only if it emits the same canonical request and passes the same validation and `Accept` rules. Preserve the wave-1 single-tileset-per-layer restriction.
|
|
|
|
**File(s):**
|
|
- `docs/specs/studio/4. Assets Workspace Specification.md`
|
|
- `docs/specs/packer/5. Diagnostics, Operations, and Studio Integration Specification.md`
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
|
|
- No code unit tests are required for this editorial plan.
|
|
|
|
### Integration Tests
|
|
|
|
- No automated integration tests are required for this editorial plan.
|
|
|
|
### Manual Verification
|
|
|
|
- Review the updated specs side by side with DEC-0029 and confirm that every normative rule in the decision has a corresponding spec statement.
|
|
- Confirm there is no spec language implying that packer parses `TMX` or `TSX` directly.
|
|
- Confirm the specs do not describe Tiled as deprecated or temporary.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] The Studio spec defines Scene Bank `Accept` as the projection boundary into the canonical scene-pack request.
|
|
- [ ] The packer specs define `SCENE/tilemap_v1` publication in terms of the canonical request, not editor files.
|
|
- [ ] The specs state that `TMX`/`TSX` are supported but non-canonical editorial surfaces.
|
|
- [ ] The specs allow future additional editors only through the same canonical request and validation path.
|
|
- [ ] Every normative requirement in DEC-0029 is represented in at least one spec file.
|
|
|
|
## Dependencies
|
|
|
|
- DEC-0029 accepted.
|
|
|
|
## Risks
|
|
|
|
- Editorial drift between Studio and packer specs could reintroduce ambiguity about who owns the canonical request.
|
|
- If the specs omit the field semantics for `palette_id` precedence or tile/layer `active`, code plans may diverge during implementation.
|