flutter3d

An independent implementation of a 3D engine on Flutter GPU, a game engine on top of it, and four games of different genres built from both. The games are there because building them is the only honest test that the engine is one. flutter3d is not a fork, a binding or a wrapper around another engine, and it is not affiliated with the Flutter team.

On pub.dev: thirty-nine packages, published by pleion.dev. Start with flutter3d and a backend. Thirty-six of them are the 0.8.0 set, one number for all, so any ^0.8.0 resolves against every other; pad_input and pointer_lock keep a line of their own at 0.4.2, since neither names a sibling. Coming from 0.6.0, several packages were folded into others, and doc/boundary-0.7.0.md lists which import lines move. To work on the engine itself, see Running, CONTRIBUTING.md and SECURITY.md.

The documentation at https://flutter3d.pleion.dev has guides, tutorials for three of the four genres, and the generated API reference. The model editor runs in a browser at https://models.pleion.dev, with its own tutorial.

The package boundaries carry weight. flutter3d_sim depends on neither flutter3d nor Flutter, because simulation, input and collision have nothing to say about how a frame is drawn. The same cut runs the other way, and a genre is a package too. flutter3d_game_shooter holds what only a shooter wants, so a platformer or a racing game inherits none of its vocabulary, and three of the scans in tool/structure.dart enforce that rather than leaving it to habit. This split is what lets a plain unit test reach the parts that fail quietly: a collision that passes through a wall once in a thousand steps, a jump that is a different height on a faster monitor, a press swallowed at a low frame rate. flutter3d_app is where a level meets the renderer for any application, and flutter3d_game is where a game's simulation does; an application supplies only what its own game looks like.

A pub workspace, so one resolve covers everything:

flutter pub get

# Required before the first run, after every Flutter SDK change, and after every
# edit to a shader. The bundle format is tied to the SDK version, the built
# bundle is gitignored so a fresh checkout has none, and a `.frag` edited without
# rebuilding changes nothing an application loads.
(cd packages/flutter3d_impeller && ./tool/build_shaders.sh)

# The second bundle: the one the engine demo loads at runtime rather than links.
# The demo's pubspec declares it as an asset, so without this the demo and the
# golden set stop at "No file or variants found for asset" before anything runs.
(cd packages/flutter3d/example && ./tool/build_shaders.sh)

# The shooter
(cd apps/flutter3d_demo_dungeon && flutter run -d macos)

# The platformer
(cd apps/flutter3d_demo_platformer && flutter run -d macos)

# The racing game
(cd apps/flutter3d_demo_racing && flutter run -d macos)

# The engine demo
(cd packages/flutter3d/example && flutter run -d macos)

In a browser it is the same command with a different device, and no shader bundle: the WebGL backend translates the same GLSL and the browser compiles it. A build that wants WebGPU instead asks for it with --dart-define=FLUTTER3D_WEBGPU=true, and the probe falls back to WebGL2 where the browser has no adapter to give. WebGPU is off by default for two reasons. A build that can try both backends ships both, which costs 376,649 bytes of main.dart.js measured on the strategy demo. And WebGL2 is the browser backend three shipped games have been looked at on.

(cd apps/flutter3d_demo_dungeon && flutter run -d chrome)

# What the demos are published as. --wasm builds the JavaScript output beside
# the WebAssembly one and the loader picks; the games are the one thing here
# that spends its frame budget in Dart rather than in a driver.
(cd apps/flutter3d_demo_dungeon && flutter build web --wasm --release)

Flutter GPU and Impeller are enabled per application through Info.plist, so every app in this repository sets FLTEnableFlutterGPU and FLTEnableImpeller for itself. A new one that skips them fails to initialise the shader library and renders nothing. Neither setting means anything to a browser build, which reaches WebGL2 through flutter3d_app instead.

tool/ci.sh          # everything a machine can check: shaders, analyze, all tests

Or one package at a time:

(cd packages/flutter3d_game && flutter test)
(cd packages/flutter3d_physics && dart test)   # plain Dart, no Flutter needed

