Skip to content
nmfisherPublic

About

3D rendering toolkit for Dart and/or Flutter

Resources

Stars

224 stars

Watchers

6 watching

Forks

Repository files navigation

Thermion Logo

Quickstart (Flutter) • Documentation • Discord

Cross-platform 3D toolkit for Dart and Flutter.

pub github discord contributors

Thermion demo

Features

  • Supports iOS (arm64), MacOS (arm64/x64), Android (arm64), Windows (x64) (>= 10), Web/WASM
  • glTF, KTX, PNG & JPEG texture support
  • camera/entity manipulation with mouse (desktop) and gestures (mobile)
  • skinning + morph animations

Uses the Filament PBR engine.

Filament version and custom materials

Use filamentVersion to select the matching Filament release when compiling custom materials with matc:

import 'package:thermion_dart/filament_version.dart';

void main() {
  print(filamentVersion); // v1.77.2
}

It is also exported by package:thermion_dart/thermion_dart.dart. The constant works with hosted, Git and path dependencies, and is the version used by the native build hook. Recompile your custom materials when it changes.

After initializing Filament, FilamentApp.instance!.materialVersion gives the material format number reported by matc --version. This number is distinct from the Filament release version. Compile custom materials with matc from the same Filament release as the application.

createMaterial rejects incompatible format versions and malformed chunk layouts with a Dart FormatException before calling Filament's material builder. It does not validate every payload or backend requirement; other invalid packages can still cause a native panic.

Runtime material compilation (optional)

Runtime packages use Filament's performance optimization (matc's default, or -O), rather than the size optimization selected by matc -S. They are not promised to be byte-identical to offline packages. Both runtime APIs embed the compilation flags and their input source for inspection; full packages embed the source after in-memory includes have been resolved. The web runtime compiler targets WebGL (OPENGL); it does not generate WebGPU materials.

Instead of precompiling .filamat packages with matc, apps that need to generate materials at runtime (e.g. user-authored or procedurally generated shaders) can compile GLSL material source directly on the device:

final material = await FilamentApp.instance!.compileMaterialSource(
  'my_material',
  '''
  void material(inout MaterialInputs material) {
    prepareMaterial(material);
    material.baseColor.rgb = float3(1.0, 0.0, 0.0);
  }
  ''',
  shading: MaterialShading.lit,
);

For full .mat sources — the same format the matc tool accepts, with a material { ... } configuration block (parameters, shading model, variants, ...) and #include directives — use compileMaterialPackage. Includes are resolved from an in-memory map (exact-name match, no filesystem access):

final material = await FilamentApp.instance!.compileMaterialPackage(
  'my_material',
  '''
  material {
      name : "MyMaterial",
      shadingModel : unlit,
      parameters : [ { type : float4, name : baseColor } ]
  }
  fragment {
      #include "common.glsl"
      void material(inout MaterialInputs material) {
          prepareMaterial(material);
          material.baseColor = tint(materialParams.baseColor);
      }
  }
  ''',
  includes: {
    'common.glsl': 'vec4 tint(vec4 c) { return c * vec4(1.0, 0.9, 0.8, 1.0); }',
  },
);

Both APIs require linking libfilamat — Filament's offline material compiler, which bakes in glslang and SPIRV-Tools — plus libmatp (the .mat parser behind matc) for compileMaterialPackage, so they are opt-in. Add the flag to your app's pubspec.yaml:

hooks:
  user_defines:
    thermion_dart:
      runtime_materials: true

The flag adds roughly 8–45 MB to the native library depending on platform and build mode (release libfilamat.a is ~45 MB; less is carried into the final binary). FilamentApp.instance!.runtimeMaterialsSupported reports whether the loaded build has it; compileMaterialSource and compileMaterialPackage throw UnsupportedError otherwise. On web, the flag additionally selects a filamat-enabled engine variant — the build hook fetches thermion_dart-<sha>-web-runtime-materials.zip instead of the default wasm (~20 MB larger; it links libfilamat, the default build dead-code-eliminates it). Compilation is synchronous and CPU-intensive (hundreds of milliseconds) — run it before startup or from a background isolate.

A live web demo — a GLSL editor that compiles and applies materials in the browser — is in examples/dart/material_editor.

Quickstart (Flutter)

From the command line:

flutter channel stable
flutter upgrade
flutter config --enable-native-assets  

In your Flutter app:

@override
  Widget build(BuildContext context) {
    return Scaffold(
        body: Stack(children: [
        Positioned.fill(
            child: ViewerWidget(
          assetPath: "assets/cube.glb",
          skyboxPath: "assets/default_env_skybox.ktx",
          iblPath: "assets/default_env_ibl.ktx",
          transformToUnitCube: true,
          initialCameraPosition: Vector3(0, 0, 6),
          background: Colors.blue,
          manipulatorType: ManipulatorType.ORBIT,
          onViewerAvailable: (viewer) async {
            await Future.delayed(const Duration(seconds: 5));
            await viewer.removeSkybox();
          },
          initial: Container(
            color: Colors.red,
          ),
        ))]));
  }

