Manual

Manual

The Animator

An Animator plays clips on an entity and on everything under it. This page covers the Animator component, the animator controllers that pick what it plays from your game's own data, the Animator panel where you edit them, with their states, fades, blend spaces and layers, and how your code plays clips and hears a clip's events. Clips themselves are on Animation clips.

Animator

The Animator component plays clips on what is under it. What it moves is found by the names of the entities from the Animator down, so a clip plays on any model whose bones are named alike, and an entity renamed or moved under it is found again. An Animator under another is the root of its own part: what is under it is its to move.

A model's prefab has an Animator at its root wherever the model has clips or a skin. The editor also adds one when you make a sprite from frames, or click Create in the Animation window, and you can add one to anything with Add Component.

FieldWhat it does
SpeedHow fast it plays every clip: 1 as they were made, 2 twice as fast, 0 held.
ControllerThe animator controller that picks what it plays while the game runs. Drop a .controller file from the Project panel on it, or pick one with its button. With none, your code plays its clips.
Unscaled TimePlays on real time rather than the game's: its clips and fades go on while the game is paused and ignore the game's time scale, as a pause menu's should.

Under its fields, the Inspector shows what the Animator plays: each clip, how far into it it is against its length, and whether it loops, plays once or is done. While one clip fades into another, it says how much of each is drawn.

An Animator plays on the game's clock. Its clips stand still while the game is paused, move on by a frame at each Step, and follow the game's time scale, unless Unscaled Time is ticked.

Animator controllers

An animator controller is a .controller file that says what an Animator plays and when, from your game's own data. Make one in the Project panel with Animator Controller in the + menu, or New Animator Controller in a folder's right-click menu. It makes NewController.controller, with one layer named Base, and lets you type its name. Drop it on an Animator's Controller slot to use it.

A controller is a list of states in order, each with the clip it plays and a condition saying when it may play. While the game plays, the first state whose condition holds is the one that plays, faded into from what played before. There are no arrows between states to follow: the order of the list is the priority. A state with no condition always holds, so the last state of a list is what plays when nothing above it does.

Fall     !Movement.Grounded && Movement.Speed < -2    hero › Fall
Move     Fox.Pace > 0.1                               Walk at 1, Run at 2, along Fox.Pace
Survey   (always)                                     fox › Survey

Conditions read the fields of your game's components directly, so there are no parameters to copy into the animator each frame: a system writes Fox.Pace, and the controller reads it.

Pick a controller in the Project panel and the Inspector says what it holds, with Open in Animator. Double-clicking it opens it in the Animator panel too.

The Animator panel

Open it with Window ▸ Animator (Ctrl+9). It sits beside Logs and Audio along the bottom of the default layout. It shows the controller named by the Animator of the entity picked in the Hierarchy, or a controller picked in the Project panel. Its top line names the controller and the entity it follows.

Along the top are the controller's layers as tabs, with + after them to add a layer (see Layers). Under them, the layer shown lists its states, one row each:

ColumnWhat it shows
StateA grip to drag the row, a dot lit while its condition holds, and its name
PlaysIts clip, fox › Walk, or its blend space's clips
WhenIts condition, or always for none, then to its end or at least so many seconds for a state left otherwise than as its condition fails
WeightWhile the game plays, how much of what is drawn it is

Click a row to edit the state in the Inspector. Drag a row up or down to change its place in the list, or right-click it for Duplicate, Move Up, Move Down and Delete. + State adds a state at the end, called New State, which always holds until you give it a condition.

A state under one that always holds is never reached: its name is grayed, and resting the pointer on it says which state above always holds. A condition with a mistake in it, or that reads a field your game doesn't have, is shown in red, and its state never plays.

While the game plays, the panel lights the state each layer plays, shows how much of each state is drawn as they fade, with a bar under its row, and lights the dot of every condition that holds. A state that is wanted to leave but may not yet says waits. A clip your code plays over the layer shows as a row of its own, From code, with its priority.

Every edit is written to the controller file and taken back with Ctrl+Z. The Animator reads the change at once, while the game plays too, and since the change is to the file, it stays after you stop.

States

Pick a state's row to edit it in the Inspector. Its ⋮ button has the same menu as its row.

