Documentation

The manual

Getting started

Read in order. It ends with a complete game.

• Introduction What DriftEngine is, what ships in it, how its packages divide, and where to start reading this manual.
• Installation Add DriftEngine to a project, set up the page, TypeScript and DriftScript, pick a backend for testing, and know what the licence asks of you.
• Working with a coding agent Start a project a coding agent can build on, give the agent the engine's skill, and check every change by looking at the game on both backends.
• Hello world A complete first program. A renderer on a canvas, light, two meshes, a camera, a loop that turns a cube on a fixed clock, and a rule in DriftScript.
• The loop A fixed simulation step, rendering between steps with alpha, pausing without freezing the screen, and the tick count replays and networking key on.
• Moving things Read the keyboard, the mouse, a gamepad and a touch screen through one action map, and turn what you read into movement on the fixed step.
• Your first game A complete 3D game. An arena with physics, a character, crates to push, orbs to gather against the clock, sound, shadows, a HUD, and rules in DriftScript.
• A 2D game A complete breakout game drawn in the XY plane by the same 3D renderer, with a camera that makes it read as flat and one mesh tinted per brick.
• Shipping to the web Build a DriftEngine game into static files, host it anywhere, test it on a phone, and know what a web build carries and why.

Concepts

How the engine thinks: its packages, its two backends, the scene graph, determinism, coordinates, quality and the shape of a frame.

• Packages How the engine divides into packages, what each one costs in a build, how they depend on each other, and which to install for what.
• WebGPU and WebGL2 How the engine chooses between WebGPU and WebGL2, what it reports about the choice, what only WebGPU can do, and how to tune quality per backend.
• The scene graph Nodes, parents and world matrices, bounds that enclose a whole subtree, culling by frustum and by occluder, and levels of detail chosen by apparent size.
• Determinism How a DriftEngine simulation gives the same result every run on every browser, which replays, rollback netcode and the editor's timeline all depend on.
• Coordinates and units Metres, Y up, which way the camera looks, how matrices are laid out, and how a world larger than single precision stays exact.
• Render quality The quality profile a renderer is built with, what each group of options does and costs, the defaults that surprise people, and the dials that move per frame.
• The frame What happens between beginFrame and endFrame, in what order a game issues its work, where custom passes and compute fit, and how the GPU-driven path differs.

DriftScript

The engine's scripting language and how a game uses it: what belongs in a script and what stays in TypeScript, setting it up, the patterns the examples use, every function a script can call, and testing and shipping it.

• DriftScript in a game What the engine's scripting language is for, what belongs in a script and what stays in TypeScript, and how the two share one game.
• Setting up scripts The build that compiles .drs files, loading and binding a script, the services a host gives it, calling it, and hot reload that keeps the game's state.
• Patterns How the examples split work between the page and its scripts, from a record the page owns to a rule that decides and systems over components.
• What a script can reach Every engine module a DriftScript file can import, what the host binds it from, and each function's signature and whether it is deterministic.
• Determinism, testing and shipping What @deterministic and @pure promise and how the compiler holds a script to them, testing a script in Node, CI, and what reaches the bundle.

Rendering

Everything that puts pixels on the screen: meshes and materials, lights and shadows, the sky, the air and water, DriftLight and DriftRay, post-processing, the GPU-driven pipeline, and passes of your own.

