voxolithEngine
@voxolith/engine: entities and colour roles, the generator contract, placement, instances, stamping, workers, input, animation and atmosphere.
@voxolith/engine sits between the renderer and an app. It holds the
entity, the unit a world is built from (a voxel model with an anchor and named colour roles),
and everything a host does with one: palette it, orient it, place it, stream it, draw it by
reference, move it, animate it. It also holds the generator contract, so a host can build a
model from a seed at runtime.
The engine consumes baked models and never authors them. The authoring toolkit (dense volumes,
rasterisers, noise, branch growth, canopy carving, rock masses) and the headless preview renderer
are @voxolith/gen-kit, beside the generators.
Entry points
| import | contents |
|---|---|
@voxolith/engine | entity and generator contracts, registry, share codes, palette allocation, orientation, placement, chunked worlds, instance layers, brick stamping, load events. Runtime-safe: no DOM, no GPU, no filesystem |
@voxolith/engine/vox | MagicaVoxel import and export of entities |
@voxolith/engine/worker | an off-thread generator pool with queue controls, an optional IndexedDB model cache and its controls, and a scene worker that encodes models and bakes static instance sets |
@voxolith/engine/animation | rigs and clips: play, pose, bake posed models at any heading, wound and sever, pose cache, crowds. Headless and pure |
@voxolith/engine/atmosphere | time of day and weather as configuration, translated into renderer settings. Headless and optional |
@voxolith/engine/input | pointers, keys, wheel, pointer lock, gamepad, gestures, actions, on-screen touch controls, orbit and look cameras. DOM only |
@voxolith/engine/vite | build side, for vite.config.ts: serviceWorker(), a Vite plugin that emits the app's service worker (precache, runtime rules for fetched data, a cache per build). Runs in the build, never in the browser; imports only types from vite |
@voxolith/engine/pwa | browser side: registerServiceWorker() under the app's base, with onOfflineReady and onUpdate callbacks and no UI. Skips dev servers and localhost |
The subpaths are split by realm: the barrel runs anywhere (a worker, a bun script, a test), input
needs a DOM, the worker entry has a main-thread half and a worker half, and the service worker
has a build half (vite) and a page half (pwa), covered in the manual's
Offline and installing.
import { PaletteAllocator, blitModel } from "@voxolith/engine";
import { entityFromVox } from "@voxolith/engine/vox";
const tree = entityFromVox(await (await fetch("oak.vox")).arrayBuffer(), { kind: "tree" });
const palette = new PaletteAllocator();
const { base } = palette.allocateFor(tree);
blitModel(world, tree.model, { x: 64, y: 0, z: 64 }, base);
renderer.updatePalette(palette.buildPalette());The pages
Entities and roles
The entity shape, why voxel values are roles and not colours, palettes and materials.
The generator contract
EntityGenerator, ParamSpec, the registry and the generation context.
Share codes
A generator, its parameters and a seed packed into a short string that rebuilds the model.
Placement and worlds
Orientations, stamping into dense and brick worlds, chunk residency, scatter and variant pools.
Instances
Drawing models by reference at any yaw, with palettes of their own.
Stamping and crowds
Moving things through a brick world, and many animated members on a budget.
Workers
The generator pool, the IndexedDB model cache and the scene worker.
Load events
One tracker the loaders report their phases into, for a loading screen and a load timeline, and the controls an app steers its load with.
Input
One input per surface, gestures, actions, touch controls and camera controllers.
Animation
Rigs, clips, poses, baking by inverse mapping, and damage.
Atmosphere
Time of day, weather presets, transitions and the translation into renderer settings.
MagicaVoxel
.vox files in and out as entities.
The full list of exports is in the API reference.