# 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 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](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 have not got Flutter yet, or `flutter doctor` does not 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. 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](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 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](https://orblitengine.com/docs/reference/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:

```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.

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](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 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:

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