FieldWhat it does
NameWhat fades and your code know it by. No two states of a layer can share a name.
WhenIts condition: it plays while this holds and no state above it does. Empty for always.
PlaysA clip, Blend Space 1D or Blend Space 2D
ClipThe clip it plays: a model's clip, or a clip file. Drop one on it, or pick from the list, which groups clips by the model they are for.
LeavesWhen it may be left for another state (see below)
SpeedHow fast it plays its clip, or its blend space's cycle: 1 as it was made, times the Animator's Speed

Under the state's fields, the Inspector says how the state is faded into: over the layer's fade, or the fades of the layer's list that name it.

Conditions

A condition is a short expression over your game's fields:

!Movement.Grounded && Movement.VerticalSpeed < -2
  • A field is a component's name and the field's, Movement.Speed. A field inside a struct goes on with more names, Transform.translation.y.
  • Beside fields, you can write numbers, 0.1 and -2, and true and false.
  • <, <=, > and >= compare two numbers, and == and != compare two numbers, or two that are true or false.
  • ! turns true and false round, and - makes a number negative.
  • && and || join two conditions, and brackets group them.

The operators bind as they do in C#: ! and - first, then the comparisons of order, then == and !=, then &&, then ||. A bool field is true or false, and every other field a number; the two are not mixed, so Movement.Grounded > 1 is a mistake.

A component of your game's C# is named by its own name, Movement, or by its full name, MyGame.Movement, which you need only where two components share a name. A component from Rust is named by its type's name. Each field is read on the Animator's entity first, then on its parents, the nearest that carries the component, since a character's own components are often on the entity above the model it is an instance of. A condition naming a field that no entity there carries does not hold.

As you type a condition, the Inspector checks it against your game and says what is wrong with it, or, while the game plays, whether it holds now. A list under the box suggests the components and fields you can go on with. Up and Down light another suggestion, and Tab or Enter puts the one lit in.

When a state is left

LeavesThe state may be left
As its condition failsAs soon as its condition stops holding, or one above it holds. The default.
When its clip endsOnce its clip is done, or at the end of a lap for one that loops: a landing played through.
After at leastOnce it has played at least so many seconds, which keeps a value hovering at a threshold from flickering between two states.

Until a state may be left, the list waits, and the Animator panel says so.

Fades between states

A change from one state to another fades: the new state's clip is faded in while the rest of the layer's clips fade out, each from the weight it has now, so a change in the middle of a fade starts from what is drawn. The clip faded into starts in step with the one it leaves where both have sync markers (see Sync markers). On the Animator's first frame, each layer cuts to its state rather than fading.

Pick a layer's tab to edit its fades in the Inspector:

FieldWhat it does
FadeHow long a change of its states fades, in seconds, and along what: Linear, at one pace, or Smooth, easing in and out. A new controller's is 0.25 seconds, linear.
FadesFades of their own for particular changes, each from a state, or Any state, to another, with its seconds and its curve. + Fade adds one.

A change takes the first fade in the list that names both of its states, then the first that names only where it goes, and the layer's Fade where none does.

Blend spaces

A state can play a blend space rather than one clip: several clips mixed by where one of your game's numbers falls, or two. Set Plays to one of them:

  • Blend Space 1D places its clips along one number, such as Walk at 1 and Run at 2 along Fox.Pace. Between two points, the nearer is drawn more. Before the first point, the first clip is all that plays, and past the last, the last.
  • Blend Space 2D places its clips on a plane of two numbers, such as standing still in the middle and a direction at each side for strafing. The points are joined into triangles, and a place inside one is shared among its three corners by how near it is to each. A place outside them all is taken to the nearest edge.

All of a blend space's clips play at once, each as much as its share. They are kept in step: they go through one cycle together, each at the same fraction of its own length, and the cycle takes as long as their lengths weighed by their shares, so a walk turning into a run keeps its feet together. A blend space set to leave at its end leaves as its cycle comes round.

FieldWhat it does
Along, or Along X and Along YThe number its points are placed along, a field written Component.Field, which your code writes. The Inspector checks it and suggests fields as you type.
Point 1, Point 2…Each point's clip, and where it is: one number on a line, two on a plane. The X button takes the point away.
+ PointAdds a point with no clip yet. A blend space holds up to 64.

Under its points, the Inspector draws the blend space: its points on a line or joined into triangles on a plane, where its numbers are, and a bar for each clip saying how much of it is drawn there. Drag a point to move it. Before the game plays, drag anywhere else in the picture to see the mix there; while it plays, the picture follows the numbers as they are.

Layers

