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
@@ -221,7 +221,8 @@ let status: int = Composer.emit_sprite(7, 0, 12, 18, 0, 2, false, false, 1);
Rules:
- `@sdk:composer` is the canonical sprite-composition module in this wave.
- `@sdk:composer` is the canonical frame-composition module in this wave.
- `Composer.bind_scene(...)`, `Composer.unbind_scene()`, and `Composer.emit_sprite(...)` belong to that module.
- `@sdk:gfx` remains valid for primitive and overlay-oriented graphics operations.
- `Gfx.set_sprite` is not part of the active stdlib line `1` contract.
@@ -141,6 +141,14 @@ For example, the PBS-facing declaration:
```pbs
declare host LowComposer {
[Host(module = "composer", name = "bind_scene", version = 1)]
[Capability(name = "gfx")]
fn bind_scene(scene_bank_id: int) -> int;
[Host(module = "composer", name = "unbind_scene", version = 1)]
[Capability(name = "gfx")]
fn unbind_scene() -> int;
[Host(module = "composer", name = "emit_sprite", version = 1)]
[Capability(name = "gfx")]
fn emit_sprite(
@@ -160,6 +168,8 @@ declare host LowComposer {
maps to the canonical runtime identity:
```text
("composer", "bind_scene", 1)
("composer", "unbind_scene", 1)
("composer", "emit_sprite", 1)
```
@@ -254,6 +254,8 @@ Rules:
- stdlib line `1` MUST expose the sprite-composition interface module at `@sdk:composer`,
- that module MUST declare `LowComposer` and public service `Composer`,
- that module MUST use runtime module `composer` and capability `gfx`,
- that module MUST expose `bind_scene(scene_bank_id: int) -> int`,
- that module MUST expose `unbind_scene() -> int`,
- that module MUST expose `emit_sprite(glyph_id: int, palette_id: int, x: int, y: int, layer: int, bank_id: int, flip_x: bool, flip_y: bool, priority: int) -> int`,
- stdlib line `1` MUST NOT expose `Gfx.set_sprite`,
- stdlib line `1` MUST expose the low-level asset interface module at `@sdk:asset`,
@@ -172,11 +172,15 @@ Rules:
- `@sdk:composer` MUST expose a low-level host owner `LowComposer`.
- `@sdk:composer` MUST expose a public service facade `Composer`.
- `Composer.bind_scene(scene_bank_id: int)` MUST lower through canonical host identity `("composer", "bind_scene", 1)`.
- `Composer.unbind_scene()` MUST lower through canonical host identity `("composer", "unbind_scene", 1)`.
- `Composer.emit_sprite(...)` MUST lower through canonical host identity `("composer", "emit_sprite", 1)`.
- `Composer.bind_scene(...)` MUST return a raw `int` in stdlib line `1`.
- `Composer.unbind_scene()` MUST return a raw `int` in stdlib line `1`.
- `Composer.emit_sprite(...)` MUST return a raw `int` in this wave.
- `@sdk:gfx` MAY continue to expose primitive and overlay-oriented operations.
- `@sdk:gfx` MUST NOT expose `set_sprite`.
- `bind_scene`, `unbind_scene`, and `set_camera` are deferred and are not required members of `@sdk:composer` in this wave.
- `set_camera` may remain deferred if not yet exposed by the active stdlib line.
## 13. Stdlib Contract Expectations for Builtin MVP
@@ -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.
@@ -258,6 +258,101 @@ Rules:
- Primary actions for unregistered assets include `Register`.
- `Register` is a direct action in Studio UX. If registration is valid, clicking it must register immediately without an extra acknowledgement step.
- If registration is blocked, Studio may surface the blocking preview inline so the user can inspect why registration cannot proceed.
## Scene Bank Editorial and Publication Rules
`Scene Bank` is an asset-owned workflow inside `Assets`.
Rules:
- `Scene Bank` authoring, diagnostics, canonical validation, and external-format interoperability are owned by the `Assets` workspace;
- the primary editorial surface for `Scene Bank` is a Studio-owned canonical scene entity;
- wave-1 `TMX` and `TSX` integration is a supported import/export compatibility surface, not the canonical asset model and not the canonical publication contract;
- supported external formats may be replaced or coexist with other editors in the future only if Studio continues to materialize the same canonical Scene Bank publication request from canonical scene state;
- `Assets` must not treat Tiled files as the canonical asset model by accident.
### Scene Bank Ownership Boundary
The `Assets` workspace owns the editorial side of `Scene Bank` publication.
Rules:
- Studio owns the canonical Scene Bank scene entity and its editorial persistence;
- Studio owns layer enablement, dimensions, linked glyph/tileset asset binding, layer default palette data, layer parallax data, and equivalent scene-owned editorial state;
- Studio owns import from supported external formats into canonical scene state;
- Studio owns export from canonical scene state into supported external formats;
- Studio owns projection from canonical scene state into the canonical publication request;
- packer owns only compilation of that canonical request into runtime `SCENE` bytes.
### Canonical Publication Request
The canonical publication contract from Studio to packer is the Scene Bank request.
Baseline 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
```
Rules:
- the request is derived from canonical scene state, not from editor-native files directly;
- the request must remain editor-agnostic and must not embed `TMX`, `TSX`, or other editor-specific source structures as the publication contract;
- wave 1 materializes exactly `4` layer entries;
- `tile_count` is derived from `width * height`;
- request fields reserved only for binary layout must not be surfaced unless they gain explicit editorial meaning.
### Scene Bank Editorial Mapping Rules
Rules:
- `glyph_asset_id` is derived from the glyph asset selected for the layer;
- `parallax_factor_x` and `parallax_factor_y` are layer-owned editorial fields in Studio;
- `palette_id` has a layer-owned default and may be overridden per tile when the supported editorial surface provides an explicit override;
- layer `active` determines whether the layer participates in publication output;
- tile `active` determines whether the tile contributes an active tile record to the published request;
- canonical scene persistence must not depend on `TMX`, `TSX`, or any other external file format remaining present on disk.
### External Format Interoperability Rules
Rules:
- Studio must expose supported scene and glyph-bank interoperability through explicit import/export workflow;
- wave-1 Tiled interoperability consists of `TMX (Tiled)` scene import/export and `TSX (Tiled)` glyph tileset export;
- scene import must validate minimum structural compatibility before mutating canonical scene state;
- scene import must fail explicitly, with logs or diagnostics, when an external file contains unsupported structural divergence such as unexpected layers, unexpected tilesets, or equivalent unsupported mutations;
- failed scene import must not silently partially rewrite canonical scene state;
- scene `TMX` export must overwrite the destination file if present, or create it if absent;
- glyph tileset `TSX` export must overwrite the destination file if present, or create it if absent;
- exported external files are compatibility artifacts and must not become the canonical source of truth.
### Canonical Validation Rules
Rules:
- publication-ready Scene Bank state requires absence of blocking diagnostics against canonical scene state;
- Studio must validate canonical scene state during `Analyse` and/or `Pack`;
- Studio may validate external files 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 not define Scene Bank readiness.
- Sensitive actions such as `Exclude From Build`, `Remove`, and `Relocate` must be visually separated from routine actions.
- Sensitive actions must not look interchangeable with routine actions.
- `Relocate` must collect an explicit user-chosen destination root before the staged preview is generated.