feat(pbs): add sprite animation and shared Studio authoring

Implement DEC-0084 with factory-only Sprite/Animator structs, complete result
lowering, validated animation sidecars, generated PBS factories and JavaFX/MCP
authoring through shared services.

Qualify native dev/release with ordinary and optimized producers, zero-allocation
playback, private-cycle reclamation, canonical Composer pixels, installed JARs
and JavaFX lifecycle. Preserve the runtime checkout and existing host ABI.
This commit is contained in:
2026-11-05 15:16:07 +00:00
parent 1d8b8c2101
commit bf31184d4d
151 changed files with 4823 additions and 98 deletions
@@ -0,0 +1,180 @@
# Core Sprite and Animation Specification
Status: Normative v1. Owner: compiler/pbs. Applies to Game stdlib major 1.
## Purpose and boundaries
The core provides ordinary executable PBS structs, not VM builtin animation types.
The caller owns bank loading, replacement and lifetime. Core validates structural
ranges and arithmetic; glyph existence and asset-to-slot correspondence belong to
the asset-aware caller. Sprite, internal clips and Animator store neither position
nor palette. Each frame is one glyph, and frame glyph IDs need not be contiguous.
The public API, private construction and executable result rules below are
normative. Finalized clips/frames are private and immutable after publication.
## Core API and ownership
```pbs
// @core:sprite exports Sprite, SpriteView, SpriteError and:
fn make_sprite(bank_id: int, glyph_id: int) -> result<SpriteError> Sprite;
// Sprite and SpriteView:
fn sprite() -> (bank_id: int, glyph_id: int);
// @core:animation exports Animator, AnimatorBuilder, AnimationError and:
declare enum PlaybackMode(Once = 0, Loop = 1);
declare enum PlaybackState(Stopped = 0, Playing = 1, Paused = 2, Finished = 3);
fn animator_builder(bank_id: int, initial_clip: str) -> result<AnimationError> AnimatorBuilder;
// AnimatorBuilder:
fn begin_clip(name: str, mode: PlaybackMode) -> result<AnimationError>;
fn add_frame(glyph_id: int, duration_ticks: long) -> result<AnimationError>;
fn end_clip() -> result<AnimationError>;
fn discard_clip() -> result<AnimationError>;
fn remove_clip(name: str) -> result<AnimationError>;
fn build() -> result<AnimationError> Animator;
// Animator implements SpriteView:
fn sprite() -> (bank_id: int, glyph_id: int);
fn state() -> PlaybackState;
fn active_clip() -> str;
fn clip_count() -> long;
fn frame_count(name: str) -> result<AnimationError> long;
fn frame_at(name: str, index: long) -> result<AnimationError> (glyph_id: int, duration_ticks: long);
fn select(name: str) -> result<AnimationError>;
fn play(name: str) -> result<AnimationError>;
fn pause() -> void;
fn resume() -> void;
fn stop() -> void;
fn restart() -> void;
fn advance(ticks: int) -> result<AnimationError>;
```
Factories are the public construction path. `[StdlibFactoryOnly]` restricts
positional/named `new` to the type's declaring module, using trusted stdlib origin.
Game code cannot forge that metadata or evade it by alias/reexport. Types remain
ordinary PBS structs. Completion/signature help must expose usable factories.
Admit the reserved attribute only on structs from trusted stdlib origin; it is
not a game-defined annotation. Use `declare contract` and `implements` in each
concrete type's module, preserving the existing PBS contract ownership rules.
Clip/frame types and backing never escape. Sprite and Animator implement
SpriteView with joint bank/glyph query, no new Sprite or effects per read.
Banks are int 0..255, glyphs int 0..65535, durations long 1..LONG_MAX,
LONG_MAX=9223372036854775807. Clip totals must not exceed LONG_MAX. Clip/frame
counts are long bounded by 4294967295; final clips/animator are nonempty. Frame
indices are zero-based longs. Tick input remains int; negative is an error,
zero has no effect and positive values are at most 2147483647.
SpriteError cases are invalid_bank, invalid_glyph. AnimationError cases, in order:
invalid_bank, invalid_name, duplicate_clip, clip_already_open, no_open_clip,
empty_clip, unfinished_clip, empty_animator, initial_clip_missing, unknown_clip,
invalid_glyph, invalid_duration, invalid_ticks, index_out_of_range, limit_exceeded,
overflow. Names are nonempty exact UTF-8 strings without implicit normalization.
Builder bank/initial name are fixed; it allows one open clip. end_clip rejects an
empty open clip without closing it; discard_clip discards only the open clip.
remove_clip requires none open. build checks open clip, empty collection, missing
initial in that order and produces Stopped at the initial clip's first frame.
Reuse must create private clips/frames for every animator. Builder edits leave
published animators unchanged. Only immutable strings may retain ordinary sharing.
No clone or external Clip attachment exists. Assignment preserves PBS identity.
Factories check bank ranges and required names before allocation; make_sprite also
checks glyph range. begin_clip requires no open clip and an unused, valid name;
add_frame requires an open clip and valid glyph/duration. For assembly operations,
check state preconditions before arguments, then names, ranges, counts and sums in
that order. Check `total > LONG_MAX - duration` before addition. Inspection checks
clip name before frame index. All recoverable failures preserve the prior draft
or animator, including failed end_clip, unknown remove/select/play and build after
removing the initial clip. Prepare candidate storage before publishing mutations.
### Executable result contract
Use the existing VM return group: first an Int32 status (0 for success, 1..N in
canonical error declaration order), followed by the complete typed plain-return
payload group. Preserve reference, builtin, function and trait-pair shapes and
nominal error identity in analysis/IR; matching slot counts do not establish type
identity. Unit result contains only status. Inactive error payload slots use
runtime-admitted typed defaults, including nullable reference defaults; they must
never be read as success values or require constructing payload objects.
`!` evaluates its operand once and immediately propagates the same error, filling
the enclosing function's inactive payload correctly even when its shape differs.
`handle` evaluates once and executes only the selected arm, preserving success,
local recovery and error remapping. Neither operation catches VM traps. Apply the
same group consistently to signatures, Registry metadata, imports/aliases, direct
and contract calls, branches and discarded results. Unit error paths must not use
the existing allocating default-holder helpers. Keep `Fn(...) -> TypeRef` grammar
and reject conversion of a result-effect function to plain Fn; successful Fn
payloads retain their ordinary typed representation.
### Playback contract
| Operation | State and cursor behavior |
| --- | --- |
| select(name) | From any state: Stopped at frame zero, zero phase, including the current name. |
| play(name) | From any state: Playing at frame zero, zero phase, including the current name. |
| pause() | Playing -> Paused; other states unchanged. Preserve cursor/phase. |
| resume() | Paused -> Playing; other states unchanged, including Finished. |
| stop() | From any state: Stopped/reset on selected clip. |
| restart() | From any state: Playing/reset on selected clip. |
| advance(ticks) | Reject negative in every state; zero is a no-op; positive advances only Playing. |
Check phase > LONG_MAX - ticks before addition; overflow leaves the animator
unchanged. Loop uses the remainder after dividing the new phase by total duration.
Once finishes only after consuming the last frame's full duration, retains its
image and clamps phase to total. Frame intervals are [start,end). Seek traverses
at most one clip's frame count, never each tick or each skipped loop. Failed
selection does not change anything; clips retain no suspended progress.
Use private finalized frame links with long duration/cumulative end, tail linking
to head, and direct selected clip/frame references. Prepare links before publishing
the animator. Advance and sprite must not allocate, including unit error returns;
array/optional wrappers must not be introduced on this path. All computations
precede visible state publication. VM resource/trap faults are not modeled domain
errors and carry no new rollback/safe-retry promise.
## External composition
The caller queries SpriteView and invokes
`Composer.emit_sprite(glyph_id, palette_id, x, y, layer, bank_id, flip_x, flip_y, priority) -> int`.
Preserve host identity `(composer, emit_sprite, 1)` and capability `composer`.
Composer does not depend on core Sprite/Animator. Palette applies only to the
current emission; query or emission does not advance playback.
Blitable and a draw manager are separate work. Entities, gameplay state machines,
events, ping-pong, clones, collision, multi-glyph frames and runtime animation
resources are outside this contract. There is no new opcode, host ABI, Registry
category or runtime metadata format.
## Authored factory and conformance
[Animation Authoring](../../studio/12.%20Animation%20Authoring%20Specification.md)
defines canonical JSON, binding drift, shared validation and generated sources.
Generated factories use the same builder and return effect as direct PBS code.
Factories construct fresh private clips; they never load banks or call the host.
Conformance must execute ordinary and optimized PBX with the production loader/VM
in dev/release, compare shared preview against native playback, and count executed
heap-allocation instructions for advance/sprite after construction, including
negative/overflow errors. Zero is mandatory. Resource/trap failures are not domain
errors and do not imply rollback or safe retry. A failure to establish zero
allocations requires an explicitly authorized decision revision.
Examples must call play on an action transition and advance for continuity;
calling play/select every frame resets playback every frame.
## Related specifications
See chapters 3/4 for source admission, 5/8 for module resolution/distribution,
9/10 for result/identity/lifetime and 13 for typed executable lowering.
## Native Composer status adaptation
The public Composer facade retains its existing int status and nine arguments.
The private LowComposer declaration uses the native Int64 status carrier and the
facade explicitly narrows it to int. This is a PBS adapter conversion using existing
intrinsics; host identity, capability, slot count and runtime behavior are unchanged.