implements PLN-0040 scene glyph spec and wire layout
This commit is contained in:
@@ -579,7 +579,7 @@ Fault boundary:
|
||||
| `gfx.draw_square` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.draw_text` | `void` | no real operational failure path in v1 |
|
||||
| `gfx.clear_565` | `void` | no real operational failure path in v1 |
|
||||
| `composer.bind_scene` | `status:int` | explicit orchestration-domain operational result |
|
||||
| `composer.bind_scene` | `status:int` | status-returning API, but missing scene glyph dependencies are fatal runtime errors |
|
||||
| `composer.unbind_scene` | `status:int` | explicit orchestration-domain operational result |
|
||||
| `composer.set_camera` | `void` | no real operational failure path in v1 |
|
||||
| `composer.emit_sprite` | `status:int` | explicit orchestration-domain operational rejection |
|
||||
@@ -596,6 +596,18 @@ The public `gfx.*` primitive family remains valid in v1, but its stable operatio
|
||||
|
||||
This means callers MUST NOT rely on stable immediate writes to the working back buffer as the public contract for `gfx.draw_text(...)` or sibling primitives.
|
||||
|
||||
### 19.1.b Scene dependency fatal boundary
|
||||
|
||||
`composer.bind_scene` remains a status-returning syscall in the public ABI, but scene glyph dependency absence is outside the accepted passive operational-error model.
|
||||
|
||||
Rules:
|
||||
|
||||
- the target scene slot may still be rejected through ordinary status-returning behavior when the scene itself is unavailable;
|
||||
- missing glyph dependencies referenced by a resident scene are not a passive `status:int` case;
|
||||
- if scene activation discovers that a layer dependency cannot be resolved to a committed glyph asset, the machine MUST fail fatally and emit a clear log;
|
||||
- if scene composition later discovers that a layer dependency can no longer be resolved, the machine MUST fail fatally and emit a clear log;
|
||||
- runtime MUST NOT continue canonical scene composition after such a dependency failure.
|
||||
|
||||
### 19.2 `composer.emit_sprite`
|
||||
|
||||
`composer.emit_sprite` returns `status:int`.
|
||||
|
||||
@@ -108,9 +108,9 @@ This table describes content identity and storage layout, not live residency.
|
||||
|
||||
`codec` does not define the bank-specific serialized layout itself. Specialized banks may still have normative decode rules even when `codec = NONE`.
|
||||
|
||||
### 4.1 `TILES` asset contract in v1
|
||||
### 4.1 `GLYPH` asset contract in v1
|
||||
|
||||
For `BankType::TILES`, the v1 runtime-facing contract is:
|
||||
For `BankType::GLYPH`, the v1 runtime-facing contract is:
|
||||
|
||||
- `codec = NONE`
|
||||
- serialized pixels use packed `u4` palette indices
|
||||
@@ -118,20 +118,20 @@ For `BankType::TILES`, the v1 runtime-facing contract is:
|
||||
- `palette_count = 64`
|
||||
- runtime materialization may expand pixel indices to one `u8` per pixel
|
||||
|
||||
For `TILES`, `NONE` means there is no additional generic codec layer beyond the bank contract itself.
|
||||
For `GLYPH`, `NONE` means there is no additional generic codec layer beyond the bank contract itself.
|
||||
|
||||
For the current transition window:
|
||||
|
||||
- `RAW` is a legacy deprecated alias of `NONE`
|
||||
- newly published material must use `NONE` as the canonical value
|
||||
|
||||
Even with `codec = NONE`, `TILES` still requires bank-specific decode from its serialized payload. The serialized byte layout therefore does not need to match the in-memory layout.
|
||||
Even with `codec = NONE`, `GLYPH` still requires bank-specific decode from its serialized payload. The serialized byte layout therefore does not need to match the in-memory layout.
|
||||
|
||||
#### 4.1.1 Metadata Normalization
|
||||
|
||||
Following `DEC-0004`, the `AssetEntry.metadata` field must be structured in segmented form to avoid ambiguity.
|
||||
|
||||
Required effective metadata fields for `TILES` at the root level:
|
||||
Required effective metadata fields for `GLYPH` at the root level:
|
||||
|
||||
- `tile_size`: tile edge in pixels; valid values are `8`, `16`, or `32`
|
||||
- `width`: total sheet width in pixels
|
||||
@@ -143,7 +143,7 @@ Optional informative subtrees:
|
||||
- `metadata.codec`: codec/compressor-specific configuration (for example dictionaries or compression flags).
|
||||
- `metadata.pipeline`: informative metadata from the Studio build process (for example source hashes, timestamps, or tool versions).
|
||||
|
||||
Validation rules for `TILES` v1:
|
||||
Validation rules for `GLYPH` v1:
|
||||
|
||||
- `palette_count` must be `64`
|
||||
- `width * height` defines the number of logical indexed pixels in the decoded sheet
|
||||
@@ -160,17 +160,74 @@ The tile-bank payload therefore separates serialized storage form from runtime m
|
||||
- decoded pixel plane: expanded `u8` indices, one entry per pixel
|
||||
- palette table: `64 * 16` colors in `RGB565`
|
||||
|
||||
For `TILES` v1:
|
||||
For `GLYPH` v1:
|
||||
|
||||
- `size` must match `ceil(width * height / 2) + (palette_count * 16 * 2)`
|
||||
- `decoded_size` must match `(width * height) + (palette_count * 16 * 2)`
|
||||
|
||||
### 4.2 `SCENE` asset contract in v1
|
||||
|
||||
For `BankType::SCENE`, the v1 runtime-facing contract is:
|
||||
|
||||
- `codec = NONE`
|
||||
- payload magic is `SCNE`
|
||||
- payload version is `1`
|
||||
- layer count is fixed at `4`
|
||||
- each layer carries its own glyph dependency
|
||||
- the glyph dependency is serialized as canonical `AssetId` using signed 32-bit little-endian width
|
||||
- the payload MUST describe cold asset dependencies only and MUST NOT encode runtime glyph slot topology
|
||||
|
||||
Even with `codec = NONE`, `SCENE` still has a bank-specific binary contract. The serialized layout is normative and distinct from any transient runtime residency state.
|
||||
|
||||
#### 4.2.1 Layer Header Layout
|
||||
|
||||
Each scene layer header is:
|
||||
|
||||
1. `flags: u8`
|
||||
2. `glyph_asset_id: i32` (little-endian)
|
||||
3. `tile_size: u8`
|
||||
4. `reserved: u16`
|
||||
5. `parallax_x: f32`
|
||||
6. `parallax_y: f32`
|
||||
7. `width: u32`
|
||||
8. `height: u32`
|
||||
9. `tile_count: u32`
|
||||
10. `reserved: u32`
|
||||
|
||||
This makes the canonical per-layer header size `32` bytes.
|
||||
|
||||
Normative rules:
|
||||
|
||||
- `glyph_asset_id` MUST be interpreted as the cold identity of the glyph dependency for that layer;
|
||||
- `glyph_asset_id` MUST NOT be interpreted as a runtime slot id;
|
||||
- each layer MUST own exactly one glyph dependency reference;
|
||||
- no shared dependency table exists in this contract;
|
||||
- `tile_count` MUST equal `width * height`.
|
||||
|
||||
#### 4.2.2 Runtime Binding Semantics
|
||||
|
||||
`SCENE` assets do not own runtime residency.
|
||||
|
||||
Therefore:
|
||||
|
||||
- the runtime MUST resolve scene glyph dependencies through runtime-owned residency state;
|
||||
- the runtime MUST maintain a runtime-owned mapping from committed glyph `AssetId` to glyph slot;
|
||||
- scene bind and scene draw MUST consult runtime residency, not serialized slot topology;
|
||||
- a missing scene glyph dependency is not a passive asset-status condition.
|
||||
|
||||
If a scene glyph dependency cannot be resolved:
|
||||
|
||||
- `bind_scene` MUST fail as a fatal machine error with clear logging;
|
||||
- draw/composition MUST fail as a fatal machine error with clear logging;
|
||||
- runtime MUST NOT continue scene composition after the missing dependency is detected.
|
||||
|
||||
## 5 Banks and Slots
|
||||
|
||||
The current runtime exposes bank types:
|
||||
|
||||
- `GLYPH`
|
||||
- `SOUNDS`
|
||||
- `SCENE`
|
||||
|
||||
Assets are loaded into explicit slots identified by slot index at the public ABI boundary.
|
||||
|
||||
|
||||
@@ -229,6 +229,12 @@ For mutating composer operations:
|
||||
- `set_camera` remains `void` in v1;
|
||||
- no caller-provided sprite index or `active` flag is part of the canonical contract.
|
||||
|
||||
Fatal boundary clarification for `bind_scene`:
|
||||
|
||||
- `bind_scene` remains status-returning for ordinary orchestration-domain rejection such as unresolved target scene slot;
|
||||
- missing glyph dependencies inside a resident scene are not accepted as passive `ComposerOpStatus` outcomes;
|
||||
- if scene activation or later composition detects an unresolved scene glyph dependency, runtime MUST escalate that condition as a fatal machine error with clear logging.
|
||||
|
||||
## 7 Syscalls as Callable Entities (Not First-Class)
|
||||
|
||||
Syscalls behave like call sites, not like first-class guest values.
|
||||
|
||||
Reference in New Issue
Block a user