flutter3d
Showcase Changelog 62 packages API reference

Replays as tests: the source

since 1.0.0-rc.1 Simulation, audio and XR

Regions the guide quotes: game (line 24), record (line 60), replay (line 136), check (line 336).

1/// A recorded run as a test: the tape played back into the game with no
2/// screen, and the digest of its state checked against the recording at the
3/// steps it was taken, so a change to the simulation fails the build at the
4/// step it first shows.
5///
6/// **`testReplay` itself is not called here.** It lives in
7/// `flutter3d_testing`, registers a `flutter_test` test and reads the tape
8/// from a file, none of which a page in a running app can do. Its loop is a
9/// dozen lines over `flutter3d_sim` types — `Demo`, `InputTapePlayback`,
10/// `StateDigest` — and this page carries that loop over, with the same
11/// refusals and the same sentence on a divergence.
12///
13/// Quoted by `replay_tests.md` and shown whole in the Source tab.
14library;
16import 'dart:convert';
18import 'package:flutter/foundation.dart' show visibleForTesting;
19import 'package:flutter3d/flutter3d.dart';
20import 'package:flutter3d_showcase/src/demo/demo.dart';
21import 'package:flutter3d_showcase/src/demo/scene_kit.dart';
22import 'package:flutter3d_sim/flutter3d_sim.dart';
24/// A ball pushed along a track between two walls. [restitution] is how
25/// hard it bounces off them, the number the planted change touches: a run
26/// that never reaches a wall cannot tell two builds apart.
27final class _Ball {
28 _Ball({this.restitution = 0.8, this.wall = 6.0});
30 final double restitution;
31 final double wall;
32 double x = 0.0;
33 double v = 0.0;
34 int bounces = 0;
36 /// What a tape is checked against before it is played: the level, so an
37 /// edited level is refused instead of reported as a bug.
38 String get levelHash => contentDigestHex(<String, Object?>{'wall': wall});
40 void restore(Snapshot start) {
41 x = start.data.number('x');
42 v = start.data.number('v');
43 bounces = start.data.integer('bounces');
44 }
46 void step(InputState input) {
47 v = (v + input.moveAxis.x * 0.002) * 0.995;
48 x += v;
49 if (x > wall || x < 0.0) {
50 x = x > wall ? 2.0 * wall - x : -x;
51 v = -v * restitution;
52 bounces++;
53 }
54 }
56 Snapshot save() =>
57 Snapshot(<String, Object?>{'x': x, 'v': v, 'bounces': bounces});
60/// What a recording session leaves behind: the start, the tape, and a
61/// digest every twenty steps, written out as a `.f3drun` would be and read
62/// back the way a test reads one.
63Demo _record() {
64 final _Ball game = _Ball();
65 final Snapshot start = game.save();
66 final InputTape tape = InputTape(
67 seed: 0,
68 frames: <InputFrame>[
69 for (var i = 0; i < 240; i++)
70 InputFrame(stickX: i < 120 ? 1.0 : (i < 170 ? 0.0 : -1.0)),
71 ],
72 );
73 final DigestTrace checkpoints = DigestTrace(every: 20);
74 final InputState input = InputState();
75 final InputTapePlayback playback = InputTapePlayback.tape(tape);
76 for (var step = 1; step <= tape.steps; step++) {
77 playback.applyTo(input);
78 game.step(input);
79 checkpoints.observe(step, game.save().toJson());
80 input.endStep();
81 }
82 final Demo demo = Demo(
83 level: 'track',
84 levelHash: game.levelHash,
85 start: start,
86 tape: tape,
87 buildStamp: 'showcase',
88 checkpoints: checkpoints,
89 simulation: SimulationVersion.engineOnly,
90 );
91 return Demo.fromJson(
92 jsonDecode(jsonEncode(demo.toJson())) as Map<String, Object?>,
93 );
96/// What a replay of a tape came to.
97sealed class _Verdict {
98 const _Verdict();
101/// Every checkpoint asked for agreed.
102final class _Agreed extends _Verdict {
103 const _Agreed(this.steps);
104 final List<int> steps;
106 @override
107 String toString() => 'agreed at steps ${steps.join(', ')}';
110/// The first checkpoint that did not, and the last one that did.
111final class _Diverged extends _Verdict {
112 const _Diverged(this.step, this.agreed, this.expected, this.found);
113 final int step;
114 final int? agreed;
115 final int expected;
116 final int found;
118 @override
119 String toString() =>
120 'diverged at step $step: the tape recorded ${_hex(expected)} and this '
121 'build reached ${_hex(found)}; '
122 '${agreed == null ? 'no earlier checkpoint was checked' : 'step $agreed still agreed'}';
125/// Nothing was played, and why.
126final class _Refused extends _Verdict {
127 const _Refused(this.reason);
128 final String reason;
130 @override
131 String toString() => reason;
134String _hex(int digest) => digest.toRadixString(16).padLeft(8, '0');
136/// [demo] played into [game] with no screen, its digest checked at each
137/// step of [digestAt] — every checkpoint the tape holds when left out.
138_Verdict _replay(Demo demo, _Ball game, {Iterable<int>? digestAt}) {
139 final Map<int, int> recorded = <int, int>{
140 for (final (int i, int step) in demo.checkpoints.steps.indexed)
141 step: demo.checkpoints.digests[i],
142 };
143 final Set<int> digests = digestAt?.toSet() ?? recorded.keys.toSet();
145 // Refused before the first step, each with what to do instead.
146 final Iterable<int> missing = digests.where((s) => !recorded.containsKey(s));
147 if (missing.isNotEmpty) {
148 return _Refused(
149 'the tape has no checkpoint at step ${missing.join(', ')}: it took one '
150 'every ${demo.checkpoints.every} steps',
151 );
152 }
153 if (digests.isEmpty) {
154 return const _Refused(
155 'this replay checks nothing, so it would pass whatever the game does',
156 );
157 }
158 if (game.levelHash != demo.levelHash) {
159 return _Refused(
160 'the level has changed since the tape was recorded: it was played on '
161 '${demo.levelHash}, the level is ${game.levelHash} now',
162 );
163 }
165 // The ball runs the engine alone; a tape recorded on another simulation
166 // is refused by the playback, before a step is played.
167 final InputTapePlayback playback;
168 try {
169 playback = InputTapePlayback(
170 demo,
171 simulation: SimulationVersion.engineOnly,
172 );
173 } on ReplayException catch (refused) {
174 return _Refused(refused.reason);
175 }
176 game.restore(demo.start);
177 final InputState input = InputState();
178 final int last = digests.reduce((a, b) => a > b ? a : b);
179 int? agreed;
180 for (var step = 1; step <= last; step++) {
181 playback.applyTo(input);
182 game.step(input);
183 if (digests.contains(step)) {
184 final int found = StateDigest.of(game.save().toJson());
185 if (found != recorded[step]) {
186 return _Diverged(step, agreed, recorded[step]!, found);
187 }
188 agreed = step;
189 }
190 input.endStep();
191 }
192 return _Agreed(digests.toList()..sort());
195/// The `replay-tests` page: a recorded run played back as a test against its
196/// checkpoints. Its check is twelve checkpoints, and a change that parts the
197/// replay at the step of the first bounce.
198final class ReplayTestsDemo extends ShowcaseDemo {
199 late final Demo _tape;
201 /// Whether the lower lane runs the build with the planted change.
202 bool planted = true;
203 bool _dirty = true;
204 late _Verdict _lower;
206 final _Ball _upperBall = _Ball();
207 late _Ball _lowerBall;
208 final InputState _upperInput = InputState();
209 final InputState _lowerInput = InputState();
210 late InputTapePlayback _upperPlay;
211 late InputTapePlayback _lowerPlay;
213 late final MeshNode _upper;
214 late final MeshNode _lowerNode;
215 late final List<MeshNode> _lamps;
217 static const double _restitution = 0.8;
219 /// The planted change: a bounce a hair softer. Nothing differs until the
220 /// ball first reaches a wall.
221 static const double _changed = 0.79;
223 @override
224 void configureView(DemoContext context) {
225 context.orbit
226 ..distance = 9.0
227 ..pitch = 0.6
228 ..yaw = 0.0;
229 context.orbit.target.setValues(0.0, 0.3, 0.0);
230 }
232 @override
233 Scene build(DemoContext context) {
234 _tape = _record();
235 _upper = ballNode(context, 'this build', 0.25, Vector4(0.4, 0.7, 0.95, 1));
236 _lowerNode = ballNode(
237 context,
238 'the other build',
239 0.25,
240 Vector4(0.95, 0.65, 0.3, 1),
241 );
242 _lamps = <MeshNode>[
243 for (final (int k, int step) in _tape.checkpoints.steps.indexed)
244 ballNode(
245 context,
246 'checkpoint $step',
247 0.14,
248 Vector4(0.3, 0.3, 0.33, 1),
249 at: Vector3(-3.0 + k * 6.0 / 11.0, 0.15, 2.0),
250 ),
251 ];
252 _restart();
253 return sceneOf(<SceneNode>[
254 floorNode(context, width: 8.0, depth: 5.0),
255 for (final double z in <double>[-0.6, 0.6])
256 for (final double x in <double>[-3.15, 3.15])
257 blockNode(
258 context,
259 'wall',
260 Vector3(0.1, 0.6, 0.8),
261 Vector4(0.6, 0.6, 0.62, 1),
262 at: Vector3(x, 0.3, z),
263 ),
264 _upper,
265 _lowerNode,
266 ..._lamps,
267 ]);
268 }
270 void _restart() {
271 _lowerBall = _Ball(restitution: planted ? _changed : _restitution);
272 _lower = _replay(_tape, _lowerBall);
273 _upperBall.restore(_tape.start);
274 _lowerBall.restore(_tape.start);
275 _upperPlay = InputTapePlayback(
276 _tape,
277 simulation: SimulationVersion.engineOnly,
278 );
279 _lowerPlay = InputTapePlayback(
280 _tape,
281 simulation: SimulationVersion.engineOnly,
282 );
283 // The lamps are the lower lane's checkpoints: green while they agree,
284 // red where the replay failed, dark after it, since a failed replay stops.
285 for (final (int k, int step) in _tape.checkpoints.steps.indexed) {
286 final Vector4 color = switch (_lower) {
287 _Diverged(step: final at) when step == at => Vector4(0.9, 0.3, 0.3, 1),
288 _Diverged(step: final at) when step > at => Vector4(0.3, 0.3, 0.33, 1),
289 _ => Vector4(0.35, 0.85, 0.4, 1),
290 };
291 _lamps[k].material.baseColor = _fromSrgb(color);
292 }
293 }
295 @override
296 void update(DemoContext context, double dt) {
297 if (_dirty) {
298 _dirty = false;
299 _restart();
300 }
301 // One step of each lane a frame, from the tape; both start again at its
302 // end.
303 if (_upperPlay.isFinished) _restart();
304 for (final (InputTapePlayback play, InputState input, _Ball ball)
305 in <(InputTapePlayback, InputState, _Ball)>[
306 (_upperPlay, _upperInput, _upperBall),
307 (_lowerPlay, _lowerInput, _lowerBall),
308 ]) {
309 play.applyTo(input);
310 ball.step(input);
311 input.endStep();
312 }
313 _upper.setPosition(_upperBall.x - 3.0, 0.25, -0.6);
314 _lowerNode.setPosition(_lowerBall.x - 3.0, 0.25, 0.6);
315 }
317 @override
318 List<DemoControl> controls(DemoContext context) => <DemoControl>[
319 ToggleControl(
320 'Lower lane: a softer bounce',
321 value: () => planted,
322 onChanged: (bool v) {
323 planted = v;
324 _dirty = true;
325 },
326 ),
327 ];
329 /// The four replays the page's claim is made of, as sentences.
330 @visibleForTesting
331 List<String> get verdicts => <String>[
332 for (final _Verdict v in _verdicts()) '$v',
333 ];
335 List<_Verdict> _verdicts() => <_Verdict>[
336 // This build replays its own tape: every checkpoint agrees.
337 _replay(_tape, _Ball()),
338 // Only some steps asked for, as `digestAt: [60, 120]` would.
339 _replay(_tape, _Ball(), digestAt: <int>[60, 120]),
340 // The planted change, caught at the first checkpoint after the first
341 // bounce, with the one before it still agreeing.
342 _replay(_tape, _Ball(restitution: _changed)),
343 // A step the tape took no digest at, and a level edited since.
344 _replay(_tape, _Ball(), digestAt: <int>[65]),
345 _replay(_tape, _Ball(wall: 6.5)),
346 ];
348 @override
349 void verify(Scene scene, FrameResult frame) {
350 if (frame.drawCalls < 1) throw StateError('nothing reached the frame');
351 if (_tape.checkpoints.steps.length != 12) {
352 throw StateError('the tape should hold twelve checkpoints');
353 }
354 switch (_verdicts()) {
355 case [
356 _Agreed(steps: final all),
357 _Agreed(steps: [60, 120]),
358 _Diverged(step: final at, agreed: final before?),
359 _Refused(reason: final noCheckpoint),
360 _Refused(reason: final edited),
361 ]
362 when all.length == 12 &&
363 before == at - 20 &&
364 noCheckpoint.contains('no checkpoint at step 65') &&
365 edited.contains('level has changed'):
366 // The planted change only matters at a wall, so the replay has to
367 // agree through the steps before the first bounce.
368 final _Ball probe = _Ball()..restore(_tape.start);
369 final InputState input = InputState();
370 final InputTapePlayback play = InputTapePlayback(
371 _tape,
372 simulation: SimulationVersion.engineOnly,
373 );
374 var firstBounce = 0;
375 for (var step = 1; probe.bounces == 0; step++) {
376 play.applyTo(input);
377 probe.step(input);
378 input.endStep();
379 firstBounce = step;
380 }
381 if (before >= firstBounce || at < firstBounce) {
382 throw StateError(
383 'the bounce is at step $firstBounce, but the replay parted '
384 'between $before and $at',
385 );
386 }
387 case final List<_Verdict> other:
388 throw StateError('the replays came to $other');
389 }
390 }
393/// A `Vector4` holding a colour sRGB-encoded, as the linear colour it names.
394LinearColor _fromSrgb(Vector4 c) => LinearColor.fromSrgb(c.x, c.y, c.z, c.w);