Plush

AnimationPlayback#

PlushEngine · Type index

Namespace: PlushEngine.Animation (using PlushEngine.Animation;)

Occurrence-owned base loop and full-body one-shot. No root-motion extraction or physics authority. CPU skinning is the first measured proof backend; shared source geometry is never modified.

public sealed class AnimationPlayback

Usage and examples

General: BaseClip · BeginDrivenOneShot · Clips · Duration · Enter · Garments · GetSocketWorldTransform · IsDrivenOneShot · IsPlayingOneShot · Loop · OneShotClip · OneShotTime · Play · PlayOneShot · SampleDrivenOneShot · Seek · StopOneShot

Blend: ActiveBlendId · Blend1D · Blend2D · BlendPhase · BlendValue · BlendValue2D · IsBlending1D · IsBlending2D · SeekBlend1D · SeekBlend2D · SetFloat

Ik: AddIkChain · ClearIk · GetIkAnimatedEnd · GetIkAnimatedEndRotation · GetIkAnimatedMid · GetIkEnd · GetNodeWorldPosition · SetIk · SetIkEndRotation · SetNodeOffset · SetNodeWorldRotation

Inertialization: InertializationSeconds · Inertialize · InertializeTransitions · IsInertializing

Layers: GetLayerWeight · IsLayerPlaying · LoopLayer · PlayLayerOneShot · SeekLayer · SetLayerWeight · StopLayer

Matching: BaseTime · IsMatchingMotion · MatchMotion · MotionFrameCount · MotionMatchCost · MotionSwitchCount · StopMatching

General#

BaseClip#

public string? BaseClip { get; }

BeginDrivenOneShot#

public bool BeginDrivenOneShot(AnimationClipReference clip, float fadeSeconds = 0);

Start an externally clocked full-body one-shot. Returns false if a shot already owns playback. Automatic advancement is suspended until StopOneShot; the caller supplies samples. Optional fadeSeconds captures the visible pose and fades on runtime time independently of sample time. This grants no physics authority or jump, wall, root bone or axis convention.

Clips#

public IReadOnlyList<AnimationClipInfo> Clips { get; }

Duration#

public float Duration(AnimationClipReference clip);

How long a clip plays once at normal speed, in seconds: Entity.Animation.Duration(Attack).

Enter#

public bool Enter(string entry, float fadeSeconds = .15f);

Plays the state a named entry point of the controller leads to, the way Play would. Entry points are named in the controller's graph.

Garments#

public GarmentSimulation? Garments { get; }

Realtime cloth for the mesh's garments, or null when the mesh carries no garment data.

GetSocketWorldTransform#

public Matrix4x4 GetSocketWorldTransform(string socket);

Current final posed anchor, including socket offset and character world transform.

IsDrivenOneShot#

public bool IsDrivenOneShot { get; }

IsPlayingOneShot#

public bool IsPlayingOneShot { get; }

Loop#

public void Loop(AnimationClipReference clip);
public void Loop(string clip);

Start/restart a looping clip. A zero-duration pose can be selected and remains held.

OneShotClip#

public string? OneShotClip { get; }

OneShotTime#

public float OneShotTime { get; }

Play#

public bool Play(AnimationClipReference state, float fadeSeconds = .15f);

Plays a state the way it is set up: looping states loop as the base animation; others play once over it. Returns false only when a one-shot is refused because another is still playing.

PlayOneShot#

public bool PlayOneShot(AnimationClipReference clip, float fadeSeconds = .15f, float startSeconds = 0);
public bool PlayOneShot(string clip, float fadeSeconds = .15f, float startSeconds = 0);

Play once, fading from/to the advancing base loop. Repeated triggers during a shot are ignored (returns false). No callbacks survive destruction; poll IsPlayingOneShot for this first slice.

SampleDrivenOneShot#

public void SampleDrivenOneShot(float time, Vector3 correction);

Sample an externally clocked shot in seconds (clamped to the clip end). Correction is a translation in imported source space, applied once to scene roots before skinning and mesh centering. It does not move the occurrence. StopOneShot releases playback ownership.

Seek#

public void Seek(float seconds);

Seek the base clip without advancing gameplay; also usable by editor previews.

StopOneShot#

public void StopOneShot();

Stop the overlay immediately and return to the base pose.

public void StopOneShot(float fadeSeconds);

Release the current overlay into advancing locomotion, retaining the visible pose for a bounded crossfade. Zero retains immediate-stop behavior.

Blend#

ActiveBlendId#

public string? ActiveBlendId { get; }

Blend1D#

public void Blend1D(float value);

Select the authored 1D base blend or update its parameter without resetting phase. This disables matching, preserves one-shots, and does not extract root motion or move physics.

public void Blend1D(string idOrName);
public void Blend1D(string idOrName, float value);

Select an authored named 1D blend by stable ID or unique name. Switching resets phase; updating the same blend preserves it. One-shots remain independent. No implicit cross-fade.

Blend2D#

public void Blend2D(Vector2 value);

Select/update the authored Cartesian base blend. Values are parameter coordinates, not world directions. Phase persists across updates, and one-shots remain independent.

BlendPhase#

public float BlendPhase { get; }

BlendValue#

public float BlendValue { get; }

BlendValue2D#

public Vector2 BlendValue2D { get; }

IsBlending1D#

public bool IsBlending1D { get; }

IsBlending2D#

public bool IsBlending2D { get; }

SeekBlend1D#

public void SeekBlend1D(float phase);

Preview a normalized cycle position [0,1]. Does not change authored data.

