feat: Add flame_3d_component, a Component3D backed by flutter_scene

.github/.cspell/flame_dictionary.txt

@@ -5,6 +5,7 @@ Audioplayers # A Flutter plugin to play multiple simultaneously audio files http
 BGUG # Break Guns Using Gems, a game by BlueFire https://github.com/bluefireteam/bgug
 Bodymovin # An After Effects extension to export Lottie animations https://aescripts.com/bodymovin/
 emberquest # Ember Quest, our platformer tutorial game
+fscene # The website of Flutter Scene https://fscene.dev
 Hermione # A character from the book Harry Potter
 Kenobi # Eminent Jedi Master, General of the Republic Army, Obi-Wan Kenobi
 Nakama # An open-source server designed to power modern games and apps https://github.com/Allan-Nava/nakama-flutter

.github/.cspell/people_usernames.txt

@@ -13,6 +13,7 @@ Klingsbo # github.com/spydon
 Kornél # github.com/kornellapu
 lapu # Artist of reference art (basic shader tutorial)
 Lapu # github.com/kornellapu
+Lousberg # kaylousberg.itch.io
 luan # github.com/luanpotter
 luanpotter # github.com/luanpotter
 Lukas # github.com/spydon
@@ -26,3 +27,4 @@ Tellinghuisen # Author of Statistical Error Propagation (2001)
 videon # github.com/markvideon
 wolfenrain # github.com/wolfenrain
 xaha # github.com/xvrh
+Zuno # pixelgameart.org

.github/workflows/cicd.yml

@@ -30,7 +30,9 @@ jobs:
           flutter-version: ${{env.FLUTTER_MIN_VERSION}}
       - uses: bluefireteam/melos-action@v3
       # flame_3d always requires the latest stable, since flutter_gpu is still
-      # unstable, so it is only analyzed in the analyze-latest job.
+      # unstable, and flame_3d_component requires the Flutter version that
+      # flutter_scene needs, so they are only analyzed in the analyze-latest
+      # job (the glob covers both).
       - name: "Analyze with lowest supported version"
         run: melos exec --ignore="flame_3d*" -- dart analyze --fatal-infos .
 

README.md

@@ -83,6 +83,8 @@ helpers, in order to make integrations seamless.
 
 Flame officially provides bridge libraries to the following packages:
 
+- [flame_3d_component][flame_3d_component] for [flutter_scene][flutter_scene]: Add 3D
+  components to the component tree.
 - [flame_audio][flame_audio] for [AudioPlayers][audioplayers]: Play multiple audio files
   simultaneously.
 - [flame_behavior_tree][flame_behavior_tree] for [behavior_tree][behavior_tree]: Drive game logic
@@ -220,6 +222,8 @@ via an issue, GitHub discussion, or reach out to the team either using the
 [flame_network_assets]: https://github.com/flame-engine/flame/tree/main/packages/flame_network_assets
 [flame_rive]: https://github.com/flame-engine/flame/tree/main/packages/flame_rive
 [rive]: https://rive.app/
+[flame_3d_component]: https://github.com/flame-engine/flame/tree/main/packages/flame_3d_component
+[flutter_scene]: https://github.com/bdero/flutter_scene
 [flame_svg]: https://github.com/flame-engine/flame/tree/main/packages/flame_svg
 [flutter_svg]: https://github.com/dnfield/flutter_svg
 [flame_texturepacker]: https://github.com/flame-engine/flame/tree/main/packages/flame_texturepacker

doc/bridge_packages/bridge_packages.md

@@ -5,6 +5,11 @@
 Uses Flutter GPU / Impeller low-level level access to provide an ergonomic and **very experimental**
 3D rendering engine on top of Flame.
 
+:::{package} flame_3d_component
+
+Add 3D components to the Flame component tree (bridge package for [flutter_scene]).
+:::
+
 :::{package} flame_audio
 
 Play multiple audio files simultaneously (bridge package for [AudioPlayers]).
