voxolithExamples
The live Voxolith example pages and apps, from one .vox model to a streamed valley in 2 cm voxels, with source and what each shows.
The examples are small, complete programs: each page is one main.ts in
voxolith/examples, running live at
voxolith.github.io/examples/. They all need a browser with WebGPU. Each page below
says what the example shows, links the live page and its source, points at the APIs it uses, and
lists the URL options it reads.
| example | shows | size |
|---|---|---|
| hello-vox | load a .vox model and draw it with a turning camera | ~35 lines |
| orbit | a voxel grid written by hand, an orbit camera, rendering on demand | ~55 lines |
| minecraft-region | drop a Minecraft .mca region and fly through it in first person | ~85 lines |
| world | a generated valley: terrain, river, village, forest, a lamp to carry, day and night, weather | ~470 lines + layout |
| valley | the same valley at 20, 50 or 100 voxels per metre: refined models as instances, streamed ground, rats at 1 cm | ~490 lines |
| nightwood | first person in a misty forest at night at 20, 50 or 100 voxels per metre: moonlight, a lit cottage, fireflies, fog as the view distance | ~270 lines |
| temporal | temporal accumulation of shadows and AO: a moonlit scene, a one-tap toggle, soft shadows, GPU time off and on | ~320 lines |
| creature | rigged, animated rats you can wound and dismember with a tap | ~375 lines |
| swarm | hundreds of animated rats through one crowd, with a live cost overlay | ~150 lines |
| instances | trees and a crowd drawn by reference, nothing written into the world | ~145 lines |
| bench | the renderer benchmark: one deterministic scene with every expensive renderer path, four fixed views, at 20, 50 or 100 voxels per metre | ~470 lines |
If you are new, read them in that order: each builds on ideas from the ones before. The tutorial walks through most of the same ground one step at a time.
Running them locally
git clone https://github.com/voxolith/examplesClone it into a workspace with the renderer, engine and generators, as in
Installation, add "examples" to the workspace list, then:
bun install
bun run --cwd examples devOpen the https://localhost:5173 URL and pick an example from the landing page.
Common URL options
Every example reads a few options through the shared startup code (src/shared/boot.ts):
| option | effect |
|---|---|
?diag | show the adapter, the 3D texture limit and the storage binding limit in the page |
?perf | where the example uses makePerf: show the frame-time and render-scale overlay; all but the bench also log the load timeline to the console, with the load time and "first frame at X s" in the overlay's label |
?e2e | expose test hooks on window for the end-to-end input checks; not for normal use |
Every page also shows the same loading screen while it loads: one row per step the page lists and an overall bar, then a corner pill for anything that continues in the background. A load that fails says so on that screen.
GPU validation errors and a lost device are shown in the page too, since a phone has no console.
Offline
After one visit online, every example page loads offline, including pages you never opened: a
service worker caches the whole build on the first visit (see
Offline and installing). Generated models come from the
IndexedDB model cache, or are generated again in the browser, and the pages with instanced scenery
read their models' encodings and static bakes from a second IndexedDB cache, the
scene cache (voxolith-scene, up to
2.5 GiB, least recently used out first), or compute them again. Both caps are sized to what the
pages store at every scale (106 MB of models, 1816 MB of encodings and bakes, measured). With
the caches, a coarse first stage and the ground filled on workers, a warm first frame of
nightwood at 100 voxels per metre is 1.0 s, where it was 30.8 s with the model cache alone
(measured). The examples only cache; they are not an installable app. A new deploy takes
over quietly and runs on the next load, and a deploy that changed a worker's code starts its cache
cold once, since each is salted by its worker's hashed URL. The dev server caches nothing. A
production build served from localhost keeps the model and scene caches but registers no service
worker, so it does not work offline there.
Apps
Larger programs built on the same packages, each in its own repository:
- Viewer: open MagicaVoxel
.voxfiles and Minecraft.mcaregions, or build models from the generators and share them as codes. Installable, and it works offline after one visit, including every sample you have opened. Source - Demolition Shot: aim, release, watch it crumble. A mobile demolition game and installable PWA, the engine's showcase. Source
- Editor: a voxel editor, in its early days. Installable, and it opens offline after one visit. Source
Deploying
Ship a Voxolith game - HTTPS for WebGPU, the Vite settings the renderer needs, base paths with import.meta.env.BASE_URL, and a GitHub Pages workflow.
hello-vox
The smallest useful Voxolith program: fetch a MagicaVoxel .vox file, convert it to a Y-up grid, and render it with a slowly turning camera.