Studio scene pack contract for runtime SCENE binary payload

This commit is contained in:
2026-05-01 06:59:42 +01:00
parent 1182d3ae1f
commit 822e892c82
61 changed files with 120404 additions and 685 deletions
@@ -97,6 +97,18 @@ Rules:
- `output.pipeline` carries tooling/build metadata kept separate at authoring time;
- codec must remain explicit and must not be hidden inside format naming.
### Scene Bank Contract Boundary
For `Scene Bank` assets, `output.format = SCENE/tilemap_v1` identifies the runtime-facing scene contract.
Rules:
- `SCENE/tilemap_v1` is a runtime/publication format, not an editor-file format;
- `TMX`, `TSX`, and other editor-specific files may exist as tooling/editorial surfaces, but they are not the canonical publication contract;
- the canonical packer input for `Scene Bank` publication is the editor-agnostic Scene Bank request emitted by Studio from canonical scene state;
- packer must not reinterpret the presence of editorial files as authorization to bypass the request boundary;
- packer must not assume any external scene file is canonical persistence, even when Studio supports that file as import/export compatibility.
### Explicit Index Collections
When `output.pipeline` carries ordered collections whose members need stable semantic identity, that identity must not depend on raw list position alone.
@@ -212,6 +212,65 @@ Rules:
- any tile in the bank may be rendered with any palette in the bank at runtime;
- palette selection is a runtime draw concern, not a tile-payload embedding concern.
## Format-Specific Baseline: `SCENE/tilemap_v1`
`SCENE/tilemap_v1` is the wave-1 Scene Bank publication format.
### Canonical Build Input
Rules:
- packer receives a canonical editor-agnostic Scene Bank request as its publication input;
- packer must not parse `TMX`, `TSX`, or other editor-specific source files directly as part of runtime scene publication;
- the request is produced by Studio from canonical scene state after canonical validation;
- equivalent requests must produce equivalent emitted `SCENE` payloads.
Baseline request shape:
```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
```
### Request Semantics
Rules:
- the request always materializes exactly `4` layer entries in wave 1;
- `tile_count` is derived from `width * height`;
- `glyph_asset_id` is the runtime-facing glyph dependency identity carried by the scene payload;
- `active` at layer scope determines whether the layer participates in emitted scene output;
- `active` at tile scope determines whether the tile contributes an active tile record to the emitted scene payload;
- `palette_id` uses a layer-owned editorial default with optional per-tile override before the request reaches packer;
- packer consumes only the resolved per-tile `palette_id` values present in the canonical request;
- request-to-binary projection should remain as close to isomorphic as possible.
### Wave-1 Constraints
Rules:
- wave 1 remains limited to exactly one logical tileset/glyph source per layer before request emission;
- packer does not own editor-format interoperability rules; it trusts the canonical request boundary once the request is structurally valid;
- binary reserved fields must not require corresponding request fields unless a later decision gives them editorial meaning.
## Determinism
Equivalent build inputs must produce equivalent outputs.
@@ -157,6 +157,25 @@ At minimum, the model should support fields equivalent to:
- `applied_actions`
- `blockers`
## Scene Bank Studio Integration Boundary
Scene Bank publication is a split workflow across Studio and packer.
Rules:
- Studio owns canonical scene validation and projection of the canonical Scene Bank request;
- packer owns compilation of the canonical Scene Bank request into runtime `SCENE` output;
- packer must report structural diagnostics against the canonical Scene Bank request artifact when that artifact is missing, malformed, or inconsistent with the locked format rules;
- packer must not report editor-file parsing diagnostics as if `TMX` or `TSX` were direct runtime build inputs.
### Request Boundary Visibility
Rules:
- the Studio-to-packer handoff for Scene Bank publication must be a canonical request artifact or equivalent request surface derived from canonical Studio scene state;
- if external compatibility files change without corresponding Studio import/update, packer must continue to treat the canonical request boundary as authoritative rather than silently reparsing editor files;
- future supported editors may replace or coexist with Tiled-backed interoperability only if Studio continues to emit the same canonical request boundary.
## Asset Event Lane
The system includes a dedicated asset workspace event/reporting lane.