Running the examples

The pages in this section are complete programs you can paste into lib/main.dart. This one is about the examples that already exist as applications, because reading a technique next to a slider that changes it is worth a good deal more than reading it on its own.

All of them render. The applications in orblit-examples are set up for macOS, and the engine carries a second copy of the gallery that builds for the other platforms too. See platform support for how far each platform has got.

The gallery

Every rendering technique, one at a time. Pick one from the list, change it with the controls, and read the lines that do it in the panel beside it. The code there is coloured by what each word is, and a button copies it or opens it wider.

git clone https://github.com/ChxisB/orblit.git
git clone https://github.com/ChxisB/orblit-examples.git
git clone --recurse-submodules https://github.com/ChxisB/orblit-script.git
bash orblit/packages/orblit_filament/darwin/setup.sh   # the Mac setup, once
cd orblit-examples
./tool/link_local.sh          # point the examples at the sibling checkouts
cd gallery && flutter run -d macos

orblit-script is there for the three TypeScript examples, and --recurse-submodules fetches the JavaScript engine they run on. Without that clone, link_local.sh skips the gallery and says so. The setup line is the Mac setup, pointed at your clone rather than at pub’s cache.

ORBLIT_EXAMPLE=weather flutter run -d macos opens on one of them by name, which is what you want for a screenshot or a demo that should start where it means to.

There are 39 of them: the engine’s 36, and three that run TypeScript. The list keeps them under nine headings, in the order they’re worth meeting, and each heading has a page here with every example’s code as its panel shows it: Getting started (3), Lighting & shadows (6), Materials & textures (4), Sky & atmosphere (4), Effects (4), Models & media (5), Scripting (3), Performance (6) and Showcases (4). Only the heading holding the example on screen starts open, and clicking a heading opens or folds it. A sample of what is in there:

A scene as a widget	A lit surface composited by Flutter, laid out like any other widget
Lights	Sun, point and spot, in lux and lumens, with the shadows each casts
Day and night	A sun and a moon crossing the sky, with the camera metered for both
Weather	Haze, banks of cloud and falling weather, carried by one wind
A thousand objects	A whole scene sent every frame, and only what moved paid for
Meshes	A glTF file, loaded once and instanced, with failures reported back
Imported models	Clips, material variants and lights out of glTF files, named by the files themselves
Textures	A wall of textures named at once: pictures, Basis and cooked sets chosen by the device, lit by a picture filtered at run time
Virtual cameras	Third person, first person and flat, blended between, framing drawn
Gaussian splats	A cloud of 3D Gaussians drawn as ellipses, sorted back to front off the render thread and held to what the device can carry
Sprites	Pixel art in layers: one draw a layer, and a backdrop that scrolls without resending a tile
Scene files	A .oscene document parsed and drawn, in 2D and in 3D, with an edit applied as a diff rather than a rebuild
Runner	A runner you can play: dodge, jump, slide and pick up coins

Some of them want files the repository doesn’t carry. The Bistro and Textures examples use the Bistro scene, which the engine’s tool/fetch_bistro.sh downloads, and tool/fetch_import_samples.sh fetches the models the Imported models example shows. The Video example plays a film you name, through ORBLIT_VIDEO or by pasting a path into its settings.

The Runner is a game rather than a demonstration. Click it, then use the arrow keys or WASD: left and right change lane, up or Space jumps, down slides under a bar, and Esc pauses. Its settings are Autopilot, Can’t crash, Top speed (20–40 m/s) and Start again. Every model and texture in it is built in code and handed over with OrblitResources.provide, so it needs no download.

Most of them live in the engine’s own orblit_examples package rather than in the examples repository, because the editor shows the same ones beside the project you are working on. An example written twice is an example that drifts.

On other platforms

The engine repository has its own gallery app, examples/gallery, with the 36 engine examples and targets for macOS, iOS, Android, Linux, Windows and the web. It depends on the packages by path, so there’s nothing to link:

cd orblit/examples/gallery
flutter devices               # a phone or simulator goes by its id
flutter run -d <id>           # or -d linux, windows or chrome

Each platform wants its machine set up first, and setting up each platform covers what that takes. On a Mac, that includes running packages/orblit_filament/darwin/setup.sh once, for iOS as well as macOS.

On a phone there’s no environment to set ORBLIT_EXAMPLE from, so a button over the scene opens a list instead. In a browser the switches go in the query string, as ?ORBLIT_EXAMPLE=Sprites. The web build also needs the renderer compiled to WebAssembly and copied into web/ first, which setting up the web walks through.

This gallery shows the scene and nothing else: no settings, no code panel and no headings, and nothing an example draws over its scene, so the Runner stands at the start with nothing to press. Of the platforms it builds for, it has been seen to draw on macOS, the iOS simulator, an Android handset and Chrome. Linux has only been run on Mesa’s software rasterisers, and nothing has drawn on Windows yet.

The viewport

The narrower point, made as plainly as possible: a Filament scene as an ordinary Flutter widget. It lays out, it clips, and it sits beside a panel that resizes it.

cd orblit-examples/viewport && flutter run -d macos

If you only believe one claim on this site before trying the engine, make it this one, because everything else follows from it.

The simulation

The engine with no window at all: an entity-component world, a transform hierarchy, a system written in Dart over column views, and the result replicated to a second world.

dart run orblit-examples/simulation/bin/simulation.dart

Plain Dart, so it runs anywhere, including a CI runner with no display. That’s the part people underestimate: most of the engine is testable without a GPU, and most of its own tests do exactly that.

Orblit Craft

A whole small game rather than a demonstration: a block world you can walk around, dig and build in.

git clone https://github.com/ChxisB/orblit-craft.git
cd orblit-craft && flutter run -d macos

It generates 129 blocks square and 48 tall from a seed, meshes it as 25 columns 32 blocks across, so a dig rebuilds one column rather than the world, and hands those to the renderer. It exists to put weight on the parts the small examples do not: geometry built at runtime through orblit_mesh rather than loaded from a file, one material for a whole landscape, and cutout geometry drawn against blended.

That weight is the point. The 16-bit index limit in orblit_mesh was found by this game and is why the package now writes 32-bit ones.

If one of them does not build

The commonest cause is the checkouts not being siblings, or not being named exactly orblit, orblit-examples and orblit-script. The overrides link_local.sh writes aren’t committed, so nothing ships wired to a path on one machine. That’s the right call, and it does mean the script has to be run.

The next commonest, on a Mac, is 'generated/<name>_material.h' file not found after a git pull in orblit. New materials need the Mac setup run again, and nothing runs it for you.

If it’s something else, that’s worth a message on the Discord. An example that won’t build is a bug of ours, not a mistake of yours.