the first time you build an app that consumes this package, the Dart native-assets build system will download static binaries from Cloudflare. This may take a few minutes (depending on which platform you are compiling for). These will be cached, so subsequent builds will be much faster.

Web

Web builds need two files (thermion_dart.js and thermion_dart.wasm) sitting alongside your app's web/index.html. In the normal case, thermion_dart's build hook fetches them for you on flutter run/flutter build web — no extra step required:

flutter build web

The hook reads native/web/web.version, downloads the matching artifacts from Cloudflare R2, caches them under .dart_tool/thermion_dart/web/<sha>/, and copies them into your app's web/ directory. Subsequent builds are instant unless the version changes.

If you want to fetch them ahead of time (e.g. for an offline build), you can do so manually:

dart run thermion_dart:download_web            # → ./web/
dart run thermion_dart:download_web -o custom  # → custom/

Iterating on native C++ against web

If you're modifying thermion_dart's native code and want to test on web without bumping native/web/web.version and waiting for CI to rebuild the R2 artifacts, build the emscripten target locally and opt in via your app's pubspec.yaml:

hooks:
  user_defines:
    thermion_dart:
      web_local: true
# Build the wasm (from native/web/build):
emcmake cmake ..
emmake make

# Then run/build your Flutter app:
flutter run -d chrome

When set, the build hook copies thermion_dart.{js,wasm} from thermion_dart/native/web/build/build/out/ into your app's web/ directory instead of downloading from R2. Remove the flag (or set it to false) to go back to the pinned prebuilt.

Main-thread rendering for standalone web clients

Custom browser clients can build the web engine with -DTHERMION_WEB_MAIN_THREAD=ON (default: OFF). Initialize the engine and call Thermion from the browser's main thread. Commands and completion callbacks execute on that calling thread. Thermion does not create its own render worker or transfer the canvas to one.

Serialize calls on that thread. Drive frames by calling FilamentApp.render() from the application's animation loop. Command dispatch also drains pending Filament commands and upload-release callbacks without requiring a frame. Asynchronous glTF loading yields between progress polls so decoder tasks and browser events can run.

The default build continues rendering through its worker loop. In that build, FilamentApp.render() runs Dart's request-frame hooks but does not request or await a rendered frame.

The main-thread option does not disable Emscripten pthread support or Filament's internal helpers. Enabling it requires rebuilding the Wasm engine. A Dart define or an existing worker bundle cannot enable it. No performance improvement is implied by the option.

CI publishes the main-thread engine alongside the default one: the build hook fetches it automatically when you set web_variant under hooks.user_defines.thermion_dart in your app's pubspec.yaml — no local toolchain needed:

hooks:
  user_defines:
    thermion_dart:
      web_variant: main_thread

Unknown values log a warning and fall back to the default engine. web_local: true composes with this: it then copies from native/web/build-main-thread/build/out/ (build that variant locally with emcmake cmake .. -DTHERMION_WEB_MAIN_THREAD=ON into a separate directory).

Runtime-materials web engine

runtime_materials: true (the same user define that enables runtime material compilation on native) also selects a web engine variant with libfilamat linked — compileMaterialSource then works in the browser. The build hook fetches thermion_dart-<sha>-web-runtime-materials.zip (~20 MB larger than the default engine; the default dead-code-eliminates filamat). It composes with web_variant and web_local like any other variant. See the live editor demo in examples/dart/material_editor. Once this lands, a matching thermion_dart-<sha>-web-main-thread.zip appears on R2 only after the next native-changed push to develop bumps web.version — until then main-thread consumers must keep building locally.

Running the test suite on web

The package:test suite runs on Chrome via a wrapper. Do not invoke dart test -p chrome directly — the multithreaded WASM build needs crossOriginIsolated (a COOP/COEP proxy), and each test file needs an HTML host that loads thermion_dart.js and the thermion_canvas. The wrapper handles both:

# from thermion_dart/
dart run tool/web_test_runner.dart --assets=../examples/assets test/texture_tests.dart

It stamps per-file test/<name>.html, starts tool/coi_proxy.dart on port 8899 (injecting the isolation headers and bridging thermion.assets / thermion.output sentinel hosts for asset reads and capture writes), runs dart test -p chrome, and prints a per-file summary.

Flags: --port=N, --timeout=DUR, --concurrency=N, --assets=DIR, --no-proxy (reuse an external proxy), --clean (delete the generated HTML on exit). With no test file arguments, it runs every test/*_test.dart and test/*_tests.dart.

test/thermion_dart.{js,wasm} are gitignored symlinks into native/web/build/build/out/, so they stay current after every make wasm.

Sponsors, Contributors & Acknowledgments

Thermion uses the Filament Physically Based Rendering engine under the hood.

Special thanks to odd-io for sponsoring work on supporting Windows, raycasting, testing and documentation.

Thank you to the following people:

About

3D rendering toolkit for Dart and/or Flutter

Resources

Stars

224 stars

Watchers

6 watching

Forks

Releases

Packages

Used by

Contributors

Languages