flame_3d

Description:

flame 3d

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>
copied to clipboard
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.frag
my_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.