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 runs on 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.

git clone https://github.com/ChxisB/orblit.git
git clone https://github.com/ChxisB/orblit-examples.git
cd orblit-examples
./tool/link_local.sh          # point the examples at the sibling checkouts
cd gallery && flutter run -d macos

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

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.

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 run -d ios            # or android, linux, windows

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 is covered under platform support.

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, and hands the result to the renderer as one draw. 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 and orblit-examples. 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.

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.