• Meshes and geometry Build geometry in code with MeshBuilder or from raw arrays, upload it, rewrite it every frame, and stream big meshes in pieces.
• Materials Surfaces from vertex values or image maps, compressed blocks for every device, shading models for metal, hair, skin and eyes, lightmaps and surface dials.
• Texture arrays and surface effects Many images as one texture, chosen per vertex, so a merged mesh of many materials is one draw, with lit windows, rooms, wear and rain.
• Instancing Thousands of copies of one mesh in one call, culled, moved every frame or played as a crowd, still draws recorded once, and foliage in the wind.
• Splines, ribbons and lines Curves sampled by arc length, banked surfaces swept along them with gaps and colliders, the exact ground on a route, and world-space strokes with real width.
• Translucent and additive meshes Glass that colours the light through it, refraction, light that adds instead of covering, untoned draws, and transparency in any order.
• Decals Marks on surfaces two ways: baked into a mesh once from its own triangles, or projected every frame onto whatever was drawn.
• Lights Point lights, spots, rectangular lights, measured photometric profiles and cookies, how a frame picks the lights it shades, and thousands of them.
• Shadows The sun's shadow map focused around the player, its static, peeled and moving layers, one caster list for every pass, and the quality dials.
• Light in the air Shafts of light with dust in them, cut to shape by a window's shadow, fire and smoke plumes, and a medium that fills a room with light.
• DriftLight Every fixed light in a scene lights the world, near or far: the lights the frame does not shade summed into an occluded volume.
• DriftRay Light that bounces, traced on the GPU through signed distance fields into the probe grid every frame, so a room follows its own changes. WebGPU only.
• Reflections What shiny surfaces show: the sky gradient, a captured room, a grid of probes baked a little at a time, bounced light and an HDR sky.
• Sky and atmosphere A procedural sky with sun, moon, stars and clouds, a celestial clock for a real latitude and date, and a palette that lights the hours.
• Fog and weather Height fog and linear fog, the underwater atmosphere, one wind for the scene, rain that stops under roofs, lightning, and storm debris.
• Water One water for sea, lake, fountain and canal: waves the wind builds, Fresnel and planar reflections, caustics, and the view from below.
• Wet surfaces A world that gets wet in the rain and dries after, puddles that fade at their rims and mirror the street, and the sheen of an oil slick.
• Post-processing The scene target screen effects need, brightness kept above white, bloom, ambient occlusion, and multisampled and temporal antialiasing.
• Colour and motion The tone curve, exposure and an eye that adapts, colour grading with a lookup table, vignette, grain and fades, depth of field and motion blur.
• DriftTR Draw the scene at a fraction of the output size and rebuild the full picture from this frame and the ones before it, on WebGPU.
• The GPU-driven pipeline A second pipeline for very large scenes on WebGPU: the device culls, picks detail and draws clusters, and shades once per material.
• Particles Sparks, smoke and motes from a pool and a batch, deterministic emission, textured sprites and flipbooks, particles placed by your own plan, and birds.
• Text and overlays A built-in pixel font for heads-up displays, panels and keycaps, a portrait in a box of its own, and distance-field text in the world.
• Picking What is under the pointer, from meshes registered for it, with the hit's point and distance, moving pickables, and a set of your own.
• Custom passes and compute Add a draw pass of your own, fill targets it owns before the frame opens, dispatch compute on WebGPU, and keep a pass right on both backends.

Worlds

Ground and the worlds built on it: terrain, worlds bigger than a float, hierarchical detail, worlds built from a kit, procedural solids, splats, textures as programs, streaming, and capture from video.

• Terrain A heightfield whose queries answer the ground that is drawn, a clipmap with matched seams, blended materials, colliders, and heights kept as textures.
• Large worlds The cell grid a large world streams in, streaming by where the camera will be, and freezing cells so streaming never changes what the simulation computes.
• Hierarchical detail Drawing each region of a world at the level its distance deserves, crossfading between levels, and baking proxies and impostors offline.
• Worlds from a kit A world built from a few pieces placed many times, carried as its placements in a .drft, expanded by arithmetic, and paged in region by region.
• Procedural solids Closed solids built in code, from boxes and lathes to sweeps, combined by booleans, smoothed, painted and handed to the renderer as meshes.
• Gaussian splats Captured places drawn as hundreds of thousands of soft ellipsoids, composed into a scene of meshes, sorted off the frame and streamed in blocks.
• DriftTexture Textures as small programs over a latent image, decoded per pixel on the GPU and on the CPU alike, animated by the simulation's clock and carried in .drft.
• Texture streaming Deciding which tiles of a texture are resident by running the simulation ahead to see where the camera will be, and giving up on tiles that will not come.
• Writable textures Marks written into a texture at run time, allocated only where they land, recorded beside the input so a replay or a rollback draws the same wall.
• DriftCapture A video of a place turned into a surface, a collider, materials and proposed entities on the player's own device, and each stage's measured limits.