@@ -110,11 +115,13 @@ Load Typled sprite atlases with edge-repeated padding (bridge package for [Typle
 [Tiled]: https://www.mapeditor.org/
 [Typled]: https://pub.dev/packages/typled
 [flutter_svg]: https://github.com/dnfield/flutter_svg
+[flutter_scene]: https://github.com/bdero/flutter_scene
 
 
 ```{toctree}
 :hidden:
 
+flame_3d_component          <flame_3d_component/flame_3d_component.md>
 flame_audio                 <flame_audio/flame_audio.md>
 flame_behaviors             <flame_behaviors/flame_behaviors.md>
 flame_bloc                  <flame_bloc/flame_bloc.md>

doc/bridge_packages/flame_3d_component/component_3d.md

@@ -0,0 +1,121 @@
+# Flame 3D Component
+
+flame_3d_component lets you put a 3D object, rendered by the
+[flutter_scene](https://pub.dev/packages/flutter_scene) engine, into the regular 2D component tree of
+a Flame game. The `Component3D` is a `PositionComponent`, so it can be positioned, sized, scaled,
+rotated, anchored, and layered together with your sprites and other 2D components.
+
+All the 3D rendering is done by [Flutter Scene](https://fscene.dev), the realtime 3D engine for
+Flutter created and maintained by [Brandon DeRosier (bdero)](https://github.com/bdero). Big thanks
+to him for building it. The engine's own documentation, guides, and API reference live at
+[fscene.dev](https://fscene.dev), and everything there applies to the scene inside a `Component3D`.
+
+
+## Scope
+
+This package is for when you want a 3D object in an otherwise 2D Flame game, for example a spinning
+model in the menu, a 3D character on top of a 2D background, or a dice rolling across a board.
+
+It is not a 3D game engine and it is not meant to replace one. The scene graph, cameras, materials,
+lighting, animation, model loading, and physics are all handled by flutter_scene. This package only
+draws a flutter_scene scene into a Flame component. If you are building a full 3D game, use
+flutter_scene directly, or the experimental [flame_3d](https://pub.dev/packages/flame_3d) package,
+which is a separate effort with a different purpose.
+
+
+## Installation
+
+3D scene support is provided by the `flame_3d_component` bridge package, be sure to put it in your pubspec
+file to use it.
+
+If you want to know more about the installation visit
+[flame_3d_component on pub.dev](https://pub.dev/packages/flame_3d_component/install).
+
+flutter_scene renders through Flutter GPU, which has to be enabled on every native platform. While
+developing you can pass a flag:
+
+```sh
+flutter run --enable-flutter-gpu
+```
+
+See the [flutter_scene README](https://pub.dev/packages/flutter_scene#enable-flutter-gpu) for how to
+enable it permanently per platform. On the web nothing needs to be enabled.
+
+
+## How to use flame_3d_component
+
+Import `package:flame_3d_component/flame_3d_component.dart`, which also re-exports the
+flutter_scene API, and add a `Component3D` to your game. Everything added to its `root` node is
+rendered through the component's `camera`:
+
+```dart
+class SpinningCube extends Component3D {
+  SpinningCube()
+    : super(
+        size: Vector2(400, 300),
+        camera: PerspectiveCamera(position: Vector3(2, 2, -4)),
+      );
+
+  late final Node cube;
+  double _rotation = 0;
+
+  @override
+  Future<void> onLoad() async {
+    await super.onLoad();
+    cube = Node(
+      mesh: Mesh(CuboidGeometry(Vector3.all(1)), PhysicallyBasedMaterial()),
+    );
+    root.add(cube);
+  }
+
+  @override
+  void update(double dt) {
+    super.update(dt);
+    _rotation += dt;
+    cube.rotation = Quaternion.axisAngle(Vector3(0, 1, 0), _rotation);
+  }
+}
+```
+
+Geometry and materials need the engine's shader libraries, so create them after `super.onLoad()`
+has completed, like in the example above. The component's `onLoad` waits for
+`Scene.initializeStaticResources`.
+
+Models can be loaded with the regular flutter_scene loaders, for example `loadScene` for assets
+converted by the flutter_scene asset pipeline or `Node.fromGlbAsset` for a glTF binary that is
+parsed at runtime:
+
+```dart
+final model = await Node.fromGlbAsset('assets/models/dash.glb');
+root.add(model);
+```
+
+The scene's clock follows Flame's clock: the `dt` passed to the component's `update` is handed to
+the scene right before it renders, so pausing the game also pauses animations and node components
+inside the scene.
+
+An existing `Scene` can also be shared with the component, which is useful when a scene is built
+outside of the component tree:
+
+```dart
+final sceneComponent = Component3D(
+  scene: myScene,
+  camera: myCamera,
+  size: Vector2(400, 300),
+);
+```
+
+
+## Name clashes
+
+Both Flame and flutter_scene define classes named `Component` and `Sprite`, so
+`flame_3d_component` does not re-export those two. Import `package:flutter_scene/scene.dart`
+directly if you need the flutter_scene versions, for example to attach a flutter_scene component
+to a node.
+
+
+## Resolution
+
+By default the scene is rasterized at the device pixel ratio multiplied by the current zoom of the
+canvas, so it stays sharp when the Flame camera zooms in. Pass `pixelRatio` to the component to
+override this, for example to render at a lower resolution for performance.

doc/bridge_packages/flame_3d_component/flame_3d_component.md

@@ -0,0 +1,5 @@
+# flame_3d_component
+
+```{toctree}
+Overview    <component_3d.md>
+```

packages/flame_3d_component/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1.0
+
+ - **FEAT**: Add the `flame_3d_component` bridge package with a `Component3D` that renders a `flutter_scene` scene inside the Flame component tree.

packages/flame_3d_component/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Blue Fire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

packages/flame_3d_component/README.md

@@ -0,0 +1,55 @@
+<!-- markdownlint-disable MD013 -->
+<p align="center">
+  <a href="https://flame-engine.org">
+    <img alt="flame" width="200px" src="https://user-images.githubusercontent.com/6718144/101553774-3bc7b000-39ad-11eb-8a6a-de2daa31bd64.png">
+  </a>
+</p>
+
+<p align="center">
+Adds 3D components (rendered by the <a href="https://github.com/bdero/flutter_scene">flutter_scene</a> engine) to the component tree of your <a href="https://github.com/flame-engine/flame">Flame</a> games.
+</p>
+
+<p align="center">
+  <a title="Pub" href="https://pub.dev/packages/flame_3d_component" ><img src="https://img.shields.io/pub/v/flame_3d_component.svg?style=popout" /></a>
+  <a title="Test" href="https://github.com/flame-engine/flame/actions?query=workflow%3Acicd+branch%3Amain"><img src="https://github.com/flame-engine/flame/actions/workflows/cicd.yml/badge.svg?branch=main&event=push"/></a>
+  <a title="Discord" href="https://discord.gg/pxrBmy4"><img src="https://img.shields.io/discord/509714518008528896.svg"/></a>
+  <a title="Melos" href="https://github.com/invertase/melos"><img src="https://img.shields.io/badge/maintained%20with-melos-f700ff.svg"/></a>
+</p>
+
+---
+<!-- markdownlint-enable MD013 -->
+
+<!-- markdownlint-disable-next-line MD002 -->
+
+# flame_3d_component
+
+Package to add 3D objects, rendered by
+[flutter_scene](https://pub.dev/packages/flutter_scene), to the regular 2D
+component tree of a Flame game.
+
+All the 3D rendering is done by [Flutter Scene](https://fscene.dev), the
+realtime 3D engine for Flutter created and maintained by
+[Brandon DeRosier (bdero)](https://github.com/bdero). Big thanks to him for
+building it, and for the Flutter GPU work that makes it possible. Head over to
+[fscene.dev](https://fscene.dev) for the engine's own documentation, guides,
+and API reference.
+
+
+## What this package is, and what it is not
+
+This package is for when you want a 3D object in an otherwise 2D Flame game: a
+spinning model in the menu, a 3D character on top of a 2D background, a dice
+rolling across a board, a product preview inside your game UI. The `Component3D`
+is a normal `PositionComponent`, so it is positioned, sized, scaled, rotated,
+anchored, and layered exactly like a sprite, and it participates in Flame's
+update and render loop like any other component.
+
+It is **not** a 3D game engine and it is not meant to replace one. All of the
+3D work, such as the scene graph, cameras, materials, lighting, animation,
+model loading, and physics, is done by flutter_scene. This package only draws a
+flutter_scene scene into a Flame component, nothing more. If you are building a
+full 3D game, use flutter_scene directly, or the experimental
+[flame_3d](https://pub.dev/packages/flame_3d) package, which is a separate
+effort with a different purpose.
+
+More [here](https://docs.flame-engine.org/main/bridge_packages/flame_3d_component/flame_3d_component.html).

packages/flame_3d_component/analysis_options.yaml

@@ -0,0 +1,15 @@
+include: package:flame_lint/analysis_options_with_dcm.yaml
+
+linter:
+  rules:
+    - public_member_api_docs
+
+analyzer:
+  exclude:
+    - build/**
+    - android/**
+    - ios/**
+    - web/**
+    - windows/**
+    - macos/**
+    - linux/**

packages/flame_3d_component/example/.gitignore

@@ -0,0 +1,49 @@
+linux/
+macos/
+web/
+windows/
+
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.buildlog/
+.history
+.svn/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/
+
+# Flutter/Dart/Pub related
+**/doc/api/
+**/ios/Flutter/.last_build_id
+.dart_tool/
+.flutter-plugins
+.flutter-plugins-dependencies
+.packages
+.pub-cache/
+.pub/
+/build/
+
+# Symbolication related
+app.*.symbols
+
+# Obfuscation related
+app.*.map.json
+
+# Android Studio will place build artifacts here
+/android/app/debug
+/android/app/profile
+/android/app/release

packages/flame_3d_component/example/README.md

@@ -0,0 +1,20 @@
+# Example of a 3D object between 2D components
+
+An animated 3D skeleton, loaded from a glTF file and rendered by
+`flutter_scene` through a `Component3D`, placed between two regular Flame
+layers: a `ParallaxComponent` scrolling behind it and a
+`SpriteAnimationComponent` walking back and forth in front of it.
+
+Rendering goes through Flutter GPU, which has to be enabled on native
+platforms:
+
+```sh
+flutter run --enable-flutter-gpu
+```
+
+On the web no flag is needed.
+
+The skeleton model is from the
+[KayKit Skeletons](https://kaylousberg.itch.io/kaykit-skeletons) pack by Kay
+Lousberg (CC0), and the parallax art is by Luis Zuno (CC0), see
+`assets/images/parallax/license.txt`.

packages/flame_3d_component/example/analysis_options.yaml

@@ -0,0 +1,15 @@
+include: package:flame_lint/analysis_options_with_dcm.yaml
+
+linter:
+  rules:
+    public_member_api_docs: false
+
+analyzer:
+  exclude:
+    - build/**
+    - android/**
+    - ios/**
+    - web/**
+    - windows/**
+    - macos/**
+    - linux/**

packages/flame_3d_component/example/assets/images/parallax/license.txt

@@ -0,0 +1,6 @@
+Artwork created by Luis Zuno (@ansimuz)
+
+License (CC0) You can copy, modify, distribute and perform the work, even for commercial purposes, all without asking permission: http://creativecommons.org/publicdomain/zero/1.0/
+
+Get more resources at pixelgameart.org, Spread the word!
+