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