Simulation

Everything that moves on the fixed clock: rigid bodies and their queries, characters, vehicles, ragdolls and cloth, animation, navigation, entities, chemistry and agents.

• Rigid bodies A deterministic physics world of boxes, spheres, capsules, cylinders, hulls and meshes, with soft contacts, sleeping islands and a fingerprint.
• Joints Seven kinds of joint between bodies, with one-sided limits, motors and a breaking load, and a six-degree-of-freedom joint described axis by axis.
• Queries and colliders Rays, swept shapes and overlaps against the world, sensors and contact events, a collider set for kinematic movement, and scenery that streams in by region.
• Characters A kinematic character controller with coyote time and jump buffering, ground surfaces for roads and decks, water, and an escape for a trapped body.
• Vehicles A raycast vehicle of a chassis body and wheels that are rays on springs, gripping by tyre curves you supply, on bodies or an analytic road.
• Ragdolls and cloth Ragdolls built from a skeleton's joints and driven toward an animated pose, and cloth that hangs, blows, drapes and pushes what it lands on.
• Animation Skeletons, clips sampled at a time you supply, blend trees, state machines, two-bone IK, retargeting, root motion, springs and morph targets.
• Navigation Routes over a graph of lanes and roads, and over a navigation mesh built from a level's geometry, with the following of a route in DriftScript.
• Entities Generational handles, components as typed columns, systems that declare what they touch, prefabs, saved scenes and rewinds, from DriftScript and TypeScript.
• Chemistry Matter as parcels of real substances, whose heat, phase changes, burning and smoke follow from conserved energy, steered from DriftScript.
• Agents and behaviour Behaviour trees that pause, interrupt and resume, and agent sessions whose deterministic floor keeps them moving while a model answers late.

Content

Getting what artists make into a game: importing models, the .drft container and how it streams, sound and music, and the tools that bake and check them.

• Importing models Reading glTF, OBJ, STL, USD, 3MF, FBX and Blender files, at build time with the baker or in a worker when a player brings a file.
• The .drft container The engine's own file: loaded without parsing, streamed onto the screen as it arrives, and opened by every future reader.
• Sound and music A mix of buses and snapshots, sounds by name, music whose kick drives lights, sounds placed among rooms and walls, and scripts that play it all.
• Command-line tools The baker and its options, comparing two containers, building a distance-field font, the visual gate, the frame audit and the dev servers.

Interface

How a player reaches the game, and what they see: every input device through one action map, cameras that cut between shots and fly keyed paths, the 2D layer of sprites and tilemaps, menus built as a tree, and a WebXR session read every frame.

• Input Keyboard, mouse, gamepads and touch through one action map, with rebinding and saving, prompts for the device in use, rumble, and scripts that read it.
• Cameras and cinematics The camera, a rig that cuts between shots for replays and cinematics, cinematics written as data, keyed camera paths, and re-timing a stretch of play.
• Sprites and tilemaps The 2D layer: textured quads batched in the order drawn, sheets cut into frames, tilemaps that cost the view, and a camera for a 2D world.
• Interfaces Menus and heads-up displays as a retained tree: layout without coordinates, focus, routing, clipping and scrolling, themes, text, and scripts.
• XR Asking a browser what it can present, entering a WebXR session, and reading the head, controllers and hands each frame. Drawing into a headset is not built yet.

Systems

What a game keeps, shares and ships: saves and preferences, networking and rollback, recorded clips, the window and the host, and packaged applications.

• Saves and preferences The store a game saves to, preferences checked field by field, saves to a server that answers later, and a world written out and read back across a change.
• Networking and rollback Two peers simulating one match over a lossy link, inputs as bytes, a rewind that replays a wrong guess, and an authority with clients that predict.
• Recording and clips Saving a still, recording a clip as it plays with the mix underneath, and rendering one frame by frame with every frame stamped at its own instant.
• Display and the host The window, the screen and the shell as capabilities a game asks about: window mode and size, orientation, focus and quitting, files, and the boot badge.
• Packaging an application Turning a web build into a desktop, mobile or native application with drift-package, and the one host a game writes its settings and its exit against.

