flutter3d
Showcase Changelog 62 packages API reference

An animation graph

since 1.0.0-rc.1 Animation

Playing one clip at a time by hand works until a character has more than two things to do. Then every game ends up writing the same code: which clip now, how long to fade, what to do when an attack is pressed halfway through a swing. An AnimationGraph holds those answers as data. It runs an AnimationStateMachine over a model's own clips, one step at a time, into a Pose that is then written onto the model.

This page drives the robot that ships with the samples. It stands, walks, runs and slows again on its own, and the controls let you set the speed, lay a wave over its right arm, let its head follow the camera and make it jump.

Step 1: The machine #

A machine is states, transitions between them, and the parameters the transitions test. Parameters are typed: float, integer, boolean or trigger. Writing a float to a trigger, or to a name the schema does not have, is refused, and the refusal names the call that would have worked.

idle plays one clip. move is a blend space: AnimationBlendSpace puts the walk at 1.5 m/s and the run at 4 m/s, and between the two the state plays some of each, by speed. The two clips share one phase, so the feet come down together however the mix is weighted. A second parameter, given as across:, spreads the points over a plane instead of a line, which is how a walk forward, back and to each side is blended by two speeds.

The transitions say when to leave. Each has its conditions, a crossfade in seconds and a priority. The jump is a trigger, which stays set until a transition uses it, so a jump asked for during a fade still happens once the fade is over. The way out of the jump waits on an exit time of one: the clip has to finish first.

/// Idle, a move that blends a walk into a run by `speed`, and a jump
/// played once on a trigger. The parameters are typed: a write of the
/// wrong kind is refused with the call that would have been right.
static AnimationStateMachine machine() => AnimationStateMachine(
  parameters: AnimationParameterSchema(const <AnimationParameter>[
    AnimationParameter.float('speed'),
    AnimationParameter.trigger('jump'),
  ]),
  entry: 'idle',
  states: <AnimationState>[
    const AnimationState(name: 'idle', clip: 'Idle'),
    AnimationState(
      name: 'move',
      blend: AnimationBlendSpace('speed', const <BlendPoint>[
        BlendPoint(walkAt, 'Walking'),
        BlendPoint(runAt, 'Running'),
      ]),
    ),
    const AnimationState(
      name: 'jump',
      clip: 'Jump',
      wrap: AnimationWrap.once,
    ),
  ],
  transitions: <AnimationTransition>[
    AnimationTransition(
      from: 'idle',
      to: 'move',
      conditions: const <AnimationCondition>[
        CompareCondition('speed', AnimationComparison.greater, 0.5),
      ],
      fade: const Duration(milliseconds: 300),
    ),
    AnimationTransition(
      from: 'move',
      to: 'idle',
      conditions: const <AnimationCondition>[
        CompareCondition('speed', AnimationComparison.less, 0.3),
      ],
      fade: const Duration(milliseconds: 300),
    ),
    for (final from in <String>['idle', 'move'])
      AnimationTransition(
        from: from,
        to: 'jump',
        conditions: const <AnimationCondition>[TriggerCondition('jump')],
        fade: const Duration(milliseconds: 100),
        priority: 1,
      ),
    AnimationTransition(
      from: 'jump',
      to: 'idle',
      exitTime: 1.0,
      fade: const Duration(milliseconds: 200),
    ),
  ],
);

Step 2: The graph over the model's clips #

The graph is made from the machine, the clips and a pose of the model's skeleton, Pose.fromNodes. A machine that cannot run, say one naming a clip the model does not have, is refused here with every problem listed. A tool that wants to refuse politely calls problems(clips) first.

rootNode names the node whose travel along the floor is root motion. Step 6 comes back to it.

/// A graph over the robot's clips into a pose of its own skeleton, with
/// the walk's travel taken out of the body as root motion.
AnimationGraph _newGraph() => AnimationGraph(
  machine: machine(),
  clips: _clips,
  pose: AnimationPose.fromNodes(_asset.nodes),
)..rootNode = _body;

Step 3: A layer over the right arm #

A layer is a second graph laid on the first one's pose, only where its mask covers. AnimationMask.below takes a node and everything under it, here the right shoulder down to the fingertips. The layer plays the wave. Its weight starts at nought, and fadeTo brings it in over a few steps, so the arm does not snap. A layer can also be additive. Then it adds its distance from rest on top of the base instead of replacing it.

/// A second graph that only waves, laid over the right arm from the
/// shoulder down. Its weight starts at nought and fades in when asked.
AnimationGraphLayer _waveLayer(AnimationGraph base) => AnimationGraphLayer(
  graph: AnimationGraph(
    machine: AnimationStateMachine(
      parameters: AnimationParameterSchema(const <AnimationParameter>[]),
      entry: 'wave',
      states: const <AnimationState>[
        AnimationState(name: 'wave', clip: 'Wave'),
      ],
      transitions: const <AnimationTransition>[],
    ),
    clips: _clips,
    pose: AnimationPose.fromNodes(_asset.nodes),
  ),
  mask: AnimationMask.below(base.pose.parents, _shoulder),
  weight: 0.0,
);

Step 4: A look goal on the head #

Goals are inverse kinematics applied after the states and the layers have posed the skeleton. LookGoal turns a joint so that what faced forward at rest faces the target, by at most limit radians. Past the limit it turns as far as it may and stops. ReachGoal bends a two-bone arm or leg to a point, and FootPlantGoal puts feet on the floor under them. All three fade by weight the way a layer does.

