Installation

Requirements

Flutter Scene needs Flutter 3.47 (stable) or newer. That is the first stable release carrying the Flutter GPU support the package builds on.

Platform	Status
iOS	Supported
Android	Supported
Web	Supported
macOS	Supported
Windows	Supported
Linux	Supported

Every platform except the web renders through Impeller and Flutter GPU. Impeller is the default renderer everywhere as of 3.47, so the only thing to turn on is Flutter GPU, once per platform. The web has no Impeller and needs nothing, since the package ships its own WebGL2 backend and runs under both the CanvasKit and Skwasm renderers.

Enable Flutter GPU

While developing, pass the flag on the command line. This works on every native platform and needs no project changes.

flutter run --enable-flutter-gpu

To turn it on permanently, so it applies to every run and to the app you ship, edit the platform file below. Do this for each platform you target.

iOS

In ios/Runner/Info.plist, inside the top-level <dict>:

<key>FLTEnableFlutterGPU</key>
<true/>

Android

In android/app/src/main/AndroidManifest.xml, inside <application>:

<meta-data
    android:name="io.flutter.embedding.android.EnableFlutterGPU"
    android:value="true" />

macOS

In macos/Runner/Info.plist, inside the top-level <dict>:

<key>FLTEnableFlutterGPU</key>
<true/>

Windows and Linux

These two gained a project-level setting in Flutter 3.47.1. Set it on the DartProject your runner builds.

On Linux, in linux/runner/my_application.cc, just after the project is created:

g_autoptr(FlDartProject) project = fl_dart_project_new();
fl_dart_project_set_enable_flutter_gpu(project, TRUE);

On Windows, in windows/runner/main.cpp, just after the project is created:

flutter::DartProject project(L"data");
project.set_enable_flutter_gpu(true);

On 3.47.0

3.47.0 has no such setting, so Flutter GPU is enabled per run instead.

flutter run --enable-flutter-gpu

For a debug or profile build launched outside flutter run, set the engine switches in the environment:

FLUTTER_ENGINE_SWITCHES=1 \
FLUTTER_ENGINE_SWITCH_1=enable-flutter-gpu \
  ./my_app

Release builds compile the environment switches out, so a shipped Windows or Linux release needs 3.47.1.

Add the package

flutter pub add flutter_scene

Set up the asset pipeline

Run this once from your project root. It is the recommended way to use Scene, and what the rest of the docs assume.

dart run flutter_scene:init

init writes a hook/build.dart that converts your assets at build time, creates flutter_scene_generated/ with a .gitignore for its outputs, and adds that one directory to flutter.assets in your pubspec.yaml. It is safe to run again, and it will not overwrite a hook/build.dart you wrote yourself. It prints a block to paste into your existing build() callback instead.

The generated hook discovers .glb and .fscene models, .fmat materials, and loose images under assets/, and converts each one.

import 'package:flutter_scene/build_hooks.dart';
import 'package:hooks/hooks.dart';

void main(List<String> args) async {
  await build(args, (input, output) async {
    buildScenes(buildInput: input, buildOutput: output);
    await buildMaterials(buildInput: input, buildOutput: output);
  });
}

Drop sources under assets/ and load them by their source path.

final level = await loadScene('assets/level.glb'); // built from the .glb
final toon = await loadFmatMaterial('assets/toon.fmat'); // built from the .fmat
final ground = await loadTexture('assets/ground.png'); // built from the image

Why convert ahead of time

A .glb has to be parsed and unpacked into GPU-ready form every time the app loads it. The pipeline does that work once, at build time, into the .fsceneb format the engine reads directly, so loading a model at runtime costs far less. Prefer it for anything that ships with your app.

It is also how the rest of the toolkit reaches you. .fmat custom materials are the supported way to write your own shaders (see Materials), textures arrive block-compressed with full mip chains, and editing any source reconverts just that source and hot reloads it into the running app.

Keep your sources in version control. The generated directory holds compiled output tied to the Flutter engine that built it, which is why the hook manages its .gitignore for you.

Import a model at runtime

When a model is not available at build time, because you download it or the user supplies it, import the .glb directly.

final model = await Node.fromGlbAsset('assets/model.glb');
scene.add(model);

This needs no hook and no configuration, which also makes it the quickest way to try Scene. It parses the glTF on every load, so reach for the pipeline above once the model ships with your app.

Run

On the web, no flags are needed.

flutter run -d chrome

Add --wasm to run under the Skwasm renderer. On native platforms, run with the flags from Enable Flutter GPU above.

Next

Continue to Your first scene to render something on screen.