Installing

What you need

macOS	For the setup on this page. The renderer draws elsewhere too, and platform support says where and how far along each one is. Everything that doesn’t draw runs anywhere Dart does.
Flutter	3.47.0 or newer, on the stable channel
Dart SDK	3.10.0 or newer. The one Flutter ships with is fine
Xcode	With the command line tools, for the renderer’s native side
A network	The first build downloads the Filament SDK, about 300 MB

Check the first two:

flutter --version
flutter doctor

Adding it to a project

The packages are not on pub.dev yet, so they resolve from git:

pubspec.yaml

dependencies:
  flutter:
    sdk: flutter

  # Vectors and matrices. Orblit takes and returns these types rather than
  # defining its own, so it is a direct dependency of yours too.
  vector_math: ^2.1.4

  orblit_filament:
    git:
      url: https://github.com/ChxisB/orblit.git
      path: packages/orblit_filament

One repository holds several packages, which is why each dependency names a path inside it. Add the others the same way: orblit_light, orblit_ui, orblit_mesh and the rest all live in ChxisB/orblit. The package reference lists them.

No account, no clone, no key

These are HTTPS URLs on public repositories, so pub get resolves them with no credentials, on your machine and on a CI runner alike. You never need to clone the engine in order to use it.

Cloning is for working on Orblit rather than with it: the editor and the examples point at sibling checkouts so a renderer change can be seen without a push and a pub upgrade in between.

What the first build does

The first flutter run on macOS is slow, once. The renderer’s podspec has a prepare_command that:

1. downloads the pinned Filament SDK (currently v1.77.0) into third_party/, and
2. compiles the package’s materials with Filament’s matc, into C arrays rather than asset files.

Both are idempotent, so every build after the first skips them. Both are build artefacts and are not in git.

Materials get compiled into the binary rather than shipped as assets, and that’s deliberate. It means the renderer has no file to find at runtime and no asset bundle to depend on, which rules out a whole class of “works on my machine” before it can start.

Swift Package Manager

Under SPM there is no equivalent hook, because a package plugin runs sandboxed and without network access. That path needs macos/setup.sh run by hand, once, and Package.swift will say so if it hasn’t been. Switching a project between SPM and CocoaPods needs a flutter clean in between.

Checking it worked

The smallest thing that proves the whole stack is up:

lib/main.dart

import 'package:flutter/material.dart';
import 'package:orblit_filament/orblit_filament.dart';

void main() => runApp(
      const MaterialApp(
        home: Scaffold(body: OrblitView()),
      ),
    );

flutter run -d macos

An OrblitView with no scene draws the default one. If you get a window with something in it, then the SDK downloaded, the materials compiled, the native side linked, and Flutter is compositing a Filament frame.

Next: your first scene.