Installation

Requirements

Flutter Scene renders through Flutter GPU, an experimental Flutter feature, so it needs a recent build of the Flutter master channel. On native platforms it also needs Impeller. On the web it uses a built-in WebGL2 backend and needs no flags.

The flutter lower bound in the package is set to the latest stable so that pub.dev can resolve and score it, but that bound is looser than what the package actually needs. A recent master build is what you want.

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

On iOS and Android, Impeller is the default renderer, so no extra configuration is needed. On macOS, Windows, and Linux, pass --enable-impeller when you run. On the web it works under both the CanvasKit and Skwasm renderers.

Add the package

flutter pub add flutter_scene

Set up the build hook

Flutter Scene does two jobs at build time. It preprocesses glTF models (.glb) into the engine’s fast-loading .fsceneb package, and it compiles .fmat custom materials, which is the supported way to write your own shaders (see Materials). Both run from a hook/build.dart in your project.

You do not have to write that file by hand. Run this once from your project root to create it.

dart run flutter_scene:init

The generated hook discovers .glb models and .fmat materials under assets/, converts them, and registers the results as Dart Data Assets.

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

void main(List<String> args) async {
  await build(args, (input, output) async {
    // Import .glb scenes under assets/ as DataAssets, loadable by source path
    // with loadScene (and hot-reloadable). A no-op when there are no scenes.
    buildScenes(
      buildInput: input,
      buildOutput: output,
      assetMode: SceneAssetMode.dataAssetsRequired,
    );
    // Compile .fmat materials under assets/ as DataAssets, loadable by source
    // path with loadFmatMaterial (and hot-reloadable). A no-op when there are
    // no materials.
    await buildMaterials(
      buildInput: input,
      buildOutput: output,
      assetMode: MaterialAssetMode.dataAssetsRequired,
    );
  });
}

The hook registers its outputs as Data Assets, which is still gated behind an experimental Flutter flag. Enable it once per machine.

flutter config --enable-dart-data-assets

What Data Assets do for you

The hook registers its outputs as Data Assets, so they are added to the asset manifest automatically. You never list a generated file under flutter.assets, and you load everything by its original source path.

final model = await loadScene('assets/model.glb'); // built from the .glb
final toon = await loadFmatMaterial('assets/toon.fmat'); // built from the .fmat

The hook re-runs when a .glb or .fmat under assets/ changes, so edits hot reload into the running app in place. This is the workflow the rest of the docs assume. Assets and loading covers models and Materials covers .fmat.

Requirements and an existing hook

Data Assets are experimental, so you need a Flutter master build that recognizes --enable-dart-data-assets. If flutter config does not list that setting, move to a newer master build.

If your project already has a hook/build.dart, dart run flutter_scene:init does not overwrite it. It prints a managed block to paste inside your existing build() callback instead.

Run

On native platforms, pass both flags so Flutter GPU and Impeller are active.

flutter run --enable-flutter-gpu --enable-impeller

On the web, no flags are needed.

flutter run -d chrome

Add --wasm to run under the Skwasm renderer.

Next

Continue to Your first scene to render something on screen.