Installing

Orblit is a set of Flutter packages, so most of installing it is installing Flutter. The renderer’s native side is the part that changes from platform to platform. Each platform has a setup script that downloads Google’s Filament SDK and compiles the renderer’s materials. What that script needs, and who runs it, is different on each one.

This page covers what is the same everywhere. Each platform then has a page of its own.

What every machine needs

Flutter	3.47.0 or newer, on the stable channel. Setting up Flutter covers getting it
Dart SDK	3.10.0 or newer. The one Flutter ships with is fine
Git	Pub fetches the packages with it
bash, curl and tar	The setup scripts are bash. On Windows, that bash is the one Git for Windows installs
A network	The first build downloads a Filament release from GitHub, between 51 MB and 810 MB depending on the platform, and three files of lookup tables, about 1.4 MB together, from raw.githubusercontent.com

If you have not got Flutter yet, or flutter doctor does not have a tick against the platform you want, start with setting up Flutter. The renderer’s native side builds with the same compilers Flutter’s own does. If Flutter cannot build an empty app for a platform, nothing on these pages will fix that.

Which machine builds what

Flutter already limits which platforms a machine can build for. You cannot build for iOS without a Mac, for instance. The renderer adds one more limit: Filament’s material compiler, matc, has to run on the machine doing the build. Google publishes it for Apple silicon Macs, for x86_64 and arm64 Linux and for x64 Windows, and that is what shapes this table.

Your machine	Can build for
Mac, Apple silicon	macOS and iOS, Android, the web
Linux, x86_64	Linux, Android
Linux, arm64	Linux
Windows, x64	Windows
Mac, Intel	Nothing that draws. Why
Windows on Arm	Nothing that draws. Why

That table is only about the renderer. Everything that does not draw, meaning the simulation, geometry, agents, 2D and networking, is plain Dart. It runs anywhere Dart does, Intel Macs included.

Platform support says how far along each platform is. That is a different question from whether it builds. Windows builds, for example, and nothing has drawn on it yet.

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.

Clone it only if you want to work on Orblit instead of with it. The editor and the examples point at sibling checkouts, so you can see a renderer change without a push and a pub upgrade in between.

What the first build does

The first build for each platform is slow, once. The setup script:

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

Both steps are idempotent, so every build after the first skips them. Both produce build artefacts, and neither is in git.

Platform	Who runs the setup	What it downloads
macOS and iOS	You, once for each engine version	74 MB, which unpacks to about 290 MB
Linux	CMake, when Flutter configures the build	52 MB, or 51 MB on arm64
Windows	CMake, through Git’s bash	About 810 MB
Android	Gradle, before the native build	58 MB, plus 52 MB on a Linux machine for its matc
The web	You, by hand, against a Filament you build yourself	Emscripten, about 1.9 GiB, and the Filament source

Materials are compiled into the binary instead of shipped as assets, on purpose. The renderer then 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” problems.

Checking it worked

Here is the smallest program 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     # or linux, windows or chrome

A phone or a simulator goes by the id that flutter devices prints for it. -d matches a device’s id or name. Neither ios nor android is one of those, so flutter run -d ios will not pick your iPhone.

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.