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
@@ -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.