Animation

Description

Plays an agent's animations. Everything sits on a playback driver, which is the only part that touches Unity's animation system. The shipped driver builds a PlayableGraph per agent, with a locomotion blend at the bottom and one layer per entry in the profile above it. See Animation Layers for how the layers are authored.

Reach an agent's animation through its applicator service:

csharp

var animation = agent.GetApplicatorService().GetAnimationService();

IAnimationService

Name	Parameters	Return Type	Description
Setup	GameObject parent, IDynamicService dynamicService = null	bool	Binds the driver to the agent and hands it to the dynamic service. False if no Animator was found.
SetCoreSet	ICoreAnimationSet set, string groupName = null	void	Replaces the idle, move and rotate clips. The group name is only for the inspector readout.
UpdateLocomotion	LocomotionState update	void	Merges the update over the held state and pushes it to the driver. Absent fields are left as they were.
GetLocomotion	N/A	LocomotionState	The merged locomotion state.
Tick	float deltaTime	void	Advances blends. Called from the agent's LateUpdate.
GetDriver	N/A	IAnimationPlaybackDriver	The driver underneath.
GetDynamicService	N/A	IDynamicService	The service that plays action sequences.
CaptureDebugState	N/A	AnimationDebugState	What is playing, for the inspector.
CaptureSnapshot	N/A	AnimationPlaybackSnapshot	Locomotion state and every layer's clip, time, weight and held flag, for saving.
RestoreSnapshot	AnimationPlaybackSnapshot snapshot	bool	Puts a snapshot back. False for null.
Dispose	N/A	void	Stops playback and destroys the graph. Called when the agent is destroyed.

LocomotionState

What the agent's legs are doing. Every field is optional, and UpdateLocomotion leaves an absent field alone, so movement, looking and the per-frame speed tick can each write only the part they own.

Field	Type	Description
Moving	bool?	Whether the agent is walking.
Speed	float?	Normalised speed, 0 to 1. Blends idle against move.
TurnRate	float?	Degrees per second, signed. Blends the rotate clip in when still.

IDynamicService

Plays a sequence of clips on a layer — an action's start, middle and end.

Name	Parameters	Return Type	Description
Setup	IAnimationPlaybackDriver driver	bool	Gives it the driver to play through.
Run	AnimationClip[] clips, LENGTH_ENFORCEMENT_MODE enforcement = FREE, bool ignorePause = false, bool holdLastPose = false	void	Plays the clips in order on the profile's first layer.
Run	AnimationClip[] clips, string layerName, LENGTH_ENFORCEMENT_MODE enforcement = FREE, bool ignorePause = false, bool holdLastPose = false	void	The same, on a named layer. An unknown name falls back to the first layer and warns once.
IsRunning	N/A	bool	Whether a sequence is still playing.
CurrentTimeLeft	N/A	float?	Seconds left in the sequence, or null when nothing is playing.
GetCurrentTime	N/A	float	Seconds since the sequence started.
Stop	N/A	void	Stops the sequence.

With holdLastPose, the layer keeps the last clip's final frame showing after the sequence ends, until something else plays on it. Without it, the layer fades back out.

IAnimationPlaybackDriver

The seam between the services above and Unity. It deals only in clips, layer names and weights. The shipped driver is PlayableAnimationDriver; AnimationService takes any driver, so a different playback scheme means a different driver and nothing else.

Name	Parameters	Return Type	Description
Bind	GameObject root	bool	Finds the Animator and builds the graph. Takes any assigned controller off and restores it on Dispose.
SetLocomotionClips	AnimationClip idle, AnimationClip move, AnimationClip rotate	void	Replaces the core clips, crossfading from the previous set.
SetLocomotion	LocomotionState state	void	Sets the idle, move and rotate weights from the state.
ResolveLayer	string layerName	AnimationLayerHandle	The layer with that name. Empty gives the first layer; unknown gives the first and warns once.
Play	AnimationLayerHandle layer, AnimationClip clip, float fadeSeconds	void	Crossfades the clip in on the layer and fades the layer up. 0 uses the layer's own fade.
Hold	AnimationLayerHandle layer	void	Freezes the layer on its current frame and keeps it up.
Release	AnimationLayerHandle layer, float fadeSeconds	void	Fades the layer out. Its clips are dropped once it reaches zero.
SetPaused	bool paused	void	Freezes every layer as it is, and lets it go again.
Tick	float deltaTime	void	Advances every fade.
CapturePlayback	AnimationPlaybackSnapshot snapshot	void	Writes each layer's state into the snapshot.
RestorePlayback	AnimationPlaybackSnapshot snapshot	void	Puts each layer back, matched by layer name and clip name.
Dispose	N/A	void	Destroys the graph.

AgentAnimationProfile

The layer stack, as a ScriptableObject. Locomotion is always the bottom layer and is not listed.

Name	Parameters	Return Type	Description
layers	N/A	AnimationLayerDefinition[]	The layers, in order from just above locomotion upwards.
LayerCount	N/A	int	How many layers.
GetLayer	int index	AnimationLayerDefinition	The layer at that position, or null.
IndexOf	string layerName	int	The layer with that name, ignoring case, or -1.

AnimationLayerDefinition

Field	Type	Description
name	string	What animation groups use to pick the layer.
mask	AvatarMask	Bones the layer drives. Null drives the whole body.
additive	bool	Add on top of the layers below rather than replace them.
weight	float	Weight the layer reaches when something is playing on it.
fadeSeconds	float	Seconds to blend the layer in and out. 0 uses Layer Blend from module settings.

AnimationDebugState

Returned by CaptureDebugState and shown in the agent inspector's Animation section.

Field	Type	Description
coreGroupName	string	The core animation group the agent is using.
weights	LocomotionWeights	Idle, move and rotate weights, which sum to one.
layers	LayerReadout[]	Per layer: name, mask, additive, weight, clip, time and held.

Related guides

• Animation Layers
• Animation Sets
• Animation Editor

---