flutter3d
Showcase Changelog 62 packages API reference

A flow field: the source

since 0.4.1 or earlier Simulation, audio and XR

Regions the guide quotes: live (line 55), aim (line 122), follow (line 129), grid (line 164), field (line 168), descend (line 171).

1/// One sweep from a goal, read by every agent in the level as the direction
2/// to walk from wherever it stands.
3///
4/// Quoted by `flow_field.md` and shown whole in the Source tab.
5library;
6
7import 'dart:math' as math;
8
9import 'package:flutter3d/flutter3d.dart';
10import 'package:flutter3d_showcase/src/demo/demo.dart';
11import 'package:flutter3d_showcase/src/demo/scene_kit.dart';
12import 'package:flutter3d_sim/flutter3d_sim.dart';
14/// The `flow-field` page: agents walking a flow field swept from a goal.
15/// Its check is that open floor always has a direction and that it points
16/// towards the goal.
17final class FlowFieldDemo extends ShowcaseDemo {
18 late final String _report;
20 /// Which goal the field is swept from, an index into the four the choice
21 /// names; moved every twelve seconds while [cycling].
22 int goal = 0;
24 /// Whether the goal moves on its own; picking one stops it.
25 bool cycling = true;
27 late final NavGrid _grid;
28 late final FlowField _field;
29 late final MeshNode _beacon;
30 final List<MeshNode> _agents = <MeshNode>[];
31 final List<Vector3> _starts = <Vector3>[];
32 double _clock = 0.0;
33 int _shown = -1;
35 static const List<(double, double)> _goals = <(double, double)>[
36 (18.0, 17.0),
37 (18.0, 3.0),
38 (3.0, 17.0),
39 (3.0, 3.0),
40 ];
42 @override
43 void configureView(DemoContext context) {
44 context.orbit
45 ..distance = 26.0
46 ..pitch = 1.0
47 ..yaw = 0.0;
48 context.orbit.target.setValues(10.0, 0.0, 10.0);
49 }
51 @override
52 Scene build(DemoContext context) {
53 _report = _run();
55 // A floor with two walls across it, each leaving a gap at one end: an
56 // agent has to snake round them, and the field knows how.
57 _grid = NavGrid.bake(<Brush>[
58 Brush(center: WorldPosition(10, 0, 10), size: Vector3(20, 1, 20)),
59 Brush(center: WorldPosition(7, 2, 6), size: Vector3(1, 4, 12)),
60 Brush(center: WorldPosition(13, 2, 14), size: Vector3(1, 4, 12)),
61 ], cellSize: 0.5);
62 _field = FlowField(_grid);
64 final math.Random random = math.Random(4);
65 for (var i = 0; i < 16; i++) {
66 final Vector3 start = Vector3(
67 1.0 + 4.0 * random.nextDouble(),
68 0.5,
69 1.0 + 18.0 * random.nextDouble(),
70 );
71 _starts.add(start);
72 _agents.add(
73 ballNode(
74 context,
75 'agent $i',
76 0.25,
77 Vector4(0.9, 0.6, 0.3, 1.0),
78 at: start + Vector3(0.0, 0.25, 0.0),
79 ),
80 );
81 }
82 _beacon = blockNode(
83 context,
84 'goal',
85 Vector3(0.5, 2.0, 0.5),
86 Vector4(0.95, 0.85, 0.3, 1.0),
87 );
88 return sceneOf(<SceneNode>[
89 blockNode(
90 context,
91 'floor',
92 Vector3(20.0, 0.5, 20.0),
93 Vector4(0.34, 0.38, 0.36, 1.0),
94 at: Vector3(10.0, 0.25, 10.0),
95 ),
96 blockNode(
97 context,
98 'wall 1',
99 Vector3(1.0, 1.5, 12.0),
100 Vector4(0.55, 0.5, 0.5, 1.0),
101 at: Vector3(7.0, 1.25, 6.0),
102 ),
103 blockNode(
104 context,
105 'wall 2',
106 Vector3(1.0, 1.5, 12.0),
107 Vector4(0.55, 0.5, 0.5, 1.0),
108 at: Vector3(13.0, 1.25, 14.0),
109 ),
110 _beacon,
111 ..._agents,
112 ]);
113 }
115 @override
116 void update(DemoContext context, double dt) {
117 _clock += dt;
118 if (cycling) goal = (_clock ~/ 12.0) % _goals.length;
119 final (double gx, double gz) = _goals[goal];
120 if (goal != _shown) {
121 _shown = goal;
122 // A new goal is one rebuild; every agent then follows the same table.
123 _field.rebuild(Vector3(gx, 0.5, gz));
124 _beacon.setPosition(gx, 1.5, gz);
125 }
126 final Vector3 direction = Vector3.zero();
127 for (var i = 0; i < _agents.length; i++) {
128 final Vector3 at = _agents[i].readPosition()..y = 0.5;
129 // One step down the table from wherever the agent stands.
130 if (_field.descend(at, direction)) {
131 // A long frame (a tab left in the background) must not fling an agent
132 // out of the level in one step.
133 at.addScaled(direction, 3.0 * math.min(dt, 0.05));
134 } else {
135 // Not on the floor any more: back to where it started.
136 at.setFrom(_starts[i]);
137 }
138 if ((at.x - gx).abs() + (at.z - gz).abs() < 1.8) {
139 at.setFrom(_starts[i]);
140 }
141 _agents[i].setPosition(at.x, 0.75, at.z);
142 }
143 }
145 @override
146 List<DemoControl> controls(DemoContext context) => <DemoControl>[
147 ChoiceControl(
148 'Goal',
149 options: const <String>['far corner', 'near corner', 'far side', 'start'],
150 index: () => goal,
151 onChanged: (int i) {
152 cycling = false;
153 goal = i;
154 },
155 ),
156 ToggleControl(
157 'Move the goal',
158 value: () => cycling,
159 onChanged: (bool v) => cycling = v,
160 ),
161 ];
163 static String _run() {
164 final grid = NavGrid.bake(<Brush>[
165 Brush(center: WorldPosition(5, 0, 5), size: Vector3(10, 1, 10)),
166 ], cellSize: 0.5);
168 final field = FlowField(grid);
169 field.rebuild(Vector3(9.0, 0.0, 9.0));
171 final from = Vector3(1.0, 0.0, 1.0);
172 final direction = Vector3.zero();
173 final found = field.descend(from, direction);
174 final distance = field.walkingDistanceTo(from);
176 return 'a step from (1, 1) points towards '
177 '(${direction.x.toStringAsFixed(2)}, ${direction.z.toStringAsFixed(2)}), '
178 'found: $found\n'
179 'walking distance to the goal: ${distance?.toStringAsFixed(2)} m';
180 }
182 @override
183 void verify(Scene scene, FrameResult frame) {
184 if (frame.drawCalls < 1) {
185 throw StateError('the agent marker was not drawn');
186 }
187 if (!_report.contains('found: true')) {
188 throw StateError(
189 'an open floor should always have a direction to the goal',
190 );
191 }
192 // The direction from (1, 1) towards (9, 9) points diagonally: both
193 // components positive.
194 if (_report.contains('(-') || _report.contains(', -')) {
195 throw StateError(
196 'the direction towards a goal up and to the right '
197 'should point up and to the right',
198 );
199 }
200 }