Studio scene pack contract for runtime SCENE binary payload
This commit is contained in:
@@ -0,0 +1,123 @@
|
||||
---
|
||||
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.
|
||||
+147
@@ -0,0 +1,147 @@
|
||||
---
|
||||
id: DEC-0030
|
||||
ticket: studio-scene-pack-runtime-binary-contract
|
||||
title: Studio-native scene canonical model with Tiled import-export compatibility
|
||||
status: accepted
|
||||
created: 2026-04-30
|
||||
accepted: 2026-04-30
|
||||
agenda: AGD-0033
|
||||
plans:
|
||||
- PLN-0062
|
||||
- PLN-0063
|
||||
- PLN-0064
|
||||
tags:
|
||||
- studio
|
||||
- packer
|
||||
- runtime
|
||||
- scene
|
||||
- asset-pack
|
||||
- tiled
|
||||
- import-export
|
||||
- revision
|
||||
---
|
||||
|
||||
## Decision
|
||||
|
||||
`Scene Bank` authoring in `studio` SHALL move to a Studio-native canonical scene model.
|
||||
|
||||
`TMX` and `TSX` SHALL remain supported formats, but only as import/export and compatibility surfaces. They MUST NOT be treated as the primary editorial model, the validation target, or the canonical publication state.
|
||||
|
||||
The Studio workflow for scenes SHALL NOT use `generate`, `validate`, or `accept` over `TMX`, per-layer `TMX`, or any equivalent editor-owned surface. Instead, Studio SHALL own:
|
||||
|
||||
- a canonical scene entity for the asset itself;
|
||||
- `import` from supported external formats into that canonical scene entity;
|
||||
- `export` from that canonical scene entity into supported external formats.
|
||||
|
||||
For wave 1 of this revision:
|
||||
|
||||
- `Tiled` SHALL be the first supported import/export option;
|
||||
- `TMX` scene import SHALL update the canonical scene entity from the external file;
|
||||
- `TMX` scene export SHALL overwrite the target `TMX` or create it if missing;
|
||||
- glyph-bank `TSX` generation SHALL be treated as `TSX (Tiled)` export and SHALL overwrite the target `TSX` or create it if missing.
|
||||
|
||||
Validation SHALL occur over the canonical Studio scene entity during `Analyse` and/or `Pack`. The canonical Studio scene entity SHALL remain distinct from the `studio -> packer` scene-pack request, and that request SHALL remain distinct from the runtime `SCENE` binary payload.
|
||||
|
||||
This decision SHALL supersede the editorial-model portion of `DEC-0029`. It SHALL preserve the parts of `DEC-0029` that define:
|
||||
|
||||
- the canonical `studio -> packer` boundary as normative for publication;
|
||||
- `TMX`/`TSX` as non-canonical supported surfaces;
|
||||
- `prometeu-packer` as compiler of the canonical request only;
|
||||
- runtime ownership of `glyph_asset_id -> slot` resolution and of the final `SCENE` payload contract.
|
||||
|
||||
## Rationale
|
||||
|
||||
The previous direction corrected the publication boundary but still modeled the editorial surface around the wrong unit. Treating layers as separate `TMX` files forced the Studio workflow to move against the natural structure of supported external editors and produced a brittle acceptance model.
|
||||
|
||||
Even revising that approach to a single `TMX` per scene would still make the external format too central. The selected direction avoids that trap by making the Studio's own scene entity the owner of editorial truth, while keeping Tiled available as an interoperability surface.
|
||||
|
||||
This preserves long-term flexibility:
|
||||
|
||||
- multiple external scene editors MAY be supported later;
|
||||
- the packer boundary remains editor-agnostic;
|
||||
- the runtime contract remains untouched;
|
||||
- editorial tooling can evolve independently of external file formats.
|
||||
|
||||
## Technical Specification
|
||||
|
||||
### 1. Canonical Scene Ownership
|
||||
|
||||
- `studio` SHALL persist and operate on a canonical scene entity owned by the Studio domain.
|
||||
- That canonical scene entity MUST be the source of truth for scene editorial state.
|
||||
- The canonical scene entity MUST NOT be conflated with a `TMX`, `TSX`, or any other editor-specific file.
|
||||
- The canonical scene entity MUST NOT be conflated with the `studio -> packer` request.
|
||||
|
||||
### 2. External Format Support
|
||||
|
||||
- `TMX` and `TSX` SHALL be treated as supported interoperability formats.
|
||||
- Studio SHALL expose import/export operations for supported formats through wizard-driven workflow.
|
||||
- `Tiled` SHALL be the initial supported option for both scene and glyph-bank interoperability.
|
||||
- Import/export MAY later support additional formats without changing the canonical publication boundary.
|
||||
|
||||
### 3. Import Semantics
|
||||
|
||||
- `import` MUST read a supported external file and project its compatible content into the canonical Studio entity.
|
||||
- `import` MUST perform minimum structural compatibility validation before mutating canonical state.
|
||||
- `import` MUST fail explicitly, with logs or diagnostics, when the external file diverges in unsupported structural ways.
|
||||
|
||||
Examples of structural divergence that MUST be treated as import failures unless explicitly supported by a later decision:
|
||||
|
||||
- unexpected new layers;
|
||||
- unexpected new tilesets;
|
||||
- unexpected structural modification of existing layers or tilesets;
|
||||
- equivalent external mutations that the Studio compatibility contract does not accept.
|
||||
|
||||
- Failed import MUST NOT silently partially rewrite canonical scene state.
|
||||
|
||||
### 4. Export Semantics
|
||||
|
||||
- `export` MUST serialize the canonical Studio entity into the selected supported format.
|
||||
- `TMX` export MUST overwrite the destination file if present, or create it if absent.
|
||||
- `TSX` export for glyph tilesets MUST overwrite the destination file if present, or create it if absent.
|
||||
- Exported files are compatibility artifacts. They MUST NOT become the canonical source of truth by virtue of existing on disk.
|
||||
|
||||
### 5. Validation Surface
|
||||
|
||||
- Validation of scene correctness SHALL target the canonical Studio scene entity.
|
||||
- `Analyse` and `Pack` SHALL be the normative validation surfaces for canonical scene integrity.
|
||||
- External files MAY be validated for import compatibility during import, but that validation does not replace canonical scene validation.
|
||||
- The old `validate layer`, `accept layer`, `validate scene from TMX`, and `accept scene from TMX` workflow MUST be removed or replaced so it no longer defines the editorial lifecycle.
|
||||
|
||||
### 6. Separation of Contracts
|
||||
|
||||
The system SHALL preserve three distinct layers of representation:
|
||||
|
||||
1. the canonical Studio-owned scene entity;
|
||||
2. the canonical `studio -> packer` scene-pack request derived from that entity;
|
||||
3. the runtime `SCENE` binary payload derived by `prometeu-packer`.
|
||||
|
||||
Normative implications:
|
||||
|
||||
- the canonical scene entity MAY evolve editorially without forcing the same shape onto the pack request;
|
||||
- the pack request MUST remain a publication projection, not the editorial persistence model;
|
||||
- packer MUST continue compiling only the canonical request, never `TMX`, `TSX`, or any other editor-native file directly.
|
||||
|
||||
### 7. Preserved Rules from DEC-0029
|
||||
|
||||
This decision intentionally preserves the following normative rules from `DEC-0029`:
|
||||
|
||||
- `TMX`/`TSX` remain supported but non-canonical;
|
||||
- the publication contract remains the canonical `studio -> packer` request;
|
||||
- `prometeu-packer` MUST NOT parse editor-specific formats directly;
|
||||
- runtime `SCENE` continues to depend on `glyph_asset_id` per layer;
|
||||
- runtime slot resolution remains runtime-owned;
|
||||
- any future change to the request shape or runtime payload contract still requires explicit decision review.
|
||||
|
||||
## Constraints
|
||||
|
||||
- This decision MUST NOT be interpreted as making Tiled deprecated or unsupported.
|
||||
- This decision MUST NOT be interpreted as collapsing the canonical Studio scene entity into the pack request.
|
||||
- This decision MUST NOT be interpreted as allowing import to accept arbitrary external edits without compatibility checks.
|
||||
- This decision MUST NOT be interpreted as preserving the old `TMX per layer` model.
|
||||
- This decision does not yet define the full canonical scene schema; that schema SHALL be specified by downstream plans and spec propagation derived from this decision.
|
||||
|
||||
## Revision Log
|
||||
|
||||
- 2026-04-30: Initial draft from AGD-0033.
|
||||
- 2026-04-30: Explicitly supersedes the editorial-model portion of DEC-0029 while preserving its canonical publication boundary.
|
||||
- 2026-04-30: Accepted and decomposed into implementation plans PLN-0062, PLN-0063, and PLN-0064.
|
||||
Reference in New Issue
Block a user