Tools

Looking inside a running game: the panels a shipped build can carry, and the instruments beside them.

• In-game tools An inspector, a console, a profiler and a network panel over a running game on a key, with undoable edits, plus core's frame meter and contact probe.

Coming from another engine

For developers who know another web engine: what each of its ideas is called here, with the same code written in both.

• Coming from Three.js What a Three.js scene, renderer, animation loop, geometry, light and loader become in DriftEngine, with the same program written in both.
• Coming from Babylon.js What a Babylon.js engine, scene, render loop, mesh builder, light, loader and Havok body become in DriftEngine, with the same program written in both.
• Coming from PlayCanvas What a PlayCanvas application, entity, component, script, light, asset and rigid body become in DriftEngine, with the same program written in both.

API reference

Generated from the engine's declaration files, an area at a time. Every symbol has a page with its signature, its members and its parameters.

The runtime

• Core42 · @driftengine/core
• Scene graph4 · @driftengine/core
• Large worlds36 · @driftengine/core
• Maths29 · @driftengine/core
• Geometry72 · @driftengine/core
• Host14 · @driftengine/core
• Instrumentation6 · @driftengine/core

Rendering

• Renderer475 · @driftengine/core
• DriftTexture171 · @driftengine/texture
• Environment12 · @driftengine/core
• Cameras and shots14 · @driftengine/core
• Splats46 · @driftengine/splats
• Screen helpers47 · @driftengine/core

Simulation

• Physics205 · @driftengine/physics
• Animation30 · @driftengine/animation
• Behaviour9 · @driftengine/core
• Navigation41 · @driftengine/nav
• Terrain32 · @driftengine/terrain
• Chemistry147 · @driftengine/chemistry
• Entities39 · @driftengine/entities

Content

• Model loading181 · @driftengine/assets
• The .drft container140 · @driftengine/drft
• Recording9 · @driftengine/media

Interface and input

• Input25 · @driftengine/core
• The 2D layer116 · @driftengine/ui2d
• XR44 · @driftengine/xr

Systems

• Audio91 · @driftengine/audio
• Networking87 · @driftengine/network
• Intelligence88 · @driftengine/ai
• DriftScript bindings22 · @driftengine/script

Making and shipping

• Editor model15 · @driftengine/editor
• In-game tools97 · @driftengine/tools
• DriftCapture200 · @driftengine/capture
• Packaging10 · @driftengine/package

Examples

Complete programs from the engine's repository. Each runs in its page, on WebGPU where your browser has it, and the gallery shows a still of every one.