There are 10789 tests across forty-two packages and nine applications. The only ones that need a GPU are the Impeller half of the golden set. The other half is rendered by the software backend, which is what makes 78 scenes checkable in a headless run.

Several steps run in a browser. flutter test --platform chrome covers the two web backends, flutter3d_app's browser half and the browser half of pointer_lock, and one step compiles a game to WebAssembly, since a platform counts as supported here only if its build actually runs. The WebGPU backend gets something from this that no other backend does: Chrome has a real WebGPU device inside flutter test, so the WebGPU conformance run is a test rather than an application somebody watches.

ARCHITECTURE.md, section 13, describes how the tests are written: three complete independent golden sets rather than one, a fourth part-recorded for WebGPU, and why every new test is written by breaking the thing it covers.

The repository builds on Flutter 3.47.0 stable, and the list of what that channel costs has kept getting shorter. Mip levels and instancing both arrived, and both are now used: a mip chain is built on the CPU and uploaded level by level because flutter_gpu has no generateMipmap, and instanced draws carry mesh particles. Rendering into a mip level came with them. ColorTarget.mipLevel names a face and a level, and the environment map is prefiltered through it. Compressed pixel formats are here too: the BC, ETC2 and ASTC families are in TextureFormat, every backend answers supportsTextureFormat for itself, and a KTX2 that arrives is read. No asset in this repository ships a compressed texture, though, because dart run flutter3d_build:convert has no encoder to make one. That gap is upstream of the engine, not in it.

One entry is left on the list: compute passes, and with them GPU particles, GPU skinning, GPU culling and indirect draw. It is recorded in ARCHITECTURE.md, section 2, and it is still the reason several things are built the way they are rather than the obvious way.

The upgrade also fixed setDepthWrite(false), which did nothing until 3.47. Before that, additive particles occluded each other on two backends out of three, and the software backend mirrored the bug on purpose so the two would stay comparable. ARCHITECTURE.md §7 keeps that story because the lesson still applies.

A stale bundle fails with failed to bind texture, not with a shader behaving oddly. The renderer binds a slot that the new GLSL declares and the compiled binary has not got, and binding a slot a compiled shader does not have takes the frame down. The message names nothing that leads back to the file that was edited.

So dart run tool/structure.dart checks it: one of its thirty-five rules compares the bundle against the sources it was built from and says which of them are newer. The rule skips when there is no bundle at all, which is every fresh checkout and every CI run. impellerc is not there to build one, and a rule demanding it would be red on the machines least able to do anything about it.

Both web backends work the other way and need no such rule: their translations are checked in, and CI regenerates each and fails on the diff. The WebGPU translation takes a longer route, from the same GLSL through glslangValidator and then naga into WGSL, so the diff also catches a different compiler on the machine.

Every package here ships agent skills: what its API is for, the mistakes it has already paid for, and the boundaries a scan holds it to. A project that depends on any of them installs the ones it wants:

dart run skills@ get          # reads the skills/ of every dependency

They travel in the published archive, so an agent working in your game reads them where it looks rather than out of a version-stamped pub cache directory it has no way to name. Each skill directory is named for the package it comes from, which the skills CLI requires and a structure rule here checks. A skill directory named otherwise is installed for nobody, and nothing reports it.

The conventions here differ from the usual ones. Tests are written by breaking the thing they cover, architecture is held by scans rather than by review, and levels, models and templates are generated rather than edited. All of it is in CONTRIBUTING.md, and bash tool/ci.sh is the contract.

• CONTRIBUTING.md: how to build, test and send a change
• CODE_OF_CONDUCT.md: Contributor Covenant 2.1
• SECURITY.md: report privately, not in an issue
• ARCHITECTURE.md: how the system is put together, and why

MIT. See LICENSE.

Third-party assets keep their own terms, recorded beside them in LICENSES.md with author, source, licence and what was changed. Everything shipped today is CC0 or generated in this repository.