RUSTICDOCSSearch documentation
DOCSENGINEAPI REFERENCEANIMATIONANIMATION.REGISTER()

Animation.register()

Animation

Compatibility

Supported languages: C, C++, C#, Python, JavaScript, Lua 5.4, Luau, Java, PHP and HTML/inline JavaScript (binding spellings and return shapes differ).

Use a compatible native engine build and the language tools required by your binding. This does not establish browser/mobile export or release qualification for every OS.

The signature below is the shared reference notation; language examples show the actual binding syntax. Question marks mark optional arguments and explicit defaults are shown where recorded. Do not copy reference notation as a typed declaration.

See Feature status and compatibility for API 1.0/1.1 and per-method restrictions. Engine release tags and Docs v0.1 are independent versions.

Signature

Animation.register(entity, clip)

Setup and usage

These engine-owned services work in Lua 5.4, Luau, JavaScript, Python, C, C++, C#, Java, PHP, and HTML inline JavaScript. Follow Use gameplay actions to create and attach a script, install external toolchains, and choose the correct language binding. PHP and HTML scripts belong under ui/; CSS alone runs no gameplay code.

The Calls section uses JavaScript signatures. The function examples below include native syntax for all ten script types, including SDK-specific alternatives and limitations. Attach a JavaScript Object Component script to the specified target and press Play. Globals are supplied by the engine. Schedule actions from Start or a callback, rather than at script top level. Native languages use typed options and their own builder conventions; see the guide's language bindings.

Parameters

ParameterMeaning
clipObject with name, positive duration, tracks and optional markers. A track contains target and keys.
keysAt least two time/value entries beginning at zero with strictly increasing times; a starting key's easing controls the following interval.
play optionsspeed (default 1), loop, blendIn/Out (seconds), blendInEase/OutEase, weight (default 1), additive, mask, layered, progressionEase.
blend optionsduration (default 0.3 seconds) and easing for the transition, plus playback options.
markerSource-clock time and event name; add before starting playback.
IK optionspole, weight, duration and easing; joints must form a direct root/middle/tip parent chain.

Return and timing

Clips lists registered names; load/register/addMarker update the engine registry. Play returns a handle with stop, speed, loop and onMarker in addition to standard controls. Value and procedural actions return operation handles; value callbacks receive the interpolated scalar/vector/quaternion.

Execution behavior

Core write timing differs between immediate Lua host calls, deferred JavaScript/Web commands and external SDK query flushes. Scheduled actions advance with the scene clock; synchronous queries evaluate at the call. Follow execution rules and the return/timing notes for this category.

Language examples

Choose one snippet at a time and place it inside your language's Start/on_start callback. These are independent examples; each creates its own handles or builders. Follow Gameplay language bindings for imports and callback registration. Python must import the modules used in its snippet from rustic; C# uses using static Rustic; Java examples belong inside a Rustic subclass; PHP callbacks declare global $rustic. HTML snippets go inside an inline script in a ui/ HTML asset.

Use an anchored Part for transform and effect examples, an unanchored collidable Part for forces, and a perspective camera named Camera for camera examples. Create Target for follow examples. Audio examples require assets/music.ogg in the Play snapshot. Replace scene paths with those listed by Game.scene.List(). Animation playback and sequence-animation examples require the Reveal fixture on the Animation page; marker callbacks also require its Halfway marker. Run clock controls separately; a paused clock cannot advance a timer.

C callback examples use these file-scope functions before on_start:

c
static void on_done(void) { rustic.log("info", "done"); }
static void on_sample(RusticValue value) { (void)value; rustic.log("info", "sample received"); }
static void on_event(const RusticValue *args, size_t count) {
    (void)args; (void)count; rustic.log("info", "event received");
}

Registers a one-second opacity clip named Reveal. Run this fixture before the playback, blend, marker and sequence-animation examples; they use Reveal on the same owner.

Lua 5.4

lua
local keys = {{time=0,value=0}, {time=1,value=1}}
local clip = {name="Reveal",duration=1,tracks={{target="Opacity",keys=keys}}}
Animation.register(rustic.entity_id(), clip)

Shared Animation constraints

  • Import glTF/GLB/FBX through Explorer and attach to the mesh entity to play skeletal clips. Source node_N descendants, inverse binds, skin weights and named clips are bound before Start. Use clips to discover actual names. Explicit load requires a fresh target.
  • Tracks target Position, Rotation, Scale, Color, Opacity, Fov or child/path/Property. C/C++ use registerClip; native facades use typed clip/key/marker records.
  • Source time is linear at selected speed unless progressionEase warps sampling. Markers use raw source time; running actions retain their clip snapshot. Blend duration stays in scene seconds when speed changes.
  • Blend/transition samples both source and destination clips. Start a base clip before a masked layer; masks match track names or hierarchy prefixes. Additive tracks apply a delta from their initial pose.
  • Turning loop off finishes the current cycle. Stop cancels without resetting the pose; completion retains the final pose unless blend-out restores the base.
  • IK solves in world space, preserves segment lengths and clamps unreachable targets. FootPlacement aliases IK; headTracking is finite lookAt, requiring controller updates for changing targets.
  • Clip limits are 4096 tracks, one million keys and 4096 markers. Add markers before playback because running actions retain their clip snapshots.
  • glTF retains linear/step/cubic-spline interpolation; FBX is baked at 60 Hz. Live renderer skinning uses four linear influences. Morph targets, dual-quaternion skinning and animation graph/editor UI are not implemented.
  • Check script attachment, enabled state and the Console when an operation fails. Asynchronous errors also appear in operation state. Callback exceptions disable the owner and clean up its actions.
  • Owner destruction, disable, successful reload or Stop cleans up owned actions and subscriptions. Failed reload retains the previous behavior's operations. See Operation handles for controls and lifetime details.

Errors and debugging

Read the constraints above and the Console diagnostic. Invalid types, non-finite values, stale targets or unavailable native services can fail validation. A failed callback disables the behavior; a failed source reload keeps the last good instance. Exact error messages depend on the language adapter. See Troubleshooting.

All animation APIs