A controller can have several layers, stacked with the first at the bottom. Each layer above the first is laid over the layers under it as much as its Weight, which is how a character's head can look round while its legs walk, or a flinch can play over a run.

Click + beside the tabs to add a layer above the others, called New Layer, with a weight of 1, moving every bone, with no states. Right-click a layer's tab for Move Left, Move Right and Delete. The first layer can't be moved or deleted this way, and its weight, blending and mask are not used.

FieldWhat it does
NameWhat your code names it by
WeightHow much of it is laid over the layers under it, from 0 to 1
BlendingOverride: in place of what is under it, on the bones its mask ticks. Additive: each clip's movement away from its own first frame, added on top, for a breath or a flinch.
Fade and FadesAs for the first layer: see Fades between states
Bones fromFor a layer that overrides, the model whose bones its mask is ticked on

A layer that overrides moves every bone until you give it a mask. Pick a model in Bones from, and the Inspector shows its bones as a tree, each with a tick. Ticking a bone ticks everything under it, and the Inspector counts how many bones the layer moves; the rest come from the layers under it. The mask keeps the bones by their names, so any model whose bones are named alike is masked alike.

A layer above the first lets go where none of its states holds: it fades out over its fade, and the layers under it show through.

Playing clips from code

Your code plays a clip on an Animator, with or without a controller. In a system, record it with the system's command buffer, and declare StructuralAccess.AndAnimate in its structural access. Code that runs between frames, such as a flow, calls the world.

This system, for an Animator with no controller, plays a walk while a character moves and an idle while it stands. Walker is a component of the game's own, on the Animator's entity, and the system keeps the clips' ids in a resource, loaded the first time it runs:

[StructLayout(LayoutKind.Sequential)]public struct HeroClips{    public ulong Idle;    public ulong Walk;}
// In a plugin's Build:World world = schedule.World;ResourceType<HeroClips> clips = world.RegisterResource<HeroClips>();world.InsertResource(clips);
schedule.Add("Gaits", [world.Component<Walker>().Read()], default, [clips.Write()], context =>{    ref HeroClips loaded = ref context.ResourceMut<HeroClips>(0).Value;    if (loaded.Walk == 0)    {        loaded.Idle = context.Assets.LoadClip(Addresses.Characters.Hero.Idle).Value;        loaded.Walk = context.Assets.LoadClip(Addresses.Characters.Hero.Walk).Value;    }
    foreach (Chunk chunk in context.Chunks)    {        ReadOnlySpan<Walker> walkers = chunk.GetReadOnlySpan<Walker>(0);        ReadOnlySpan<ulong> entities = chunk.Entities;        for (int at = 0; at < walkers.Length; at++)        {            ClipId wanted = new(walkers[at].Speed > 0.1f ? loaded.Walk : loaded.Idle);            context.Commands.Play(entities[at], wanted, fade: 0.3f, loop: true);        }    }}, structural: StructuralAccess.None.AndAnimate);

Play takes the Animator's entity and the clip, and three settings that may be left out:

ParameterWhat it does
fadeHow long the clip takes to come in, in seconds, from what played before; 0 cuts to it at once
looptrue to loop, false to play once; null, the default, as the clip's own Loop says
layer, priorityOn an Animator a controller runs, the layer it plays on and how much it matters (see Actions)

Playing what already plays carries it on, so a system can ask for the clip it wants every frame and only a change starts another. A clip that played once and is done starts again. A clip played on an instance whose prefab has not loaded yet plays once it has.

Stop stops every clip an Animator plays, at once. On an Animator a controller runs, it stops only what your code played, and the states take over again:

context.Commands.Stop(fox);                        // in a systemAnimatorState state = flow.World.AnimatorOf(fox);  // between frames: what it plays nowif (state.Finished) { /* the clip it played last is done */ }

AnimatorOf says what the Animator plays: each clip, how far into it, how long it is, how much of it is drawn, and whether it loops or is done, the clip played last first.

Actions

On an Animator a controller runs, a clip your code plays is an action. It plays over a layer's list of states, the first layer's unless you name another, faded in over fade while the list's clips fade out. It holds the list until it is done, or until you stop it, and then the list takes over again; on a layer above the first where no state holds, the layer lets go instead.

One action plays on a layer at a time. Another played on that layer takes its place, unless the one playing has a higher priority, when the new one is refused. That way a flinch interrupts an attack only when it should. On a layer that adds, the clip's movement since its own first frame is laid on top.

