flutter3d
Showcase Changelog 62 packages API reference

The level format: the source

since 0.4.2 Simulation, audio and XR

Regions the guide quotes: live (line 81), level (line 133), write (line 144), validate (line 147).

1/// The document a level is: brushes, entities and lights, and the validator
2/// that reports what is wrong with one before it is ever played.
3///
4/// Quoted by `level_format.md` and shown whole in the Source tab.
5library;
6
7import 'package:flutter3d/flutter3d.dart';
8import 'package:flutter3d_showcase/src/demo/demo.dart';
9import 'package:flutter3d_showcase/src/demo/scene_kit.dart';
10import 'package:flutter3d_sim/flutter3d_sim.dart';
12/// The `level-format` page: two brushes and a spawn in a level document. Its
13/// check is that every brush survives JSON and that overlapping brushes are
14/// reported.
15final class LevelFormatDemo extends ShowcaseDemo {
16 late final String _report;
18 /// The gap between the two brushes in metres, -2 to 2; below zero they
19 /// overlap and the validator says so.
20 double gap = -1.0;
22 /// Whether the level has a spawn point.
23 bool withSpawn = true;
25 bool _dirty = true;
26 late final MeshNode _first;
27 late final MeshNode _second;
28 late final MeshNode _spawn;
29 late final List<MeshNode> _issues;
31 static const int _lamps = 6;
33 @override
34 void configureView(DemoContext context) {
35 context.orbit
36 ..distance = 13.0
37 ..pitch = 0.9
38 ..yaw = 0.0;
39 context.orbit.target.setValues(1.5, 0.0, 1.0);
40 }
42 @override
43 Scene build(DemoContext context) {
44 _report = _run();
45 _first = blockNode(
46 context,
47 'brush 1',
48 Vector3(4.0, 2.0, 4.0),
49 Vector4(0.55, 0.65, 0.8, 1.0),
50 );
51 _second = blockNode(
52 context,
53 'brush 2',
54 Vector3(4.0, 1.9, 4.0),
55 Vector4(0.8, 0.65, 0.5, 1.0),
56 );
57 _spawn = ballNode(context, 'spawn', 0.35, Vector4(0.4, 0.9, 0.5, 1.0));
58 _issues = <MeshNode>[
59 for (var i = 0; i < _lamps; i++)
60 ballNode(
61 context,
62 'issue $i',
63 0.25,
64 Vector4(0.9, 0.3, 0.3, 1.0),
65 at: Vector3(-2.5 + i * 0.8, 0.3, 4.5),
66 ),
67 ];
68 return sceneOf(<SceneNode>[
69 floorNode(context, width: 16.0, depth: 12.0),
70 _first,
71 _second,
72 _spawn,
73 ..._issues,
74 ]);
75 }
77 @override
78 void update(DemoContext context, double dt) {
79 if (!_dirty) return;
80 _dirty = false;
81 // The level of the first step, with the second brush slid along by the
82 // slider (a negative gap is an overlap) and the spawn optional, written to
83 // JSON, read back and validated.
84 final Level level = Level(
85 name: 'sample',
86 brushes: <Brush>[
87 Brush(center: WorldPosition(0, 0, 0), size: Vector3(4, 2, 4)),
88 Brush(center: WorldPosition(4.0 + gap, 0, 0), size: Vector3(4, 2, 4)),
89 ],
90 entities: <EntityDef>[
91 if (withSpawn) EntityDef(type: 'spawn', name: 'start'),
92 ],
93 );
94 final Level reread = Level.fromJson(level.toJson());
95 final List<LevelIssue> issues = LevelValidator(
96 registry: EntityRegistry(const <EntityKind>[]),
97 ).validate(reread);
98 _first.setPosition(0.0, 1.0, 0.0);
99 _second.setPosition(4.0 + gap, 0.95, 0.0);
100 _spawn.isVisible = withSpawn;
101 _spawn.setPosition(0.0, 2.35, 0.0);
102 for (var i = 0; i < _lamps; i++) {
103 _issues[i].isVisible = i < issues.length;
104 }
105 }
107 @override
108 List<DemoControl> controls(DemoContext context) => <DemoControl>[
109 SliderControl(
110 'Gap between the brushes',
111 min: -2.0,
112 max: 2.0,
113 value: () => gap,
114 onChanged: (double v) {
115 gap = v;
116 _dirty = true;
117 },
118 format: (double v) => v < 0
119 ? 'overlap ${(-v).toStringAsFixed(1)} m'
120 : '${v.toStringAsFixed(1)} m',
121 ),
122 ToggleControl(
123 'A spawn point',
124 value: () => withSpawn,
125 onChanged: (bool v) {
126 withSpawn = v;
127 _dirty = true;
128 },
129 ),
130 ];
132 static String _run() {
133 // Two brushes that overlap by a metre, which nothing in this format
134 // forbids outright but which the validator flags as worth a look.
135 final level = Level(
136 name: 'sample',
137 brushes: <Brush>[
138 Brush(center: WorldPosition(0, 0, 0), size: Vector3(4, 2, 4)),
139 Brush(center: WorldPosition(3, 0, 0), size: Vector3(4, 2, 4)),
140 ],
141 entities: <EntityDef>[EntityDef(type: 'spawn', name: 'start')],
142 );
144 final json = level.toJson();
145 final reread = Level.fromJson(json);
147 final validator = LevelValidator(
148 registry: EntityRegistry(const <EntityKind>[]),
149 );
150 final issues = validator.validate(reread);
152 return '${reread.brushes.length} brushes round-tripped through JSON\n'
153 '${issues.length} issue(s): ${issues.map((LevelIssue i) => i.message).join(' | ')}';
154 }
156 @override
157 void verify(Scene scene, FrameResult frame) {
158 if (frame.drawCalls < 1) {
159 throw StateError('the level marker was not drawn');
160 }
161 if (!_report.contains('2 brushes round-tripped')) {
162 throw StateError('every brush should survive a trip through JSON');
163 }
164 if (_report.contains('0 issue(s)')) {
165 throw StateError(
166 'two overlapping brushes should be reported by the validator',
167 );
168 }
169 }