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:
@@ -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.
|
||||
Reference in New Issue
Block a user