124 lines
5.4 KiB
Markdown
124 lines
5.4 KiB
Markdown
---
|
|
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.
|