voxolithManual
Task-by-task guide to building a game on Voxolith, from storing a world and placing models to input, lighting, weather, performance and deployment.
The manual is organised by task. Each page answers one question you will have while making a game: how do I do this, which parts of Voxolith are involved, what does it cost, and what goes wrong. Pages are short and link out to the API reference and to the concept pages of each package when you need the full picture.
If you have not drawn anything yet, start with Getting started and the
tutorial. The manual assumes you have a canvas, a GpuContext from initGpu
and a Renderer from createRenderer.
How the pieces fit
Voxolith is three layers, and the manual follows their split:
@voxolith/rendererdraws. It holds the world as bricks, draws instances, lights and atmospheric effects, and knows nothing about entities, weather or gameplay.@voxolith/engineis the vocabulary between them: entities and colour roles, palettes, placement, streaming, instances, input, animation and atmosphere presets.- Generators (
@voxolith/gen-*) bake models: trees, rocks, buildings, creatures, terrain.
Your game decides what happens and when. Where the engine offers a helper for a policy (a phone profile, a weather rule, a quality setting), it is a suggestion the game is free to replace.
The world
Worlds and storage
Dense grids, bricks, editing voxels, what memory costs.
Palettes and roles
256 world slots, colour roles, materials, restyling.
Entities
Models with an anchor and roles; orientations; stamping.
Using generators
Trees, rocks, houses from a seed; share codes; finer scales.
Instances
Draw one model many times at any heading, without stamping.
Streaming
Chunked worlds around the camera; deterministic scatter.
Interaction
Input
One input per surface, gestures, actions, touch controls.
Cameras
Orbit, first person and chase cameras; yaw conventions.
Picking
Turn a tap into a ray, a ground point or a voxel.
Animation
Rigged creatures, clips, crowds and damage.
The look
Lighting
One key light, up to 32 point lights, shadows and glow.
Atmosphere and weather
Time of day, fog, clouds, rain, snow, wet ground.
Water
The water material: ripples, refraction, wind.
Effects
Explosions, muzzle flashes, debris and stains.
Assets and shipping
File formats
MagicaVoxel .vox in and out, Minecraft regions.
Workers and caching
Generate off the main thread; keep models in IndexedDB.
Loading screens
What is loading, of how much; time the load and mark the first frame.
Managing loading
Warm pipelines up, place off the main thread, steer the generation queue and the model cache.
Performance
Render on demand, quality presets, adaptive scale.
Mobile and PWA
Phones, lighter profiles, touch controls.
Offline and installing
A service worker per app: offline after one visit, cached data, deploys, manifests.
Deploying
HTTPS, base paths, GitHub Pages.
7. Performance and deploying
Rat Hunt, step 7: a quality menu over QUALITY_PRESETS, adaptive render resolution with makePerf, then a GitHub Actions workflow that publishes to Pages.
Worlds and storage
How a Voxolith world is stored as 8³ bricks, when to use a dense grid instead, how to edit voxels, and what a world costs in memory.