// The head turns towards a point in the pose's space, a radian at most;
// what faced +z at rest is what turns.
_look = LookGoal(joint: _head, forward: Vector3(0.0, 0.0, 1.0), limit: 1.0);
_graph.goals.add(_look);

Step 5: Write the parameters, then step #

Once a frame the page writes the speed, fades the layer and the look in or out, moves the look's target to the camera in the pose's space, and steps the graph. evaluate returns the pose, and writeTo puts it on the model's nodes. Turn Speed changes by itself off and drag the slider past half a metre a second to see the fade from idle into the walk.

// The game writes the parameters between steps; the graph decides.
_graph.parameters.setFloat('speed', speed);
_wave.fadeTo(waving ? 1.0 : 0.0, fade: const Duration(milliseconds: 300));
_look.fadeTo(watching ? 1.0 : 0.0, fade: const Duration(milliseconds: 300));
final Matrix4 toPose = Matrix4.inverted(_model.root.sceneMatrix);
_look.target.setFrom(
  toPose.transformed3(context.camera.readScenePosition()),
);
_graph.evaluate(dt).writeTo(_model.player!.targets);

Step 6: Root motion #

The robot's clips walk on the spot, so the page gives the walk and the run a stride along the body before it builds the graph. With rootNode set, the graph holds that node over its rest and hands its travel over as rootDelta. The travel is unwound across the loop's turns and mixed by the same weights as the pose. rootDeltaIn carries it into the world by the model's matrix. A game passes that to CharacterController.step(drivenBy:), which sweeps it, so a walk stops at a wall. Here it just moves the robot round a circle.

// The stride the clips took, turned and scaled into the world by the
// model's own matrix, moves the robot; a game would hand it to a
// `CharacterController` to sweep. Here it bends round a circle.
final Vector3 step = _graph.rootDeltaIn(_model.root.sceneMatrix);
_at.add(step);
_yaw -= step.length / _radius;

Step 7: What has to hold #

The check builds a second graph from the same machine and steps it by hand. It has to start idle. When the speed goes past the threshold it has to take the transition, and on the next step both states have to be playing with a fade weight between nought and one. At 2 m/s, a fifth of the way from the walk's point to the run's, the thigh has to be exactly the walk and the run sampled at the shared phase and mixed four to one. The body has to travel forwards. With the wave layer at full weight, the upper arm has to be the layer's and the head has to stay outside the mask.

// A graph of its own, so the one on screen is left as it was.
const double step = 1 / 60;
final AnimationGraph graph = _newGraph()..evaluate(step);
if (graph.state != 'idle') throw StateError('it did not start idle');

// Past the threshold it takes the transition on that step, and on the
// next both states are playing, the move coming in.
const double told = 2.0;
graph.parameters.setFloat('speed', told);
graph.evaluate(step);
if (graph.state != 'move' || graph.fadingFrom != 'idle') {
  throw StateError('no transition from idle to move');
}
graph.evaluate(step);
if (!(graph.fadeWeight > 0.0 && graph.fadeWeight < 1.0)) {
  throw StateError('no crossfade from idle to move');
}
for (var i = 0; i < 30; i++) {
  graph.evaluate(step);
}
if (graph.fadingFrom != null) throw StateError('the fade never ended');

// A fifth of the way from the walk's point to the run's, the pose is
// four fifths walk and one fifth run at the shared phase: two weights
// that sum to one.
final double t = (told - walkAt) / (runAt - walkAt);
final AnimationClip walk = _clips.firstWhere((c) => c.name == 'Walking');
final AnimationClip run = _clips.firstWhere((c) => c.name == 'Running');
final AnimationPose expected = graph.pose.restCopy()
  ..sampleClip(walk, graph.stateSeconds * walk.durationSeconds);
final AnimationPose ran = graph.pose.restCopy()
  ..sampleClip(run, graph.stateSeconds * run.durationSeconds);
expected.blendFrom(ran, 1.0 - t);
if (_dot(expected, graph.pose, _thigh) < 0.9999) {
  throw StateError('the leg is not half walk and half run');
}

// Root motion: the body is held over its rest and its travel handed
// over instead, forwards.
if (!(graph.rootDelta.z > 0.0)) throw StateError('no root motion');

// The layer writes the arm and leaves the head to the base.
final AnimationGraphLayer layer = _waveLayer(graph)..weight = 1.0;
graph.layers.add(layer);
graph.evaluate(step);
final int arm = _node('UpperArm.R');
if (_dot(layer.graph.pose, graph.pose, arm) < 0.9999) {
  throw StateError('the wave did not reach the arm');
}
if (!layer.mask.covers(arm) || layer.mask.covers(_head)) {
  throw StateError('the mask is not the right arm');
}

Note. A graph takes one transition a step, and none during a crossfade: a fade cannot be interrupted, so a trigger set during one waits for it to end. This page steps the graph on the frame, while a game steps it on its fixed step and draws the step's pose, so the pose moves at the step's rate and is not blended between steps. Root motion is taken from a node whose parents stand at rest; a rig whose clips move those parents does not get it. The dungeon's monsters run on this graph but get no root motion from it yet, since their clips walk on the spot as the robot's do.