flutter3d
Showcase Changelog 62 packages API reference

Keeping a Flame position and a flutter3d node in step: the source

since 0.7.0 The Flame bridge

Regions the guide quotes: live (line 102), shared-plane (line 148), scene-authoritative (line 153), flame-authoritative (line 175).

1/// `Object3dComponent` keeping a Flame `PositionComponent` and a flutter3d
2/// `SceneNode` at the same place, in both `SyncDirection`s.
3///
4/// Quoted by `flame_transform_bridge.md` and shown whole in the Source tab.
5library;
6
7import 'dart:math' as math;
8
9import 'package:flame/components.dart';
10import 'package:flame_flutter3d/flame_flutter3d.dart';
11import 'package:flutter/widgets.dart';
12import 'package:flutter3d/flutter3d.dart';
13import 'package:flutter3d_showcase/src/demo/demo.dart';
14import 'package:flutter3d_showcase/src/demo/flame_layer.dart';
16/// The `flame-transform-bridge` page: two markers on a floor, one led by its
17/// scene node and one by its Flame position. Its check moves each and reads
18/// the other back, (3, _, 2) as Flame (3, 2) and Flame (4, -1) as x = 4,
19/// z = -1.
20final class FlameTransformBridgeDemo extends ShowcaseDemo {
21 late final double _flamePositionX;
22 late final double _flamePositionY;
23 late final double _scenePositionX;
24 late final double _scenePositionZ;
26 late final DemoContext _context;
27 late final Scene _scene;
28 late final MeshNode _leader;
29 late final TransparentFlameGame _game;
30 late final Widget _body = flameOrbit(
31 _context,
32 Flutter3dFlameWidget(
33 game: _game,
34 camera: _context.camera,
35 existing: BorrowedRenderer(
36 device: _context.device,
37 renderer: _context.renderer,
38 ),
39 buildScene: (GraphicsDevice device) => _scene,
40 ),
41 );
42 double _clock = 0.0;
44 @override
45 void configureView(DemoContext context) {
46 context.orbit
47 ..distance = 8.0
48 ..pitch = 0.7
49 ..yaw = 0.5;
50 context.orbit.target.setValues(0.0, 0.0, 0.0);
51 }
53 MeshNode _cube(DemoContext context, String name, Vector4 color) => MeshNode(
54 DeviceMesh.upload(
55 context.device,
56 CuboidShape(size: Vector3(0.5, 0.5, 0.5)).build(),
57 ),
58 RenderMaterial(name: name, baseColor: _fromSrgb(color)),
59 name: name,
60 )..setPosition(0.0, 0.25, 0.0);
62 @override
63 Scene build(DemoContext context) {
64 _context = context;
65 final (double flameX, double flameY, double sceneX, double sceneZ) = _run(
66 context.device,
67 );
68 _flamePositionX = flameX;
69 _flamePositionY = flameY;
70 _scenePositionX = sceneX;
71 _scenePositionZ = sceneZ;
73 _leader = _cube(context, 'scene leads', Vector4(0.5, 0.7, 0.9, 1.0));
74 final MeshNode follower = _cube(
75 context,
76 'flame leads',
77 Vector4(0.9, 0.6, 0.3, 1.0),
78 );
79 _scene = Scene()
80 ..ambientColor = LinearColor(0.5, 0.55, 0.65)
81 ..ambientIntensity = 0.3 * LightNode.legacyUnit
82 ..add(
83 MeshNode(
84 DeviceMesh.upload(
85 context.device,
86 CuboidShape(size: Vector3(8.0, 0.1, 8.0)).build(),
87 ),
88 RenderMaterial(
89 name: 'floor',
90 baseColor: LinearColor.fromSrgb(0.36, 0.4, 0.38, 1.0),
91 ),
92 name: 'floor',
93 )..setPosition(0.0, -0.05, 0.0),
94 )
95 ..add(_leader)
96 ..add(follower)
97 ..add(
98 LightNode(name: 'sun', intensity: 2.5 * LightNode.legacyUnit)
99 ..setLocalForward(Vector3(-0.3, -0.6, -0.4)),
100 );
102 // The same two components as above, now in a running game: each frame
103 // Flame updates them and each copies one way. The map in the corner is
104 // Flame's own view of the ground plane, a metre to 24 pixels.
105 final BridgePlane plane = BridgePlane.ground();
106 final Object3dComponent reads = Object3dComponent(
107 node: _leader,
108 scene: _scene,
109 plane: plane,
110 )..add(flameDot(const Color(0xFF80B3E6)));
111 final Object3dComponent writes = Object3dComponent(
112 node: follower,
113 scene: _scene,
114 plane: plane,
115 direction: SyncDirection.flameToScene,
116 )..add(flameDot(const Color(0xFFE6994D)));
117 final FlameMinimap map = FlameMinimap()
118 ..world.addAll(<Component>[reads, writes]);
119 _game = TransparentFlameGame();
120 _game
121 // Before `writes`, so the position is set before it is copied.
122 ..add(_Drift(writes))
123 ..add(map)
124 ..add(flameCaption('blue: the node moves, Flame reads it'))
125 ..add(
126 flameCaption(
127 'orange: Flame moves, the node reads it',
128 at: Vector2(16.0, 40.0),
129 ),
130 );
131 return _scene;
132 }
134 @override
135 void update(DemoContext context, double dt) {
136 _clock += dt;
137 context.orbit.syncProjectionDepth(context.camera);
138 // The flutter3d side leads: it moves its own node round in a circle.
139 _leader.setPosition(
140 2.6 * math.cos(_clock * 0.8),
141 0.25,
142 2.6 * math.sin(_clock * 0.8),
143 );
144 }
146 static (double, double, double, double) _run(GraphicsDevice device) {
147 final scene = Scene();
148 // One ground plane, shared by both components below, so a Flame (x, y)
149 // and a flutter3d (x, height, y) mean the same point everywhere in this
150 // scene.
151 final plane = BridgePlane.ground();
153 // The flutter3d side moves; `SyncDirection.sceneToFlame` is the default,
154 // so `Object3dComponent` reads the node and writes the Flame component.
155 final node = MeshNode(
156 DeviceMesh.upload(
157 device,
158 CuboidShape(size: Vector3(0.4, 0.4, 0.4)).build(),
159 ),
160 RenderMaterial(
161 name: 'scene-authoritative',
162 baseColor: LinearColor.fromSrgb(0.5, 0.7, 0.9, 1.0),
163 ),
164 );
165 scene.add(node);
166 final sceneToFlame = Object3dComponent(
167 node: node,
168 scene: scene,
169 plane: plane,
170 );
171 node.setPosition(3.0, 0.0, 2.0);
172 sceneToFlame.update(1 / 60);
173 final Vector2 flamePosition = sceneToFlame.position;
175 // The Flame side moves instead; `SyncDirection.flameToScene` makes
176 // `Object3dComponent` read the Flame component and write the node.
177 final otherNode = MeshNode(
178 DeviceMesh.upload(
179 device,
180 CuboidShape(size: Vector3(0.4, 0.4, 0.4)).build(),
181 ),
182 RenderMaterial(
183 name: 'flame-authoritative',
184 baseColor: LinearColor.fromSrgb(0.9, 0.6, 0.3, 1.0),
185 ),
186 );
187 scene.add(otherNode);
188 final flameToScene = Object3dComponent(
189 node: otherNode,
190 scene: scene,
191 plane: plane,
192 direction: SyncDirection.flameToScene,
193 );
194 flameToScene.position = Vector2(4.0, -1.0);
195 flameToScene.update(1 / 60);
196 final Vector3 scenePosition = otherNode.readPosition();
198 return (flamePosition.x, flamePosition.y, scenePosition.x, scenePosition.z);
199 }
201 /// The Flame game the page runs, for a test that steps it without a window.
202 @visibleForTesting
203 TransparentFlameGame get game => _game;
205 @override
206 Widget? customBody(BuildContext buildContext, DemoContext context) => _body;
208 @override
209 void verify(Scene scene, FrameResult frame) {
210 if (frame.drawCalls < 1) {
211 throw StateError('the marker was not drawn');
212 }
213 // Compared as numbers, not read back out of a formatted report: a whole
214 // number double loses its trailing `.0` when a web backend formats it,
215 // and this repository's own showcase pages were bitten by exactly that
216 // once already.
217 if (_flamePositionX != 3.0 || _flamePositionY != 2.0) {
218 throw StateError(
219 'moving the node to (3, _, 2) on a ground plane should read back as '
220 'Flame position (3, 2), got ($_flamePositionX, $_flamePositionY)',
221 );
222 }
223 if (_scenePositionX != 4.0 || _scenePositionZ != -1.0) {
224 throw StateError(
225 'moving the Flame position to (4, -1) on a ground plane should read '
226 'back as scene x=4, z=-1, got x=$_scenePositionX, z=$_scenePositionZ',
227 );
228 }
229 }
232/// Moves a bridged component along a figure of eight, the way a Flame game
233/// moves anything of its own: by setting its position.
234final class _Drift extends Component {
235 _Drift(this._target);
237 final Object3dComponent _target;
238 double _t = 0.0;
240 @override
241 void update(double dt) {
242 super.update(dt);
243 _t += dt;
244 _target.position = Vector2(
245 2.6 * math.sin(_t * 0.8),
246 1.6 * math.sin(_t * 1.6),
247 );
248 }
251/// A `Vector4` holding a colour sRGB-encoded, as the linear colour it names.
252LinearColor _fromSrgb(Vector4 c) => LinearColor.fromSrgb(c.x, c.y, c.z, c.w);