• Agents Villagers whose routines shelter from the rain and resume, and a crier who asks a model.
• Light in the air A sunbeam through a window, fire and smoke, and a medium that fills the room.
• Animation A figure walking a circle on a blend tree, reaching for a lantern, its pace set in DriftScript.
• Antialiasing sceneSamples at 1 and at 4, on the edges where the difference is visible.
• Audio A courtyard heard from the camera: a scripted bell, a muffled cart, lanterns on the kick.
• DriftCapture A synthesised clip of a room fused into a surface, proposed as entities, that balls land on.
• Characters A character controller in a valley of steps, a slab, a bridge and a pond.
• Chemistry A campfire where everything heats at its own rate, with rain, wind and green wood scripted.
• Cinematic A buggy and a jump, cut by a scripted director, a cinematic as data, and a keyed path.
• Display A video settings screen drawn from what the host says it can do, and why where it cannot.
• DriftLight Seven hundred candles, the sixteen nearest shaded exactly and the rest summed by DriftLight.
• DriftRay Bounced light traced on the GPU, following a wall that changes colour. WebGPU.
• DriftTexture Materials as programs decoded per pixel, one animated by the simulation's clock. WebGPU.
• DriftTR The scene drawn smaller and rebuilt to full size by temporal reconstruction. WebGPU.
• Entities Frogs catching fireflies over a pond, every rule a DriftScript system, with time that rewinds.
• Your first game A complete 3D game: physics, a character, shadows, sound, a HUD, and its rules in DriftScript.
• A 2D game A whole game — paddle, ball, bricks, score, lives, win and loss — laid out in the XY plane.
• A garment on a skeleton A figure walking a circle in a cape: skinned cloth on the device, and a finer mesh bound to it.
• GPU-driven pipeline 2,500 meshes culled and drawn by the GPU-driven pipeline. WebGPU.
• Hierarchical detail A city of 144 blocks drawn at the level of detail each one's distance deserves, crossfaded.
• Input A puck driven by keys, a gamepad or a thumb, a controls screen that rebinds, and rumble.
• Instancing Ten thousand rocks in culled batches, and a batch rewritten every frame.
• Interface A pause menu and options over a running scene: laid out, themed, clipped, in DriftScript.
• Joints A bridge of hinged planks, a door on a motor, a swinging lamp and a breakable chain.
• Worlds from a kit A street built from copies of three pieces, as placements and expanded, with rules in a script.
• A room lit by a lightmap A room lit by a bake: a page read at each surface's second coordinates, and a shadow in it.
• Lights Lamps that cast, a spot with a cookie, a photometric profile and a window that is an area light.
• World-space lines Strokes with width in metres, an antialiased edge, and a buffer rewritten in place.
• Colour and motion Exposure, a colour grade, vignette, grain, a fade, depth of field and motion blur.
• Materials Image maps built in code, metalness and roughness, and the per-draw surface dials.
• Models A turntable that reads glTF, OBJ and STL in a worker and streams them, or a model you drop.
• Navigation Villagers walking lanes in DriftScript, and dogs crossing a square on a mesh built from it.
• Netplay Two players in one match over a lossy link, rewinding when a guess was wrong, staying in step.
• 2D overlay and text Screen-space panels and the built-in font, a keycap prompt, and a portrait in a box of its own.
• Particles Sparks, smoke and motes from pools, emitted deterministically.
• Physics A wall of crates, a ramp of rolling shapes, and a cannon scripted in DriftScript.
• Picking Hover and click: what is under the pointer.
• Ambient occlusion and bloom Ambient occlusion, bloom, and the two settings bloom is useless without.
• Queries and colliders A laser casting rays, a sensor counting what stands on it, and a kinematic wall.
• Ragdolls and cloth A ragdoll shoved down the stairs, a flag in a gusting wind, and a sheet dropped over a crate.
• Recording A still, a clip recorded as it plays, and one rendered frame by frame with its score.
• Saves A garden bed that saves to a server that can fail, loads across a change, and keeps preferences.
• Writable textures A wall a scripted turret scorches, with a clock that runs backwards and burns the marks again.
• Sky and atmosphere A day in ninety seconds: sun, moon, stars, clouds, and lamps that come on at dusk.
• Procedural solids A gatehouse built from closed solids, with windows and a doorway cut by booleans.
• Gaussian splats A rock garden of Gaussian splats, sorted off the frame, with geometry standing in it.
• Sprites A tilemap garden and a gardener who picks its flowers, one sprite pass, in DriftScript.
• Hello world A lit cube turning at a rate a DriftScript rule sets. The one to copy out to start a game.
• Streaming a large world A town far from the origin, streamed in cells by prediction, with walkers that freeze and thaw.
• Terrain A valley drawn as a clipmap, painted and planted by rules in DriftScript.
• Tools An inspector, a console and a profiler over a running game, and edits that undo.
• Vehicles A raycast car on a ring of cones, driven by a DriftScript driver or by you, on tarmac or ice.
• Water The open sea under three winds, a planar reflection, and caustics under a pier.
• Fog and weather Fog, one wind, rain, lightning and puddles that mirror the street.
• XR A headset across a room: its head, controllers and hand read each frame, a lamp on the trigger.

Elsewhere

• Release notesWhat changed in every version, newest first.
• DriftScriptThe engine's scripting language, with its own guide and a playground.
• SourceThe engine on GitHub, Apache-2.0.
• npmEvery package under the @driftengine scope.