Adds 3D support for Flame using the Flutter GPU.
flame_3d
This package provides an experimental implementation of 3D support for Flame. The main focus is to explore the potential capabilities of 3D for Flame while providing a familiar API to existing Flame developers.
Supported platforms:
| Platform | Supported |
|---|---|
| Android | ❌ |
| iOS | ❌ |
| macOS | ✅ |
| Windows | ❌ |
| Linux | ❌ |
| Web | ❌ |
Prologue
STOP, we know you are hyped up and want to start coding some funky 3D stuff but we first have to set your expectations and clarify some things. So turn down your music, put away the coffee and make some tea instead because you have to do some reading first!
This package provides 3D support for Flame but it depends on the still experimental Flutter GPU, which in turn depends on Impeller.
Because of that, this package is also highly experimental. Our long term goal is to
eventually merge this branch into Flame's main, but we currently need to depend on Flutter's main
(Flame depends on stable). For more information on this, check out our
Roadmap.
This package does not guarantee that it will follow correct semver versioning rules, nor does it assure that its APIs wont break. Be ready to constantly have to refactor your code if you are planning on using this package, and potentially to have to contribute with improvements and fixes. Please do not use this for production environments.
Documentation and tests might be lacking for quite a while because of the potential constant changes of the API. Where possible, we will try to provide in-code documentation and code examples to help developers but our main goal for now is to enable the usage of 3D rendering within a Flame ecosystem.
Prerequisites
In order to use flame_3d, you will need to ensure a few things. First of all, you need to be on
the main channel of Flutter, and on MacOS, the only currently supported platform.
Then, you need to enable Impeller; to do that, add the following to the
Info.plist in your macos/ directory:
<dict>
...
<key>FLTEnableImpeller</key>
<true/>
</dict>
Now everything is set up you can start doing some 3D magic! You can check out the example to see how you can set up a simple 3D environment using Flame.
Also check out the flame_3d_extras package for more
utilities and helpers not yet merged into flame_3d.
Building shaders
If you are using the SpatialMaterial provided by flame_3d, you do not need to worry about shaders.
That being said, you can write your own shaders and use them on custom materials.
Currently, Flutter does not do the bundling of shaders for us so this package provides a simple
Dart script. Create your fragment and vertex shader in a shaders directory,
make sure the file names are identical. Like so:
my_custom_shader.fragmy_custom_shader.vert
You can then run dart pub run flame_3d:build_shaders to bundle the shaders. They will
automatically be placed in assets/shaders.
You can check out the default shaders if you want to have some examples.
Contributing
Have you found a bug or have a suggestion of how to enhance the 3D APIs? Open an issue and we will take a look at it as soon as possible.
Do you want to contribute with a PR? PRs are always welcome, just make sure to create it from the correct branch (main) and follow the checklist which will appear when you open the PR.
For bigger changes, or if in doubt, make sure to talk about your contribution to the team. Either via an issue, GitHub discussion, or reach out to the team using the Discord server.