flame_3d 0.1.0-dev.1

Experimental 3D support for the Flame Engine

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. The Flutter GPU is currently not shipped with Flutter so this package wont work without following the prerequisites steps.

Because we depend on Flutter GPU this package is also highly experimental. Our long term goal is to eventually deprecate this package and integrate it into the core flame package, for more information on this see the Roadmap.

This package does not guarantee that it will follow correct semver versioning rules nor does it assure that it's APIs wont break. Be ready to constantly have to refactor your code if you are planning on using this package in a semi-production environment, which we do not recommend.

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

Before you can get started with using this package a few steps have to happen first. Step one is switching to a specific commit on the Flutter tooling. Because this package is still experimental some of the features it requires are still being worked on from the Flutter side.

So to make sure you are using the same build that we use while developing you have to manually checkout a specific Flutter build. Thankfully we were able to simplify that process into a one-liner:

cd $(dirname $(which flutter)) && && git fetch && git checkout bcdd1b2c481bca0647beff690238efaae68ca5ac -q && echo "Engine commit: $(cat internal/engine.version)" && cd - >/dev/null

This will check out the GIT repo of your Flutter installation to the specific commit that we require and also return the commit SHA of the Flutter Engine that it was build with. We need for step two.

Step two is setting up the Flutter GPU. You can follow the steps described in the Flutter Wiki. The engine commit that you should use is the one we got in step one.

Once you have cloned the Flutter engine you can add the flutter_gpu as an override dependency to your pubspec.yaml or in a pubspec_overrides.yaml file:

dependency_overrides:
  flutter_gpu:
    path: <path_to_the_cloned_flutter_engine_directory>/lib/gpu

Step three would be to enable impeller for the macOS platform, 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.

Building shaders

You can write your own shaders and use them on 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.