Installing

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

This page covers what’s the same everywhere. There’s a page for each platform under it.

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 haven’t got Flutter yet, or flutter doctor doesn’t 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, so if Flutter can’t 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 can’t build for iOS without a Mac, for instance. The renderer adds one limit of its own: 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’s 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’s only about the renderer. Everything that doesn’t draw, meaning the simulation, geometry, agents, 2D and networking, is plain Dart and runs anywhere Dart does, Intel Macs included.

Platform support says how far along each platform is, which isn’t the same as 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.

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 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 rather than asset files.

Both are idempotent, so every build after the first skips them. Both are build artefacts and are not 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 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.

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     # 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, and ios and android are neither, so flutter run -d ios doesn’t 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.