flutter3d
Showcase Changelog 62 packages API reference

An animation graph: the source

since 1.0.0-rc.1 Animation

Regions the guide quotes: machine (line 91), graph (line 149), layer (line 157), look (line 220), drive (line 277), root (line 287), check (line 353).

1/// The robot driven by an animation graph instead of by hand: a state
2/// machine over its own clips, a blend space from a walk to a run by speed,
3/// a wave laid over one arm by a masked layer, a head that turns to the
4/// camera by a look goal, and the walk's stride carried into the world as
5/// root motion.
6///
7/// Quoted by `animation_graph.md` and shown whole in the Source tab.
8library;
9
10import 'dart:math' as math;
11import 'dart:typed_data';
13import 'package:flutter/foundation.dart' show visibleForTesting;
14import 'package:flutter3d/flutter3d.dart';
15import 'package:flutter3d_showcase/src/demo/demo.dart';
17/// The `animation-graph` page: `RobotExpressive.glb` walking a circle of radius
18/// 3 m, driven by one `AnimationGraph`. Its check follows the graph from idle
19/// into the move state and through the crossfade between them.
20final class AnimationGraphDemo extends ShowcaseDemo {
21 late final ModelAsset _asset;
22 late final ModelInstance _model;
23 late final List<AnimationClip> _clips;
24 late final AnimationGraph _graph;
25 late final AnimationGraphLayer _wave;
26 late final LookGoal _look;
28 /// Node indices in the robot's file, found by name.
29 late final int _body, _shoulder, _head, _thigh;
31 /// The speed the graph is told, in m/s: it picks the place in the walk-to-run
32 /// blend space. The "Speed" slider writes it, and so does [wandering] while
33 /// it is on.
34 double speed = 0.0;
36 /// Whether [speed] drifts between standing and running on its own. Dragging
37 /// the speed slider turns it off, and the "Speed changes by itself" switch
38 /// turns it back on.
39 bool wandering = true;
41 /// Whether the right arm waves: the masked wave layer fades in over 0.3
42 /// seconds when this turns on, and out when it turns off, while the rest of
43 /// the body keeps walking.
44 bool waving = false;
46 /// Whether the head turns to the camera: the look goal fades in or out over
47 /// 0.3 seconds as this changes.
48 bool watching = true;
50 double _clock = 0.0;
51 double _yaw = 0.0;
52 final Vector3 _at = Vector3(3.0, 0.0, 0.0);
54 /// `RobotExpressive.glb` stands this tall in its own units; scaled to
55 /// 1.8 m.
56 static const double _modelHeight = 4.461221901699901;
57 static const double _scale = 1.8 / _modelHeight;
59 /// The speed at which the blend space is all walk, in m/s; between it and
60 /// [runAt] the two clips are mixed.
61 static const double walkAt = 1.5;
63 /// The speed at which the blend space is all run, in m/s; past it the run
64 /// clip plays alone.
65 static const double runAt = 4.0;
67 /// The circle the robot walks round, m.
68 static const double _radius = 3.0;
70 @override
71 void configureView(DemoContext context) {
72 context.orbit
73 ..distance = 9.0
74 ..pitch = 0.45
75 ..yaw = 0.3;
76 context.orbit.target.setValues(0.0, 0.8, 0.0);
77 }
79 @override
80 Future<void> prepare(DemoContext context) async {
81 // CC0, Tomás Laulhé, with facial morph targets by Don McCurdy; see
82 // `packages/flutter3d_samples/assets/ATTRIBUTION.md`.
83 final document = await loadModelByPath(
84 'packages/flutter3d_samples/assets/RobotExpressive.glb',
85 );
86 _asset = await ModelAsset.fromDocument(document, device: context.device);
87 }
89 int _node(String name) => _asset.nodes.indexWhere((n) => n.name == name);
91 /// Idle, a move that blends a walk into a run by `speed`, and a jump
92 /// played once on a trigger. The parameters are typed: a write of the
93 /// wrong kind is refused with the call that would have been right.
94 static AnimationStateMachine machine() => AnimationStateMachine(
95 parameters: AnimationParameterSchema(const <AnimationParameter>[
96 AnimationParameter.float('speed'),
97 AnimationParameter.trigger('jump'),
98 ]),
99 entry: 'idle',
100 states: <AnimationState>[
101 const AnimationState(name: 'idle', clip: 'Idle'),
102 AnimationState(
103 name: 'move',
104 blend: AnimationBlendSpace('speed', const <BlendPoint>[
105 BlendPoint(walkAt, 'Walking'),
106 BlendPoint(runAt, 'Running'),
107 ]),
108 ),
109 const AnimationState(
110 name: 'jump',
111 clip: 'Jump',
112 wrap: AnimationWrap.once,
113 ),
114 ],
115 transitions: <AnimationTransition>[
116 AnimationTransition(
117 from: 'idle',
118 to: 'move',
119 conditions: const <AnimationCondition>[
120 CompareCondition('speed', AnimationComparison.greater, 0.5),
121 ],
122 fade: const Duration(milliseconds: 300),
123 ),
124 AnimationTransition(
125 from: 'move',
126 to: 'idle',
127 conditions: const <AnimationCondition>[
128 CompareCondition('speed', AnimationComparison.less, 0.3),
129 ],
130 fade: const Duration(milliseconds: 300),
131 ),
132 for (final from in <String>['idle', 'move'])
133 AnimationTransition(
134 from: from,
135 to: 'jump',
136 conditions: const <AnimationCondition>[TriggerCondition('jump')],
137 fade: const Duration(milliseconds: 100),
138 priority: 1,
139 ),
140 AnimationTransition(
141 from: 'jump',
142 to: 'idle',
143 exitTime: 1.0,
144 fade: const Duration(milliseconds: 200),
145 ),
146 ],
147 );
149 /// A graph over the robot's clips into a pose of its own skeleton, with
150 /// the walk's travel taken out of the body as root motion.
151 AnimationGraph _newGraph() => AnimationGraph(
152 machine: machine(),
153 clips: _clips,
154 pose: AnimationPose.fromNodes(_asset.nodes),
155 )..rootNode = _body;
157 /// A second graph that only waves, laid over the right arm from the
158 /// shoulder down. Its weight starts at nought and fades in when asked.
159 AnimationGraphLayer _waveLayer(AnimationGraph base) => AnimationGraphLayer(
160 graph: AnimationGraph(
161 machine: AnimationStateMachine(
162 parameters: AnimationParameterSchema(const <AnimationParameter>[]),
163 entry: 'wave',
164 states: const <AnimationState>[
165 AnimationState(name: 'wave', clip: 'Wave'),
166 ],
167 transitions: const <AnimationTransition>[],
168 ),
169 clips: _clips,
170 pose: AnimationPose.fromNodes(_asset.nodes),
171 ),
172 mask: AnimationMask.below(base.pose.parents, _shoulder),
173 weight: 0.0,
174 );
176 @override
177 Scene build(DemoContext context) {
178 _body = _node('Body');
179 _shoulder = _node('Shoulder.R');
180 _head = _node('Head');
181 _thigh = _node('UpperLeg.L');
183 final scene = Scene()
184 ..ambientIntensity = 0.3 * LightNode.legacyUnit
185 ..add(
186 MeshNode(
187 DeviceMesh.upload(
188 context.device,
189 CuboidShape(size: Vector3(10.0, 0.2, 10.0)).build(),
190 ),
191 RenderMaterial(
192 name: 'floor',
193 baseColor: LinearColor.fromSrgb(0.42, 0.45, 0.5, 1.0),
194 ),
195 name: 'floor',
196 )..setPosition(0.0, -0.1, 0.0),
197 )
198 ..add(
199 LightNode(name: 'sun', intensity: 2.5 * LightNode.legacyUnit)
200 ..setLocalForward(Vector3(-0.3, -0.7, -0.4)),
201 );
202 _model = _asset.instantiate(scene, name: 'robot');
203 _model.root.setScale(_scale, _scale, _scale);
205 final player = _model.player!;
206 // The robot's walk and run are made in place. Their body is given a
207 // stride along +z here, so that root motion has something to carry.
208 _clips = <AnimationClip>[
209 for (final clip in player.clips)
210 switch (clip.name) {
211 'Walking' => _strided(clip, _body, walkAt),
212 'Running' => _strided(clip, _body, runAt),
213 _ => clip,
214 },
215 ];
217 _graph = _newGraph();
218 _wave = _waveLayer(_graph);
219 _graph.layers.add(_wave);
220 // The head turns towards a point in the pose's space, a radian at most;
221 // what faced +z at rest is what turns.
222 _look = LookGoal(joint: _head, forward: Vector3(0.0, 0.0, 1.0), limit: 1.0);
223 _graph.goals.add(_look);
224 _place();
225 return scene;
226 }
228 /// [clip] with [node]'s translation moved along +z at [metersPerSecond]
229 /// in the world, in the units of the body's parent: the armature is
230 /// scaled a hundred times inside a robot scaled to 1.8 m.
231 static AnimationClip _strided(
232 AnimationClip clip,
233 int node,
234 double metersPerSecond,
235 ) {
236 final perSecond = metersPerSecond / (_scale * 100.0);
237 return AnimationClip(
238 name: clip.name,
239 tracks: <AnimationTrack>[
240 for (final track in clip.tracks)
241 if (track.nodeIndex == node &&
242 track.path == AnimationPath.translation &&
243 track.interpolation == AnimationInterpolation.linear)
244 AnimationTrack(
245 nodeIndex: node,
246 path: AnimationPath.translation,
247 interpolation: AnimationInterpolation.linear,
248 times: track.times,
249 values: Float32List.fromList(<double>[
250 for (var k = 0; k < track.times.length; k++) ...<double>[
251 track.values[k * 3],
252 track.values[k * 3 + 1],
253 track.values[k * 3 + 2] + track.times[k] * perSecond,
254 ],
255 ]),
256 componentCount: 3,
257 )
258 else
259 track,
260 ],
261 );
262 }
264 void _place() {
265 _model.root
266 ..setPosition(_at.x, _at.y, _at.z)
267 ..setRotation(Quaternion.axisAngle(Vector3(0.0, 1.0, 0.0), _yaw));
268 }
270 @override
271 void update(DemoContext context, double dt) {
272 _clock += dt;
273 if (wandering) {
274 // Stands, walks, runs and slows again, over twelve seconds.
275 speed = math.max(0.0, 4.6 * math.sin(_clock * math.pi / 6.0) - 0.4);
276 }
277 // The game writes the parameters between steps; the graph decides.
278 _graph.parameters.setFloat('speed', speed);
279 _wave.fadeTo(waving ? 1.0 : 0.0, fade: const Duration(milliseconds: 300));
280 _look.fadeTo(watching ? 1.0 : 0.0, fade: const Duration(milliseconds: 300));
281 final Matrix4 toPose = Matrix4.inverted(_model.root.sceneMatrix);
282 _look.target.setFrom(
283 toPose.transformed3(context.camera.readScenePosition()),
284 );
285 _graph.evaluate(dt).writeTo(_model.player!.targets);
287 // The stride the clips took, turned and scaled into the world by the
288 // model's own matrix, moves the robot; a game would hand it to a
289 // `CharacterController` to sweep. Here it bends round a circle.
290 final Vector3 step = _graph.rootDeltaIn(_model.root.sceneMatrix);
291 _at.add(step);
292 _yaw -= step.length / _radius;
293 // Held on the circle against drift.
294 final double around = math.atan2(_at.z, _at.x);
295 _at.setValues(_radius * math.cos(around), 0.0, _radius * math.sin(around));
296 _place();
297 }
299 @override
300 List<DemoControl> controls(DemoContext context) => <DemoControl>[
301 SliderControl(
302 'Speed',
303 min: 0.0,
304 max: 4.5,
305 value: () => speed,
306 onChanged: (double v) {
307 wandering = false;
308 speed = v;
309 },
310 format: (double v) => '${v.toStringAsFixed(1)} m/s',
311 ),
312 ToggleControl(
313 'Speed changes by itself',
314 value: () => wandering,
315 onChanged: (bool v) => wandering = v,
316 ),
317 ToggleControl(
318 'Wave with the right arm (a masked layer)',
319 value: () => waving,
320 onChanged: (bool v) => waving = v,
321 ),
322 ToggleControl(
323 'Head watches the camera (a look goal)',
324 value: () => watching,
325 onChanged: (bool v) => watching = v,
326 ),
327 ToggleControl(
328 'Jump (a trigger)',
329 value: () => false,
330 onChanged: (bool v) {
331 if (v) _graph.parameters.fire('jump');
332 },
333 ),
334 ];
336 /// The state the shown graph is in, for a test.
337 @visibleForTesting
338 String get state => _graph.state;
340 static double _dot(AnimationPose a, AnimationPose b, int joint) {
341 var sum = 0.0;
342 for (var k = 0; k < 4; k++) {
343 sum += a.rotations[joint * 4 + k] * b.rotations[joint * 4 + k];
344 }
345 return sum.abs();
346 }
348 @override
349 void verify(Scene scene, FrameResult frame) {
350 if (frame.drawCalls < 1) {
351 throw StateError('the robot did not reach the frame');
352 }
353 // A graph of its own, so the one on screen is left as it was.
354 const double step = 1 / 60;
355 final AnimationGraph graph = _newGraph()..evaluate(step);
356 if (graph.state != 'idle') throw StateError('it did not start idle');
358 // Past the threshold it takes the transition on that step, and on the
359 // next both states are playing, the move coming in.
360 const double told = 2.0;
361 graph.parameters.setFloat('speed', told);
362 graph.evaluate(step);
363 if (graph.state != 'move' || graph.fadingFrom != 'idle') {
364 throw StateError('no transition from idle to move');
365 }
366 graph.evaluate(step);
367 if (!(graph.fadeWeight > 0.0 && graph.fadeWeight < 1.0)) {
368 throw StateError('no crossfade from idle to move');
369 }
370 for (var i = 0; i < 30; i++) {
371 graph.evaluate(step);
372 }
373 if (graph.fadingFrom != null) throw StateError('the fade never ended');
375 // A fifth of the way from the walk's point to the run's, the pose is
376 // four fifths walk and one fifth run at the shared phase: two weights
377 // that sum to one.
378 final double t = (told - walkAt) / (runAt - walkAt);
379 final AnimationClip walk = _clips.firstWhere((c) => c.name == 'Walking');
380 final AnimationClip run = _clips.firstWhere((c) => c.name == 'Running');
381 final AnimationPose expected = graph.pose.restCopy()
382 ..sampleClip(walk, graph.stateSeconds * walk.durationSeconds);
383 final AnimationPose ran = graph.pose.restCopy()
384 ..sampleClip(run, graph.stateSeconds * run.durationSeconds);
385 expected.blendFrom(ran, 1.0 - t);
386 if (_dot(expected, graph.pose, _thigh) < 0.9999) {
387 throw StateError('the leg is not half walk and half run');
388 }
390 // Root motion: the body is held over its rest and its travel handed
391 // over instead, forwards.
392 if (!(graph.rootDelta.z > 0.0)) throw StateError('no root motion');
394 // The layer writes the arm and leaves the head to the base.
395 final AnimationGraphLayer layer = _waveLayer(graph)..weight = 1.0;
396 graph.layers.add(layer);
397 graph.evaluate(step);
398 final int arm = _node('UpperArm.R');
399 if (_dot(layer.graph.pose, graph.pose, arm) < 0.9999) {
400 throw StateError('the wave did not reach the arm');
401 }
402 if (!layer.mask.covers(arm) || layer.mask.covers(_head)) {
403 throw StateError('the mask is not the right arm');
404 }
405 }