flutter3d
Showcase Changelog 62 packages API reference

A Flame game that owns its 3D world

since 0.8.3 The Flame bridge

A Flame game with the HasFlutter3d mixin has its scene, camera, renderer and projector as fields of its own, and builds its 3D world the way it builds everything else: in code that runs once Flame has loaded it. Flutter3dFlameWidget then needs nothing but the game.

Step 1: Hand the game a device #

On its own the widget opens the device and the scene. Here the page already has both, so the game is opened on them directly, and the widget sees a game whose world is already open.

// The game is handed the page's device and scene; it builds the rest
// itself, in onOpen3d, once Flame has loaded it.
_game = _Yard(context.camera)..open3d(context.device, scene: _scene);

Step 2: Build the world in onOpen3d #

onOpen3d runs once, after the game has loaded and its world is open, whichever of the two came first. The crates, the layer that hears taps and the hitbox lines are all the game's own. createCamera3d hands it the page's orbiting camera, so that what it projects is what is drawn.

/// The game, owning its world: the page hands it a device and a scene, and
/// it adds the crates, the tap layer and the hitbox lines itself.
final class _Yard extends FlameGame with HasFlutter3d {
  _Yard(this._eye);

  final CameraNode _eye;
  final List<_Crate> crates = <_Crate>[];
  final Taps3dComponent taps = Taps3dComponent();

  /// The page's own orbiting camera, so the projector sees what is drawn.
  @override
  CameraNode createCamera3d() => _eye;

  @override
  void onOpen3d() {
    for (var i = 0; i < 3; i++) {
      final angle = i * 2.0 * math.pi / 3.0;
      crates.add(
        _Crate(
          device,
          scene,
          Vector2(2.4 * math.cos(angle), 2.4 * math.sin(angle)),
        ),
      );
    }
    addAll(<Component>[...crates, taps]);
    debugHitboxes3d = true;
  }
}

Step 3: A tap on what the camera shows #

Flame decides whether a point is inside a component on the plane the game plays on. Seen through a perspective camera, a crate is drawn somewhere else, larger near and smaller far, and Flame's own test misses it. Tap3dCallbacks asks whether the tap falls on the screen rectangle the crate's node covers, and Taps3dComponent gives each tap to the nearest crate under it. The crate flashes through its tint, which is its alone though the three share a material, and puts a "+1" over itself in Flame's layer at the point the projector gives.

/// A crate that hears a tap on what the camera shows of it, flashes, and
/// says so over itself.
final class _Crate extends Object3dComponent with Tap3dCallbacks {
  _Crate(GraphicsDevice device, Scene scene, Vector2 at)
    : super(
        node: MeshNode(
          DeviceMesh.upload(
            device,
            CuboidShape(size: Vector3.all(1.0)).build(),
          ),
          RenderMaterial(
            name: 'crate',
            baseColor: LinearColor.fromSrgb(0.8, 0.65, 0.4, 1.0),
          ),
        ),
        scene: scene,
        plane: BridgePlane.ground(),
        direction: SyncDirection.flameToScene,
        elevation: 0.5,
        position: at,
        size: Vector2.all(1.0),
        anchor: Anchor.center,
        children: <Component>[RectangleHitbox()],
      );

  @override
  void onTap3d(Vector2 screen) {
    // A red flash over the material the other crates share: the tint is
    // this crate's alone.
    tint = const LinearColor(1.0, 0.3, 0.25);
    add(
      TimerComponent(
        period: 0.25,
        removeOnFinish: true,
        onTick: () => tint = LinearColor.white,
      ),
    );
    // "+1" over the crate, placed through the projector, in Flame's layer.
    final game = findGame()! as HasFlutter3d;
    game.add(
      TextComponent(
        text: '+1',
        position: game.projector.toScreen(scenePosition)!,
        anchor: Anchor.center,
      )..addAll(<Component>[
        MoveByEffect(Vector2(0.0, -40.0), EffectController(duration: 0.8)),
        RemoveEffect(delay: 0.8),
      ]),
    );
  }
}

On the page a crate is tapped every second and a half through that same path. The green outlines are the crates' hitboxes, drawn in the scene where the crates are; Flame's debugMode would draw them flat on its own canvas.