# Orblit

> Everything written down about Orblit, from getting a window open to what the renderer does on each platform.

Orblit is pre-alpha and nothing in it is API-stable, so these pages are a
better guide than anything remembered from training. When in doubt about a
name, the engine's source is at https://github.com/ChxisB/orblit.

- The packages aren't on pub.dev. They resolve from git, each one a `path`
  inside ChxisB/orblit: see [Installing](https://orblitengine.com/docs/start/installing.md).
- Most of the Dart written for these pages is compiled against the engine in
  CI. The Gallery pages are the excerpts the gallery app's code panel shows,
  not whole programs.
- The renderer is proven on macOS. [Platform
  support](https://orblitengine.com/docs/reference/platform-support.md) says what has been seen on
  each of the others.
- Licensed FSL-1.1-MIT, which is source-available: each release becomes MIT
  two years after it ships.
- Every page below is Markdown at the address given, and the whole site is
  one file at https://orblitengine.com/llms-full.txt.

## Start here

- [Documentation](https://orblitengine.com/docs.md): Everything written down about Orblit, from getting a window open to what the renderer does on each platform.
- [What Orblit is](https://orblitengine.com/docs/start/what-orblit-is.md): A Dart-first 3D game engine. What it does, what it does not do yet, and who it is for.
- [Where this came from](https://orblitengine.com/docs/start/where-this-came-from.md): Flame, Flutter Scene and Fluorite. What each of them got right, what Orblit is doing differently, and where the name came from.
- [Setting up Flutter](https://orblitengine.com/docs/start/flutter.md): Getting Flutter onto a Mac, a Windows or a Linux machine, the tools each platform's builds need, and an empty app that proves it before Orblit is involved.
- [Installing](https://orblitengine.com/docs/start/installing.md): What every machine needs, which machine builds for which platform, and how to add Orblit to a Flutter project.
- [macOS and iOS](https://orblitengine.com/docs/start/setup/apple.md): Setting up a Mac to build Orblit for macOS and iOS, including the one step Flutter doesn't do for you.
- [Linux](https://orblitengine.com/docs/start/setup/linux.md): Setting up a Linux machine to build Orblit, and the two things Filament's Linux release needs that Flutter's own instructions don't mention.
- [Windows](https://orblitengine.com/docs/start/setup/windows.md): Setting up a Windows machine to build Orblit, the bash it needs, and how far Windows has actually got.
- [Android](https://orblitengine.com/docs/start/setup/android.md): Setting up a Mac or a Linux machine to build Orblit for Android, and which phones and emulators it runs on.
- [The web](https://orblitengine.com/docs/start/setup/web.md): Building Orblit's renderer for the browser, with Emscripten and a Filament built from source, and the two files your app carries.
- [Your first scene](https://orblitengine.com/docs/start/your-first-scene.md): Building a scene, lighting it, and making it move, with the whole thing as a widget.
- [The editor](https://orblitengine.com/docs/start/the-editor.md): What the Orblit editor is for, and what it is not for.
- [Working with AI assistants](https://orblitengine.com/docs/start/working-with-ai.md): The Markdown copies of this site that language models read best, how to point an assistant at them, and the Orblit skill for Claude Code.

## Concepts

- [How it fits together](https://orblitengine.com/docs/concepts/architecture.md): The three layers of Orblit, the boundary between them, and why it sits where it does.
- [Stating a scene](https://orblitengine.com/docs/concepts/stating-a-scene.md): Why every frame describes the whole scene, what that costs, and how the renderer makes it cheap.
- [Entities and components](https://orblitengine.com/docs/concepts/entities.md): The archetype store, how Dart reaches it, and when you actually need it.
- [Sampled, not stepped](https://orblitengine.com/docs/concepts/sampled.md): Why effects, sprite animation and cutscenes are all functions of a playhead, and what that makes possible.

## Guides

- [Lighting a scene](https://orblitengine.com/docs/guides/lighting.md): Photometric units, the four light kinds, exposure, shadows and image-based lighting.
- [Building an interface](https://orblitengine.com/docs/guides/interfaces.md): One interface document, a familiar styling vocabulary, and real Flutter widgets at the end of it.
- [Working in two dimensions](https://orblitengine.com/docs/guides/two-dimensions.md): Drawing sprites, packing atlases, sprite animation, parallax and tile maps, and how they meet the 3D renderer.
- [Cameras that frame, not follow](https://orblitengine.com/docs/guides/cameras.md): Virtual cameras, bodies, aims and blends. Describing what a shot should contain, rather than where the camera goes.
- [Things that decide for themselves](https://orblitengine.com/docs/guides/agents.md): Steering behaviours for where to go, behaviour trees for what to want.
- [Multiplayer](https://orblitengine.com/docs/guides/multiplayer.md): How Orblit replicates state, who is allowed to change what, and what arrives on the wire.
- [Scene files](https://orblitengine.com/docs/guides/scene-files.md): A scene saved as a document, read back with its problems listed, brought up to date by migrations and edited with diffs that know what changed.
- [Models out of files](https://orblitengine.com/docs/guides/models.md): Playing a file's clips and fading between them, setting joints from a rig, picking material variants, using a file's lights, and bringing in FBX and OBJ.
- [Textures that don't stall](https://orblitengine.com/docs/guides/textures.md): Cooking textures into GPU-ready sets the device chooses from, how they reach the GPU without freezing a frame, and the budgets that decide how large they load.
- [Gaussian splats](https://orblitengine.com/docs/guides/splats.md): Drawing captured places as clouds of 3D Gaussians, from a file or from memory, sorted off the drawing thread and held to what the device can carry.
- [Materials that inherit](https://orblitengine.com/docs/guides/materials.md): Material files that state only what they change, a library that resolves the chain once, groups that override a whole set from outside, and looks that reclothe a scene without editing it.
- [Exporting and importing scenes](https://orblitengine.com/docs/guides/exporting-scenes.md): Writing a scene as glTF, GLB or OBJ with its models grafted in, reading one back so that the round trip returns the same document, and what each format can and can't carry.
- [Assets over a network](https://orblitengine.com/docs/guides/network-assets.md): Fetching assets from a server with a policy that refuses before it downloads, a manifest that verifies what arrived, resumable downloads, and stages so there's always something to draw.

## Examples

- [Running the examples](https://orblitengine.com/docs/examples/running-them.md): The applications you can clone and run today, and what each one is for.
- [A model on screen](https://orblitengine.com/docs/examples/a-model-on-screen.md): Loading a model file, instancing it, and finding out when it did not load.
- [A thousand things](https://orblitengine.com/docs/examples/a-thousand-things.md): Sending a whole scene every frame, and paying only for what moved.
- [A camera that follows](https://orblitengine.com/docs/examples/a-camera-that-follows.md): Two shots, a brain that picks between them, and a blend you get for free.
- [A menu over the game](https://orblitengine.com/docs/examples/a-menu-over-the-game.md): A pause overlay on top of a 3D scene, built from real Flutter widgets, because the scene is one too.
- [Something that chases you](https://orblitengine.com/docs/examples/something-that-chases-you.md): Steering behaviours for where to go, a behaviour tree for what to want, and the line between them.

## Gallery

- [Getting started](https://orblitengine.com/docs/gallery/basics.md): The three examples the gallery lists under Getting started, and the code its panel shows for each.
- [Lighting & shadows](https://orblitengine.com/docs/gallery/lighting.md): The six examples the gallery lists under Lighting & shadows, and the code its panel shows for each.
- [Materials & textures](https://orblitengine.com/docs/gallery/materials.md): The four examples the gallery lists under Materials & textures, and the code its panel shows for each.
- [Sky & atmosphere](https://orblitengine.com/docs/gallery/atmosphere.md): The four examples the gallery lists under Sky & atmosphere, and the code its panel shows for each.
- [Effects](https://orblitengine.com/docs/gallery/effects.md): The four examples the gallery lists under Effects, and the code its panel shows for each.
- [Models & media](https://orblitengine.com/docs/gallery/content.md): The five examples the gallery lists under Models & media, and the code its panel shows for each.
- [Scripting](https://orblitengine.com/docs/gallery/scripting.md): The three examples the gallery lists under Scripting, and the code its panel shows for each.
- [Performance](https://orblitengine.com/docs/gallery/performance.md): The six examples the gallery lists under Performance, and the code its panel shows for each.
- [Showcases](https://orblitengine.com/docs/gallery/showcases.md): The four examples the gallery lists under Showcases, and the code its panel shows for each.

## Reference

- [Packages](https://orblitengine.com/docs/reference/packages.md): Every Orblit package, what it is, which repository it is in, and whether it needs Flutter.
- [Platform support](https://orblitengine.com/docs/reference/platform-support.md): What runs where today, and how much of it has actually been seen to draw.
- [The renderer](https://orblitengine.com/docs/reference/renderer.md): OrblitScene and everything you can put in one. Objects, populations, splats, sprites, lights, sky, weather, post-processing and the render graph.

## Community

- [Join in](https://orblitengine.com/docs/community.md): The Discord, the repositories, and what is actually useful to do with a pre-alpha engine.