Replays and digests: the source
Open the live demo · Read the guide · View on GitHub
Regions the guide quotes: live (line 89), agree (line 138), diverge (line 143), wire (line 148).
1/// A number that says whether two runs of the same simulation are the same
2/// run, taken every so many steps so a divergence can be bracketed to where
3/// it happened.
4///
5/// A `Demo` is the file this rides in: a level, the state a run started from,
6/// its tape of inputs and this checkpoint trace, so a server can replay a
7/// submitted run and know exactly where it stopped agreeing.
8///
9/// Quoted by `replay_digest.md` and shown whole in the Source tab.
10library;
12import 'package:flutter3d/flutter3d.dart';
13import 'package:flutter3d_showcase/src/demo/demo.dart';
14import 'package:flutter3d_showcase/src/demo/scene_kit.dart';
15import 'package:flutter3d_sim/flutter3d_sim.dart';
17/// The `replay-digest` page: a run and its replay, digested at checkpoints.
18/// Its check is that two recordings of one run agree, that a drift is
19/// reported at the first checkpoint covering it, and that a trace reads back
20/// what it wrote.
21final class ReplayDigestDemo extends ShowcaseDemo {
22 late final String _report;
24 /// The step from which the replay drifts, 1 to 20; 21 means it never does.
25 double driftAt = 9.0;
26 bool _dirty = true;
27 late final List<BarGauge> _original;
28 late final List<BarGauge> _replay;
29 late final List<MeshNode> _lamps;
31 static const int _checkpoints = 5;
34 void configureView(DemoContext context) {
35 context.orbit
36 ..distance = 12.0
37 ..pitch = 0.45
38 ..yaw = 0.0;
39 context.orbit.target.setValues(0.0, 1.4, 0.0);
40 }
43 Scene build(DemoContext context) {
44 _report = _run();
45 BarGauge tower(String name, Vector4 ink, double x, double z) => BarGauge(
46 context,
47 name,
48 ink,
49 Vector3(x, 0.0, z),
50 height: 3.0,
51 width: 0.8,
52 vertical: true,
53 );
54 _original = <BarGauge>[
55 for (var k = 0; k < _checkpoints; k++)
56 tower(
57 'original $k',
58 Vector4(0.45, 0.65, 0.95, 1.0),
59 -4.0 + k * 2.0,
60 -0.8,
61 ),
62 ];
63 _replay = <BarGauge>[
64 for (var k = 0; k < _checkpoints; k++)
65 tower('replay $k', Vector4(0.95, 0.65, 0.3, 1.0), -4.0 + k * 2.0, 0.8),
66 ];
67 _lamps = <MeshNode>[
68 for (var k = 0; k < _checkpoints; k++)
69 ballNode(
70 context,
71 'lamp $k',
72 0.3,
73 Vector4(0.3, 0.3, 0.33, 1.0),
74 at: Vector3(-4.0 + k * 2.0, 3.7, 0.0),
75 ),
76 ];
77 return sceneOf(<SceneNode>[
78 floorNode(context, width: 12.0, depth: 5.0),
79 for (final BarGauge g in _original) ...g.nodes,
80 for (final BarGauge g in _replay) ...g.nodes,
81 ..._lamps,
82 ]);
83 }
86 void update(DemoContext context, double dt) {
87 if (!_dirty) return;
88 _dirty = false;
89 // The original, and a replay that drifts by one from the chosen step on.
90 // A checkpoint every four steps: the tower is the state there, and its
91 // lamp is green while the two digests agree.
92 final DigestTrace original = _record(20, (int step) => step);
93 final DigestTrace replay = _record(
94 20,
95 (int step) => step >= driftAt.round() ? step + 1 : step,
96 );
97 for (var k = 0; k < _checkpoints; k++) {
98 final int step = (k + 1) * 4;
99 _original[k].set(step / 22.0);
100 _replay[k].set((step >= driftAt.round() ? step + 1 : step) / 22.0);
101 final bool same = original.digests[k] == replay.digests[k];
102 _lamps[k].material.baseColor = LinearColor.fromSrgb(
103 same ? 0.35 : 0.9,
104 same ? 0.85 : 0.3,
105 same ? 0.4 : 0.3,
106 1.0,
107 );
108 }
109 }
112 List<DemoControl> controls(DemoContext context) => <DemoControl>[
113 SliderControl(
114 'Drift starts at step',
115 min: 1,
116 max: 21,
117 value: () => driftAt,
118 onChanged: (double v) {
119 driftAt = v.roundToDouble();
120 _dirty = true;
121 },
122 format: (double v) => v.round() > 20 ? 'never' : v.round().toString(),
123 ),
124 ];
126 /// A toy step: a counter that walks forward, standing in for a simulation.
127 static Map<String, Object?> _stepOf(int x) => <String, Object?>{'x': x};
129 static DigestTrace _record(int steps, int Function(int step) valueAt) {
130 final trace = DigestTrace(every: 4);
131 for (var step = 1; step <= steps; step++) {
132 trace.observe(step, _stepOf(valueAt(step)));
133 }
134 return trace;
135 }
137 static String _run() {
138 // Two recordings of the same run agree at every checkpoint.
139 final original = _record(20, (int step) => step);
140 final replay = _record(20, (int step) => step);
141 final agree = replay.divergenceFrom(original.digests) == null;
143 // A replay whose state drifts from step 9 onward parts company with the
144 // original at the first checkpoint after that.
145 final drifted = _record(20, (int step) => step >= 9 ? step + 1 : step);
146 final where = drifted.divergenceFrom(original.digests);
148 // What a `.f3drun` actually carries: the trace as hex digits, written
149 // out and read back.
150 final wireForm = original.toJson();
151 final reread = DigestTrace.fromJson(wireForm);
152 final roundTrips = reread.divergenceFrom(original.digests) == null;
154 return 'a faithful replay agrees: $agree\n'
155 'a drifted one diverges at $where\n'
156 'a trace written to JSON and read back still agrees: $roundTrips';
157 }
160 void verify(Scene scene, FrameResult frame) {
161 if (frame.drawCalls < 1) {
162 throw StateError('the marker was not drawn');
163 }
164 if (!_report.contains('agrees: true')) {
165 throw StateError('two recordings of the same run must agree');
166 }
167 // The drift starts at step 9; the checkpoint every 4 steps that first
168 // covers it is step 12.
169 if (!_report.contains('step 12')) {
170 throw StateError(
171 'the divergence should be reported at the first '
172 'checkpoint that covers the drift',
173 );
174 }
175 if (!_report.contains('still agrees: true')) {
176 throw StateError('a trace should read back exactly what it wrote');
177 }
178 }
179}