SeekBlend2D#

public void SeekBlend2D(float phase);

SetFloat#

public void SetFloat(string parameter, float value);

Update the active blend's named parameter. Unknown names or inactive blends are errors.

Ik#

Procedural IK on top of the evaluated pose: two-bone chains (leg or arm, with optional twist nodes between) and world-space node offsets (pelvis drop). Mechanism only: scripts decide targets, weights and when IK applies (ground probing, foot planting, contact policy are project code). Nodes are exact hierarchy paths, resolved once. Targets are world space and persist until changed or cleared; an active ragdoll disables IK. Twist nodes between the chain bones keep their local pose. The pre-IK animated pose is readable for probing and planting.

AddIkChain#

public int AddIkChain(string upperPath, string midPath, string endPath);

Register a two-bone chain by exact hierarchy paths (mid must descend from upper, end from mid). Returns its handle.

ClearIk#

public void ClearIk(int chain);

GetIkAnimatedEnd#

public Vector3 GetIkAnimatedEnd(int chain);

Animated (pre-IK, pre-offset) world position of a chain's end as of the last evaluation. Valid after the first evaluation.

GetIkAnimatedEndRotation#

public Quaternion GetIkAnimatedEndRotation(int chain);

GetIkAnimatedMid#

public Vector3 GetIkAnimatedMid(int chain);

GetIkEnd#

public Vector3 GetIkEnd(int chain);

World position of the end after IK (equals the animated end when the chain is inactive).

GetNodeWorldPosition#

public Vector3 GetNodeWorldPosition(string path);

World position of a node as of the last evaluation (after IK). Paths resolve once and are cached.

SetIk#

public void SetIk(int chain, Vector3 endWorld, float weight, Vector3? poleWorld = null);

Reach the end node toward a world position. weight 0 leaves the animation untouched. The optional pole is a world point the bend (knee/elbow) turns toward; by default the animated bend direction is kept.

SetIkEndRotation#

public void SetIkEndRotation(int chain, Quaternion worldRotation, float weight);

Orient the end node (foot/hand) to a world rotation at the given weight; weight 0 keeps the animated orientation.

SetNodeOffset#

public void SetNodeOffset(string path, Vector3 worldOffset);

Translate a node (e.g. the pelvis) by a world-space offset after animation and before IK. Zero removes it.

SetNodeWorldRotation#

public void SetNodeWorldRotation(string path, Quaternion worldDelta, float weight);

Rotate a node (and so its descendants) by a world-space delta about its own origin, scaled by weight (0 removes it). Applied top-down in hierarchy order after offsets and before IK, so a spine can be split into fractions of one aim rotation.

Inertialization#

Inertialized transitions: at a pose discontinuity (one-shot start/end, release, clip or blend switch) the visible pose is kept and the difference to the new target pose decays as a critically damped spring whose start velocity matches the visible motion, so neither position nor velocity pops and no frozen pose is blended in. Opt-in per playback (InertializeTransitions); when off, the authored crossfades are unchanged. Layers, ragdoll and matching own their own blending. Scale is not offset.

InertializationSeconds#

public float InertializationSeconds { get; set; }

Settle time for hard cuts (Loop and blend switches) that carry no fade of their own.

Inertialize#

public void Inertialize(float seconds);

Scripts may declare that a cut is about to happen (before changing pose state). Requires InertializeTransitions; otherwise ignored.

InertializeTransitions#

public bool InertializeTransitions { get; set; }

When true, one-shot fades and releases (and clip/blend switches) use inertialization instead of pose crossfades. The fade argument of those calls becomes the settle time.

IsInertializing#

public bool IsInertializing { get; }

Layers#

GetLayerWeight#

public float GetLayerWeight(string layer);

Current authored weight of a layer (before its fade envelope).

IsLayerPlaying#

public bool IsLayerPlaying(string layer);

LoopLayer#

public void LoopLayer(string layer, AnimationClipReference clip, float fadeSeconds = .15f);

Start/restart a looping authored layer (override or additive). Zero-duration clips hold a pose.

PlayLayerOneShot#

public bool PlayLayerOneShot(string layer, AnimationClipReference clip, float fadeSeconds = .15f);

Play a masked one-shot. Returns false while this layer is occupied; other layers/base continue.

SeekLayer#

public void SeekLayer(string name, float seconds);

Scrub an active layer in seconds, clamped to its clip. Uses full envelope for inspection.

SetLayerWeight#

public void SetLayerWeight(string layer, float weight);

StopLayer#

public void StopLayer(string name, float fadeSeconds = .15f);

Release the current layer into the advancing lower stack. Repeated stops do not restart fading.

Matching#

BaseTime#

public float BaseTime { get; }

IsMatchingMotion#

public bool IsMatchingMotion { get; }

MatchMotion#

public void MatchMotion(Vector3 desiredVelocity, Vector3 actualVelocity, Vector3 desiredFacing, AnimationClipReference? clipConstraint = null);

Supply persistent world-space desired/solved velocity and facing. Matching controls the visual pose only. Uniform visual scale is accounted for; physics retains world placement. Optional clipConstraint selects a matching slot explicitly (for example a game's idle policy). Null restores unconstrained search; the engine does not infer idle from the default clip.

MotionFrameCount#

public int MotionFrameCount { get; }

MotionMatchCost#

public float MotionMatchCost { get; }

MotionSwitchCount#

public int MotionSwitchCount { get; }

StopMatching#

public void StopMatching();

AnimationClipInfo · AnimationClipReference · GarmentSimulation

Source#