# Installing

> What every machine needs, which machine builds for which platform, and how to add Orblit to a Flutter project.

Read online at https://orblitengine.com/docs/start/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](https://orblitengine.com/docs/start/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](https://orblitengine.com/docs/start/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](https://orblitengine.com/docs/start/setup/apple/), [Android](https://orblitengine.com/docs/start/setup/android/), [the web](https://orblitengine.com/docs/start/setup/web/) |
| Linux, x86_64 | [Linux](https://orblitengine.com/docs/start/setup/linux/), [Android](https://orblitengine.com/docs/start/setup/android/) |
| Linux, arm64 | [Linux](https://orblitengine.com/docs/start/setup/linux/) |
| Windows, x64 | [Windows](https://orblitengine.com/docs/start/setup/windows/) |
| Mac, Intel | Nothing that draws. [Why](https://orblitengine.com/docs/start/setup/apple/#not-on-an-intel-mac) |
| Windows on Arm | Nothing that draws. [Why](https://orblitengine.com/docs/start/setup/windows/#x64-only) |

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](https://orblitengine.com/docs/reference/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:

```yaml title="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](https://orblitengine.com/docs/reference/packages/) lists them.

:::note[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](https://orblitengine.com/docs/start/setup/apple/) | You, once for each engine version | 74 MB, which unpacks to about 290 MB |
| [Linux](https://orblitengine.com/docs/start/setup/linux/) | CMake, when Flutter configures the build | 52 MB, or 51 MB on arm64 |
| [Windows](https://orblitengine.com/docs/start/setup/windows/) | CMake, through Git's bash | About 810 MB |
| [Android](https://orblitengine.com/docs/start/setup/android/) | Gradle, before the native build | 58 MB, plus 52 MB on a Linux machine for its `matc` |
| [The web](https://orblitengine.com/docs/start/setup/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:

```dart title="lib/main.dart"
import 'package:flutter/material.dart';
import 'package:orblit_filament/orblit_filament.dart';

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

```sh
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](https://orblitengine.com/docs/start/your-first-scene/).