---
id: DEC-0029
ticket: studio-scene-pack-runtime-binary-contract
title: Studio scene pack contract for runtime SCENE binary payload
status: accepted
created: 2026-04-29
accepted: 2026-04-29
agenda: AGD-0032
plans:
  - PLN-0059
  - PLN-0060
  - PLN-0061
tags:
  - 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:

```text
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.