PR002: implement gfx status-first contract for set_sprite
This commit is contained in:
@@ -511,3 +511,32 @@ The system can measure:
|
||||
- `palettes_referenced_this_frame`
|
||||
- `tiles_drawn_by_palette_id`
|
||||
- `sprites_drawn_by_palette_id`
|
||||
|
||||
---
|
||||
|
||||
## 19. Syscall Return and Fault Policy
|
||||
|
||||
`gfx` follows status-first policy for operations with operational failure modes.
|
||||
|
||||
Fault boundary:
|
||||
|
||||
- `Trap`: structural ABI misuse (type/arity/capability/shape mismatch);
|
||||
- `status`: operational failure;
|
||||
- `Panic`: internal runtime invariant break only.
|
||||
|
||||
### 19.1 `gfx.set_sprite`
|
||||
|
||||
`gfx.set_sprite` returns `status:int`.
|
||||
|
||||
Minimum status table:
|
||||
|
||||
- `0` = `OK`
|
||||
- `1` = `ASSET_NOT_FOUND`
|
||||
- `2` = `INVALID_SPRITE_INDEX`
|
||||
- `3` = `INVALID_ARG_RANGE`
|
||||
|
||||
Operational notes:
|
||||
|
||||
- no fallback to default bank when the sprite asset name cannot be resolved;
|
||||
- no silent no-op for invalid index/range;
|
||||
- `palette_id` and `priority` must be validated against runtime-supported ranges.
|
||||
|
||||
Reference in New Issue
Block a user