Root motion: the source
Open the live demo · Read the guide · View on GitHub
Regions the guide quotes: clip (line 96), controller (line 125), live (line 141).
1/// A walk clip whose own translation track stands still: the forward motion
2/// was extracted into the clip's `extras` under `flutter3dRootMotion`, and
3/// `AnimationPlayer.rootMotionDelta` hands it back a step at a time so a
4/// separate controller node can carry the character instead of the rig
5/// sliding inside itself. The controller paces between two ends of a floor.
6///
7/// Quoted by `root_motion.md` and shown whole in the Source tab.
8library;
10import 'dart:math' as math;
11import 'dart:typed_data';
13import 'package:flutter3d/flutter3d.dart';
14import 'package:flutter3d_showcase/src/demo/demo.dart';
16/// The `root-motion` page: a walker whose clip stands still, carried up and
17/// down a floor by a controller node that takes the clip's root motion. Its
18/// check fails if the controller does not move forward, or moves further than
19/// one frame of the walk allows.
20final class RootMotionDemo extends ShowcaseDemo {
21 late final AnimationPlayer _player;
22 late final SceneNode _controller;
23 double _lastTime = 0.0;
24 double _direction = 1.0;
26 /// How far from the middle of the floor the walker goes before it turns.
27 static const double _reach = 3.5;
30 void configureView(DemoContext context) {
31 context.orbit
32 ..distance = 11.0
33 ..pitch = 0.6
34 ..yaw = 0.7;
35 }
38 Scene build(DemoContext context) {
39 final Scene scene = Scene();
41 scene.add(
42 MeshNode(
43 DeviceMesh.upload(
44 context.device,
45 const PlaneShape(width: 7.0, depth: 11.0).build(),
46 ),
47 RenderMaterial(
48 name: 'floor',
49 baseColor: LinearColor.fromSrgb(0.32, 0.36, 0.34, 1.0),
50 ),
51 name: 'floor',
52 ),
53 );
54 // Posts along both edges: the walker's own cube never changes shape, so
55 // what shows that it is being carried is the ground going past it.
56 final DeviceMesh post = DeviceMesh.upload(
57 context.device,
58 CuboidShape(size: Vector3(0.2, 0.6, 0.2)).build(),
59 );
60 final RenderMaterial postMaterial = RenderMaterial(
61 name: 'post',
62 baseColor: LinearColor.fromSrgb(0.85, 0.8, 0.6, 1.0),
63 );
64 for (var z = -5; z <= 5; z += 2) {
65 for (final double x in <double>[-2.8, 2.8]) {
66 scene.add(
67 MeshNode(post, postMaterial, name: 'post $x,$z')
68 ..setPosition(x, 0.3, z.toDouble()),
69 );
70 }
71 }
73 final MeshNode walker = MeshNode(
74 DeviceMesh.upload(context.device, CuboidShape().build()),
75 RenderMaterial(
76 name: 'walker',
77 baseColor: LinearColor.fromSrgb(0.3, 0.7, 0.4, 1.0),
78 ),
79 name: 'walker',
80 );
81 // A nose, so the turn at each end reads as a turn.
82 walker.add(
83 MeshNode(
84 DeviceMesh.upload(
85 context.device,
86 CuboidShape(size: Vector3(0.3, 0.3, 0.4)).build(),
87 ),
88 RenderMaterial(
89 name: 'nose',
90 baseColor: LinearColor.fromSrgb(0.95, 0.9, 0.8, 1.0),
91 ),
92 name: 'nose',
93 )..setPosition(0.0, 0.0, 0.6),
94 );
96 // The track that ships with the clip goes up and down in place and
97 // nowhere else: the walk's forward travel was taken out of it, the way
98 // an exporter's own extraction pass leaves it. The values a real walk
99 // would have had live in `extras` instead, one triple per keyframe.
100 final Float32List times = Float32List.fromList(<double>[0.0, 0.5, 1.0]);
101 final AnimationTrack bobTrack = AnimationTrack(
102 nodeIndex: 0,
103 path: AnimationPath.translation,
104 interpolation: AnimationInterpolation.linear,
105 times: times,
106 values: Float32List.fromList(<double>[
107 0.0, 0.0, 0.0, //
108 0.0, 0.15, 0.0,
109 0.0, 0.0, 0.0,
110 ]),
111 componentCount: 3,
112 );
113 final AnimationClip walk = AnimationClip(
114 name: 'walk',
115 tracks: <AnimationTrack>[bobTrack],
116 extras: <String, Object?>{
117 rootMotionExtra: <List<double>>[
118 <double>[0.0, 0.0, 0.0],
119 <double>[0.0, 0.0, 1.0],
120 <double>[0.0, 0.0, 2.0],
121 ],
122 },
123 );
125 _controller = SceneNode(name: 'controller')..setPosition(0.0, 0.5, -_reach);
126 _controller.add(walker);
127 _player = AnimationPlayer(
128 clips: <AnimationClip>[walk],
129 targets: <AnimationTarget?>[walker],
130 )..play(index: 0);
131 scene.add(_controller);
133 return scene..add(
134 LightNode(name: 'sun', intensity: 3.0 * LightNode.legacyUnit)
135 ..setLocalForward(Vector3(-0.4, -0.7, -0.5)),
136 );
137 }
140 void update(DemoContext context, double dt) {
141 final double fromTime = _lastTime;
142 _player.advance(dt);
143 _lastTime = _player.timeSeconds;
144 final Vector3? delta = _player.rootMotionDelta(
145 0,
146 fromSeconds: fromTime,
147 toSeconds: _lastTime,
148 );
149 if (delta != null) {
150 // The clip only ever walks forward; which way forward is on the floor
151 // is the controller's business, so it is the controller that turns
152 // round when the floor runs out.
153 _controller.translate(0.0, 0.0, delta.z * _direction);
154 final double z = _controller.readPosition().z;
155 if (z.abs() >= _reach) {
156 _direction = z > 0 ? -1.0 : 1.0;
157 _controller
158 ..setPosition(0.0, 0.5, _reach * (z > 0 ? 1.0 : -1.0))
159 ..setRotation(
160 Quaternion.axisAngle(
161 Vector3(0.0, 1.0, 0.0),
162 _direction > 0 ? 0.0 : math.pi,
163 ),
164 );
165 }
166 }
167 }
170 void verify(Scene scene, FrameResult frame) {
171 final double z = _controller.readPosition().z;
172 if (z <= -_reach + 1e-5) {
173 throw StateError('the controller did not carry the walk forward');
174 }
175 if (z > -_reach + 1.0) {
176 throw StateError('the controller moved further than one frame allows');
177 }
178 if (frame.drawCalls < 1) throw StateError('the walker was not drawn');
179 }
180}