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
@@ -329,3 +329,10 @@ The [Array owner chapter](14.%20Typed%20Arrays%20and%20Optional%20Execution%20Sp
defines the complete type, optional-flow and storage contract.
This chapter supplies shared reachability and ownership rules; Array storage
and complete-group packing are defined by that owner.
## Animation ownership and allocation
Every AnimatorBuilder.build materializes independent private clips, frames and backing. Immutable strings retain normal sharing; assignment retains ordinary identity/aliasing. Final frame links may form private cycles and must remain rooted/reclaimable under existing GC. After construction, executed advance and sprite paths allocate no heap objects, including negative/overflow error returns.
See [Core Sprite and Animation](27.%20Core%20Sprite%20and%20Animation%20Specification.md) for the complete API, ranges, state table and conformance obligations.
@@ -291,3 +291,10 @@ The [Memcard Bootstrap and SDK contract](<26. Memcard Bootstrap and SDK Specific
defines the additional [MemcardBoot] marker, exact signature, neutral once-only
bootstrap, project identity/slot validation and complete installed mem ABI.
Its requirements apply in addition to this chapter; pause/resume remain independent.
## Executable result return groups
Emit an existing typed return group: Int32 status 0 for success or canonical nominal error case index 1..N, followed by the complete plain payload group. Unit result has only status. Error payloads use admitted typed defaults, including nullable references, without constructing payload objects. Preserve typed reference/builtin/Fn/trait groups across signatures, Registry, direct/contract calls, branches and discard. Propagation fills the enclosing inactive payload and returns immediately; handle recovers locally or remaps outward. The common backend consumes neutral typed IR with no PBS branches.
See [Core Sprite and Animation](27.%20Core%20Sprite%20and%20Animation%20Specification.md) for the complete API, ranges, state table and conformance obligations.
@@ -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.
@@ -1243,3 +1243,10 @@ may accompany them. Targets MUST be nongeneric top-level userland functions;
methods, lambdas, host/interface declarations and other declaration kinds are
invalid targets. Function names are arbitrary and do not select runtime roles.
PBS exposes no sync statement, lifecycle syscall or termination marker.
## Stdlib factory-only construction
`[StdlibFactoryOnly]` is reserved metadata on trusted stdlib structs. Both positional and named `new` are permitted only in the canonical declaring module. Imports, aliases and reexports preserve this admission boundary. Game declarations cannot forge the attribute. Public construction uses the declared recoverable factories. The existing result return-effect and `Fn(...) -> TypeRef` grammar remain unchanged.
See [Core Sprite and Animation](27.%20Core%20Sprite%20and%20Animation%20Specification.md) for the complete API, ranges, state table and conformance obligations.
@@ -866,3 +866,10 @@ The [Memcard Bootstrap and SDK contract](<26. Memcard Bootstrap and SDK Specific
defines the additional [MemcardBoot] marker, exact signature, neutral once-only
bootstrap, project identity/slot validation and complete installed mem ABI.
Its requirements apply in addition to this chapter; pause/resume remain independent.
## Factory admission and typed result identity
Factory-only admission uses trusted canonical declaration origin, never visible spelling or slot count. Reject external positional/named construction and forged metadata; omit prohibited constructors from completion/signature help and expose public factories. Result error identity is nominal through imports and aliases; a result-effect function cannot be converted to plain Fn.
See [Core Sprite and Animation](27.%20Core%20Sprite%20and%20Animation%20Specification.md) for the complete API, ranges, state table and conformance obligations.
@@ -578,3 +578,10 @@ The [Memcard Bootstrap and SDK contract](<26. Memcard Bootstrap and SDK Specific
defines the additional [MemcardBoot] marker, exact signature, neutral once-only
bootstrap, project identity/slot validation and complete installed mem ABI.
Its requirements apply in addition to this chapter; pause/resume remain independent.
## Core animation and generated module resolution
Game stdlib 1 distributes executable ordinary PBS modules `@core:sprite` and `@core:animation`. Private helpers retain definition-scoped resolution and trusted origin. Reserve `generated/animations` for project-owned virtual modules `@<project>:generated/animations/b_<uuid_without_hyphens>`; physical collisions are diagnostics. Only registered build-included banks publish factories; invalid included definitions block analysis/build.
See [Core Sprite and Animation](27.%20Core%20Sprite%20and%20Animation%20Specification.md) for the complete API, ranges, state table and conformance obligations.
@@ -366,3 +366,10 @@ documents with revision-consistent text, ranges and frontend semantic context.
Hover and continued definition use that retained context. Compilation, module
admission, ABI and linking rules are unchanged. See Compiler Spec 23 §8.3 and
Studio Spec 11 for the consumer protocol and atomic write restrictions (DEC-0062).
## Executable core animation distribution
Package ordinary PBS bodies, barrels, helpers, documentation and examples for core sprite/animation in stdlib major 1. Compile these bodies through the same executable frontend path used by collections. Restrictions specific to SDK service bodies do not apply to all stdlib functions/structs. Installed consumers must not depend on a source checkout.
See [Core Sprite and Animation](27.%20Core%20Sprite%20and%20Animation%20Specification.md) for the complete API, ranges, state table and conformance obligations.
@@ -420,3 +420,10 @@ The [Memcard Bootstrap and SDK contract](<26. Memcard Bootstrap and SDK Specific
defines the additional [MemcardBoot] marker, exact signature, neutral once-only
bootstrap, project identity/slot validation and complete installed mem ABI.
Its requirements apply in addition to this chapter; pause/resume remain independent.
## Result groups and explicit animation time
A result success evaluates its payload once. Propagation and handle evaluate their operand once; only the selected recovery arm runs. Error remapping returns the enclosing error; traps are not caught. Animation advances only through explicit ticks. Queries/emissions are pure with respect to playback; repeated play/select resets the selected clip even when its name is unchanged.
See [Core Sprite and Animation](27.%20Core%20Sprite%20and%20Animation%20Specification.md) for the complete API, ranges, state table and conformance obligations.
@@ -204,3 +204,5 @@ The internal resource path is `pbs-knowledge/specs/<numbered filename>.md`;
reference clients resolve IDs through the catalog instead of constructing paths.
- [Memcard Bootstrap and SDK](<26. Memcard Bootstrap and SDK Specification.md>): opt-in persistence producer and runtime-consumer boundaries.
- [Sprite and animation contract](27.%20Core%20Sprite%20and%20Animation%20Specification.md) — core API, explicit ticks, shared bank authoring and generated factories.