Experimental VR fork of flutter/flutter, maintained by Adrian Moisa. This fork is the engine half of the Flutter Scene VR demo. The original Flutter README is preserved below this addendum.
Demo setup snapshot: 31 August 2026.
Both forks keep their maintained VR changes on vr. Commit and push fork work
only to origin/vr; leave master untouched. Explicitly select vr when cloning
either fork, even if GitHub opens a different default branch.
Maintainers should select vr as each fork's default branch in GitHub repository
settings so repository visitors see the maintained code too.
This experiment grew out of building VR support for Visual Space. Maintaining Flutter Scene for the flat application and a separate native 3D engine for Quest would mean implementing and tuning materials, lighting, shadows, and scene features twice. We want to keep Flutter Scene as the 3D renderer in both modes, with native OpenXR responsible for the headset session and presentation.
Flutter Scene already renders geometry on the GPU. The problem was the route its finished images took to the headset: Flutter composition, a large Android surface, and a native copy into the OpenXR eye images. This fork adds the missing engine boundary for borrowing an external GPU render target so that Flutter Scene can write directly into those eye images.
| Repository | Responsibility |
|---|---|
| flutter_vr (this repository) | Generic external GPU surfaces, frame ownership/completion, and Android GLES interoperation. |
| flutter_scene_vr | Rendering scenes into supplied targets, stereo views, the OpenXR plugin, and the gallery/demo. |
The Flutter patch is intentionally generic; it does not put Meta Quest or OpenXR application logic into Flutter. The current external-target implementation is Android/OpenGL ES, not a general Vulkan, Metal, or all-headset VR solution. The API and synchronization contract remain experimental.
The recipe below follows the development setup used for the demo: macOS on Apple Silicon, an Android ARM64 profile engine, and a Meta Quest 3. Other host platforms need the appropriate host build configuration from Flutter's engine setup and compilation guide. Do not copy the macOS ARM64 host target unchanged onto Intel or Linux. Windows is not the documented host for cross-compiling this Android engine.
Install Git, Python 3, curl/unzip, full Xcode with its platform/Metal toolchains,
and the Rosetta components required by Flutter's Apple Silicon engine setup.
Make sure xcode-select -p selects the full Xcode developer directory rather
than only Command Line Tools. For the Android application, install Android
Studio, SDK Platform/Build Tools 36, Platform Tools (adb), NDK
28.2.13676358, and CMake 3.22.1 or newer. Use an Android Studio JDK compatible
with the checked-in Gradle configuration (Java source compatibility is 17).
Engine dependencies are downloaded separately by gclient.
Allow substantial disk space for source dependencies and two engine outputs; this is much larger than installing a normal Flutter SDK. Initial dependency downloads and compilation can take a long time.
Use a writable directory without spaces, such as ~/Projects. Keep your stock
Flutter installation available for unrelated applications. The engine is already
inside the Flutter monorepo; do not clone the retired standalone engine repo.
mkdir -p "$HOME/Projects"
git clone --branch vr https://github.com/adrian-moisa/flutter_vr.git "$HOME/Projects/flutter_vr"
git -C "$HOME/Projects/flutter_vr" remote add upstream https://github.com/flutter/flutter.git
git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git "$HOME/Projects/depot_tools"For an existing fork clone, keep its SDK cache, dependencies, and engine outputs.
First commit or otherwise preserve local work, then fetch origin. If local
vr does not exist, create it with git switch --create vr --track origin/vr.
If it exists, use git switch vr and
git branch --set-upstream-to=origin/vr vr to replace any old origin/main
tracking. If origin/vr is missing, the maintainer must publish local vr
with git push -u origin vr first; do not substitute master.
Use origin for your fork and upstream for official Flutter. If reusing an
existing SDK at another path, set FLUTTER_VR_ROOT to that path below.
Add these lines to your shell configuration (~/.zshrc for the usual macOS
terminal, or your Bash configuration), then open a new terminal:
export FLUTTER_VR_ROOT="$HOME/Projects/flutter_vr"
export FLUTTER_GIT_URL="https://github.com/adrian-moisa/flutter_vr.git"
export PATH="$HOME/Projects/depot_tools:$FLUTTER_VR_ROOT/bin:$PATH"
export ANDROID_HOME="$HOME/Library/Android/sdk"
export PATH="$ANDROID_HOME/platform-tools:$PATH"FLUTTER_VR_ROOT is a convenience variable used by this guide. Adjust
ANDROID_HOME if Android Studio uses another SDK location. There is no need
to copy engine binaries over your stock SDK or install Flutter system-wide.
type -a flutter
flutter --version
flutter doctor -v
flutter doctor --android-licensesThe first Flutter executable should be inside flutter_vr/bin. An explicit
"$FLUTTER_VR_ROOT/bin/flutter" invocation also avoids aliases, version-manager
shims, or another SDK earlier on PATH.
In Android Studio, set Languages & Frameworks → Flutter → Flutter SDK path
to the fork root, not its bin directory. If Dart is not detected, use
<fork>/bin/cache/dart-sdk. In VS Code, set dart.flutterSdkPath to the same
absolute fork root. Check the Android app's local android/local.properties
if Gradle still finds an older SDK; flutter.sdk must refer to this fork.
Do not commit machine-specific IDE paths or local.properties.
Selecting the SDK does not select your compiled engine. Without the
local-engine flags in step 4, Flutter normally uses downloaded engine artifacts.
Do not run flutter upgrade or switch Flutter channels as part of this setup;
use the fork revision containing the VR patches.
From a fresh clone:
cd "$FLUTTER_VR_ROOT"
cp engine/scripts/standard.gclient .gclientIn the new .gclient, change the solution's url from the upstream Flutter URL
to https://github.com/adrian-moisa/flutter_vr.git. Keep its name: ".",
managed: False, and deps_file: "DEPS" settings. If you already have a
.gclient, inspect and update it instead of overwriting your configuration.
gclient sync --no-history --jobs=1This is the conservative download recipe used locally after parallel downloads
hit rate limits. --no-history reduces dependency history, not the top-level
fork's patch history; omit it if you need full dependency histories. The sync
job count is independent of the compiler job count below. No separate web-engine
build is required to run the gallery in Chrome.
Do not proceed to GN with an incomplete sync. Missing paths such as
engine/src/flutter/third_party/skia indicate missing dependencies, not a
reason to remove build targets. Re-run the sync after resolving the reported
network or toolchain error.
The successful local recipe used a 24 GB Apple Silicon machine, with four Android build jobs and two host build jobs, run sequentially:
cd "$FLUTTER_VR_ROOT/engine/src"
./flutter/tools/gn --android --android-cpu arm64 --runtime-mode profile --no-lto --no-enable-unittests
./flutter/tools/gn --mac-cpu arm64 --runtime-mode profile --no-lto --no-enable-unittests
ninja -C out/android_profile_arm64 -j 4
ninja -C out/host_profile_arm64 -j 2Both builds are required. The Android output supplies the headset engine and
embedding JARs; the host output supplies tools such as gen_snapshot,
font-subset, and the shader compiler used to build the application.
Run each command only after the previous one succeeds.
- Limit parallel jobs. Each compile/link process consumes memory. Start at
the values above, or reduce to
-j 1/-j 2on smaller machines. A powerful workstation with enough RAM can try-j 20or more, scaling toward its available core count while watching memory pressure. Core count alone does not determine a safe setting, particularly during linking. - Close other applications before building, especially IDE indexing, browsers, and other builds. Do not run the Android and host Ninja builds concurrently when memory is tight.
- Disable LTO for this demo build.
--no-ltoavoids the expensive link-time optimization that contributed to local memory pressure. It is a build-time compromise, not a runtime performance improvement. - Disable unit-test targets for this demo build.
--no-enable-unittestsavoids compiling/linking the full unit-test and related benchmark target set just to obtain demo artifacts. We used this to get the local build through, not because tests are unnecessary. This is not an upstream validation recipe; proper coverage and normal validation are still required before proposing the engine changes for acceptance.
If a prior configuration enabled LTO/tests, rerun both GN commands before resuming Ninja. If a linker is killed or the machine starts swapping heavily, stop that build and restart with fewer jobs. Keep the existing output directories so completed work can be reused; deleting the build is not the first remedy.
Check that the outputs include:
engine/src/out/android_profile_arm64/lib.stripped/libflutter.so
engine/src/out/android_profile_arm64/flutter_embedding_profile.jar
engine/src/out/android_profile_arm64/arm64_v8a_profile.jar
engine/src/out/host_profile_arm64/gen_snapshot
engine/src/out/host_profile_arm64/font-subset
engine/src/out/host_profile_arm64/impellerc
engine/src/out/host_profile_arm64/shader_lib/
The two engine configurations and the APK must use the same runtime mode.
Changing only --profile to --debug or --release is not sufficient; build
matching Android and host outputs first.
Follow the Flutter Scene VR README
to clone its workspace, select the local flutter_gpu Dart package, connect
Quest, and launch the gallery. That Dart dependency override is essential:
--local-engine selects native artifacts, not the matching package sources.
After that workspace setup, a manual APK build has this shape:
cd "$HOME/Projects/flutter_scene_vr/examples/openxr_quest"
"$FLUTTER_VR_ROOT/bin/flutter" \
--local-engine-src-path="$FLUTTER_VR_ROOT/engine/src" \
--local-engine=android_profile_arm64 \
--local-engine-host=host_profile_arm64 \
build apk --profile --target-platform android-arm64 --target lib/main.dartBuilding an APK does not install or launch it. The Scene repository's
quest-build-and-deploy-local-forks.sh helper performs the build, device
selection, install, and immersive launch, with overridable SDK/engine paths.
Use that helper for the complete first-run flow.
These forks make the demo reproducible while the shared rendering approach is developed. They are not official Flutter VR support, and upstream acceptance or a delivery date has not been agreed. The intent is to contribute the changes back and stop requiring forks.
The Flutter engine contribution needs careful API, resource lifetime, synchronization, backend, and test review. The Scene integration is more local, but still depends on that engine capability and needs performance and platform validation. GPU completion uses EGL fences where supported, with a conservative blocking fallback. Further synchronization, lifecycle, and performance work must keep borrowed images alive until GPU work is complete.
The plan is to periodically rebase these forks onto their upstream projects
while preparing contributions. Treat the two forks as a compatible pair: record
their commit IDs for a shared demo, preserve local changes before updating, and
follow the fork's published revision rather than blindly tracking upstream.
After engine source or DEPS changes, sync dependencies, rerun GN as needed,
and rebuild both engine outputs before rebuilding the APK. After Scene changes,
refresh dependencies and let its build hooks regenerate assets.
For developers and runners consuming the published fork:
cd "$FLUTTER_VR_ROOT"
git switch vr
git pull --ff-only origin vrWhen engine source, dependencies, or build configuration changes, repeat the
sync, GN, and both Ninja builds above. Keep out for incremental compilation.
A branch rename alone or a framework-only Dart change does not require native
engine compilation. Rebuild the application to pick up framework changes.
Maintainers commit on vr and publish ordinary new commits with
git push -u origin vr. For an upstream update, start from a clean working tree,
fetch both remotes, review any remote-only commits, then rebase:
cd "$FLUTTER_VR_ROOT"
git switch vr
git fetch origin
git log --oneline --left-right vr...origin/vr
git fetch upstream
git rebase upstream/masterUse upstream for https://github.com/flutter/flutter.git; add that remote if
an older clone lacks it. Reconcile unexpected divergence before rebasing.
After rebuilding affected engine outputs and checking the matching Scene fork,
publish rewritten history with git push --force-with-lease origin vr.
Never push to master, main, or upstream. A failed lease requires reviewing
remote changes. If a consumer's fast-forward pull fails after a rebase or amend,
reconcile it with published vr; do not switch to master or delete the engine
outputs. The runner consumes published revisions and does not rebase or push.
The material below is preserved from upstream. Its stock installation links do not replace the custom-engine setup above.
Flutter is Google's SDK for crafting beautiful, fast user experiences for mobile, web, and desktop from a single codebase. Flutter works with existing code, is used by developers and organizations around the world, and is free and open source.
For release and other announcements, join the flutter-announce mailing list. Our documentation also tracks breaking changes across releases.
The Flutter tool may occasionally download resources from Google servers. By downloading or using the Flutter SDK, you agree to the Google Terms of Service: https://policies.google.com/terms
For example, when installed from GitHub (as opposed to from a prepackaged
archive), the Flutter tool will download the Dart SDK from Google servers
immediately when first run, as it is used to execute the flutter tool itself.
This will also occur when Flutter is upgraded (e.g. by running the flutter upgrade command).
We think Flutter will help you create beautiful, fast apps, with a productive, extensible and open development model, whether you're targeting iOS or Android, web, Windows, macOS, Linux or embedding it as the UI toolkit for a platform of your choice.
We want to enable designers to deliver their full creative vision without being forced to water it down due to limitations of the underlying framework. Flutter's layered architecture gives you control over every pixel on the screen and its powerful compositing capabilities let you overlay and animate graphics, video, text, and controls without limitation. Flutter includes a full set of widgets that deliver pixel-perfect experiences whether you're building for iOS (Cupertino) or other platforms (Material), along with support for customizing or creating entirely new visual components.
Flutter is fast. It's powered by hardware-accelerated 2D graphics libraries like Skia (which underpins Chrome and Android) and Impeller. We architected Flutter to support glitch-free, jank-free graphics at the native speed of your device.
Flutter code is powered by the world-class Dart programming language, which enables compilation to 32-bit and 64-bit ARM machine code for iOS and Android, JavaScript and WebAssembly for the web, as well as Intel x64 and ARM for desktop devices.
Flutter offers stateful hot reload, allowing you to make changes to your code and see the results instantly without restarting your app or losing its state.
Flutter works with any development tool (or none at all), and also includes editor plug-ins for both Visual Studio Code and IntelliJ / Android Studio. Flutter provides tens of thousands of packages to speed your development, regardless of your target platform. And accessing other native code is easy, with support for both FFI (on Android, on iOS, on macOS, on Linux, and on Windows) as well as platform-specific APIs.
Flutter is a fully open-source project, and we welcome contributions. Information on how to get started can be found in our contributor guide.


