prometeu-studio/discussion/workflow/decisions/DEC-0029-studio-scene-pack-runtime-binary-contract.md

id	ticket	title	status	created	accepted	agenda	plans	tags
DEC-0029	studio-scene-pack-runtime-binary-contract	Studio scene pack contract for runtime SCENE binary payload	accepted	2026-04-29	2026-04-29	AGD-0032	PLN-0059 PLN-0060 PLN-0061	studio packer runtime scene asset-pack binary-format tiled

Decision

The canonical publication contract for Scene Bank assets SHALL be the studio -> packer scene-pack request and its direct compilation into runtime SCENE payload bytes.

TMX and TSX SHALL remain supported editorial surfaces for wave 1 inside the studio domain, but they MUST NOT define the normative publication contract, the runtime asset shape, or the packer boundary.

The system MAY support additional scene editors in the future. Any supported editor MUST materialize the same canonical scene-pack request and MUST pass the same validation and Accept gating rules before publication.

prometeu-packer SHALL compile only the canonical scene-pack request into the runtime SCENE payload. It MUST NOT parse TMX, TSX, or any other editor-specific surface directly.

The runtime SCENE dependency contract SHALL use glyph_asset_id per layer. Resolution from glyph_asset_id to runtime glyph slot SHALL remain a runtime concern and MUST NOT be serialized by Studio or packer as a pre-resolved slot.

Rationale

This decision preserves the already accepted wave-1 editorial direction from DSC-0028 while preventing Tiled from becoming the canonical asset model by accident.

The binary SCENE runtime payload already exists and is the true sink of the pipeline. The missing architectural piece is therefore not a new scene schema, but a stable domain boundary that lets Studio accept editorial state and lets packer compile a runtime-owned request without absorbing external-tool concerns.

Treating TMX and TSX as supported but non-canonical keeps the current workflow viable, while leaving the door open for future integrated editors or multiple editors without reopening the packer or runtime contract.

Technical Specification

1. Domain Ownership

• studio SHALL own editorial scene authoring, validation, diagnostics, and Accept.
• packer SHALL own compilation of the canonical request into binary SCENE.
• runtime SHALL own decoding, binding, and operational slot resolution for glyph dependencies.

2. Supported Editorial Surfaces

• Wave 1 SHALL support TMX and TSX as editorial surfaces in studio.
• These surfaces MUST be treated as replaceable editor integrations, not as canonical publication artifacts.
• Future editors MAY replace or coexist with Tiled-backed surfaces if they emit the same canonical request and satisfy the same validation semantics.

3. Canonical studio -> packer Request

The canonical request SHALL be defined as:

ScenePackRequest
- version: int
- layers: [ScenePackLayerRequest; 4]

ScenePackLayerRequest
- active: bool
- glyph_asset_id: int
- tile_size: int
- parallax_factor_x: float
- parallax_factor_y: float
- width: int
- height: int
- tiles: List<ScenePackTileRequest>

ScenePackTileRequest
- active: bool
- glyph_id: int
- palette_id: int
- flip_x: bool
- flip_y: bool

Normative rules:

• request -> SCENE SHALL be as direct as possible.
• tile_count SHALL be derived from width * height.
• Binary reserved fields MUST NOT be mirrored into the request unless they gain explicit editorial meaning.
• layers SHALL always materialize exactly 4 entries in wave 1.

4. Layer and Tile Semantics

• glyph_asset_id SHALL be derived from the glyph asset/tileset selected for the layer in Studio.
• parallax_factor_x and parallax_factor_y SHALL be modeled as layer-owned editorial fields in Studio.
• palette_id SHALL be modeled with a layer-level editorial default in Studio, with optional per-tile override when supported by the editorial surface.
• active at layer scope SHALL indicate whether the layer participates in publication output.
• active at tile scope SHALL indicate whether the tile contributes an active tile record to the published scene payload.
• Wave 1 SHALL remain limited to exactly 1 TSX per TMX per layer.

5. Validation and Acceptance

• Publication MUST be gated by absence of blocking diagnostic errors.
• The Accept step in Studio SHALL be the moment where supported editorial state is validated and projected into the canonical request.
• Studio MUST NOT silently auto-accept external editor mutations.

6. Manifest and Runtime Projection

• The manifest output format SHALL remain SCENE/tilemap_v1 for this wave.
• The runtime payload SHALL carry glyph_asset_id per layer.
• Runtime slot allocation and asset_id -> slot resolution MUST remain runtime-internal behavior.

Constraints

• This decision MUST NOT be interpreted as introducing a dedicated scene workspace.
• This decision MUST NOT be interpreted as allowing packer to parse editor-specific formats directly.
• This decision MUST NOT be interpreted as making Tiled temporary or deprecated; it is supported, but non-canonical.
• This decision does not reopen wave-1 limits around single-tileset-per-layer authoring.
• Any future change to the canonical request or runtime projection SHALL require explicit decision review.

Revision Log

• 2026-04-29: Initial draft from AGD-0032.
• 2026-04-29: Accepted and decomposed into implementation plans PLN-0059, PLN-0060, and PLN-0061.