// Between frames, as in a flow:AnimationAction swing = world.Play(hero, attack, fade: 0.1f, layer: "Upper", priority: 5);ActionState now = world.StateOf(swing);                     // Playing, Played, Stopped, Replaced, Refused
// In a system:context.Commands.Play(hero, flinch, layer: "Upper", priority: 1);   // refused while the attack playscontext.Commands.Stop(hero, "Upper");                               // what code played on Upper; null for every layer

In a flow, Play waits for the action to end. It returns true when the clip played to its end, and false when it was stopped, replaced or refused. A clip that loops ends only when it is stopped or replaced.

schedule.AddFlow("Attack", async flow =>{    if (await flow.Play(hero, attack, layer: "Upper", priority: 5))    {        // the swing played through    }});

flow.Ended(action) waits the same way for an action played with world.Play. A layer the controller doesn't have plays the action on the first layer, and the log says so once.

Layer weights from code

Your code can set a layer's weight in place of the file's, fading there over a time. It stays until the game stops.

context.Commands.SetLayerWeight(fox, "Look", 0f, fade: 0.4f);   // in a systemworld.SetLayerWeight(fox, "Look", 1f, fade: 0.4f);              // between frames

To see what a controller is doing, world.LayersOf(entity) gives each layer as it runs: the state it plays, how much of it is laid over the layers under it, the action playing over it and its priority, and for each state its weight, whether its condition holds and, for a blend space, each clip's share.

IReadOnlyList<LayerRun> layers = world.LayersOf(fox);float laid = layers[1].Weight;                             // how much of the second layer is laid overIReadOnlyList<float> mix = layers[0].States[0].Shares;     // a blend space's clips, each one's share

Animation events in code

An event is a struct of your game's marked [AnimationEvent], placed on a clip's timeline with Event (see Events). It is declared as a component is, and must be partial. Its fields are shown on the timeline as [Range], [Tooltip] and [HideInInspector] say.

[AnimationEvent][StructLayout(LayoutKind.Sequential)]public partial struct Footstep{    [Range(0, 1)] public int Foot;            // 0 the left, 1 the right    [Range(0f, 1f)] public float Volume;}

A system reads the events that clips fired on the last frame, on every Animator, in the order they fired. Each is a Fired<T>: the Animator's entity, the clip, the event's time on the clip, how much of what was drawn the clip was, and the struct with its fields as the timeline set them.

foreach (Fired<Footstep> step in context.Events<Footstep>()){    if (step.Event.Foot == 0) { /* step.Animator put its left foot down */ }}

A flow can wait for the next event on one Animator:

Fired<Footstep> next = await flow.AnimationEvent<Footstep>(fox);

[AnimationEvent(Name = "Step")] gives the struct the name clips know it by, the type's name if you leave it out.

The controller file

A controller is JSON, so it reads well in version control. What the file leaves out starts as the editor starts it: a fade of a quarter of a second, linear, a speed of 1, leaving as the condition fails, and a layer of weight 1 overriding every bone.

{
  "abyssController": 3,
  "layers": [
    {
      "name": "Base",
      "fade": 0.4,
      "fades": [ { "to": "Move", "seconds": 0.4 } ],
      "states": [
        {
          "name": "Move",
          "when": "Fox.Pace > 0.1",
          "blend": {
            "along": "Fox.Pace",
            "points": [
              { "clip": "models/fox/fox.glb#Walk", "model": "fba788ef5f244de79da49a4380a06761", "at": 1 },
              { "clip": "models/fox/fox.glb#Run", "model": "fba788ef5f244de79da49a4380a06761", "at": 2 }
            ]
          }
        },
        { "name": "Survey", "clip": "models/fox/fox.glb#Survey", "model": "fba788ef5f244de79da49a4380a06761" }
      ]
    },
    {
      "name": "Look",
      "mask": { "from": "models/fox/fox.glb", "model": "fba788ef5f244de79da49a4380a06761", "bones": ["b_Neck_04", "b_Head_05"] },
      "states": [ { "name": "Survey", "when": "Fox.Looks", "clip": "models/fox/fox.glb#Survey", "model": "fba788ef5f244de79da49a4380a06761" } ]
    }
  ]
}

Each clip is named by its model's path and the clip's name, and by the model's identity under model, so a model you move or rename is still found. A built game reads each controller packed, with the models and clip files its states play.

In the Scripting API