Getting started

Introduction

What DriftEngine is, what ships in it, how its packages divide, and where to start reading this manual.

Install npm install @driftengine/core

DriftEngine is a 3D game engine written in strict TypeScript. It draws with WebGPU, and falls back to WebGL2 when a browser can't give it a usable WebGPU device. Your game code doesn't change between the two: you ask for a renderer, and the engine tells you which backend it got and why.

A game built on it ships as a web page. The same build can also be packaged as a desktop app for Linux, Windows or macOS, or as an Android app, and it can run on a native window with no browser in the process at all.

You write a game as a program. You create a renderer on a canvas, build or load meshes, step a simulation on a fixed clock and draw frames. There is an editor, with a scene tree, an inspector and a timeline you can scrub backwards, but nothing in the engine requires you to use it.

What ships

Rendering. A forward renderer with clustered lighting, cascaded sun shadows, point and spot lights with their own shadows, rectangular area lights, physically based materials, ambient occlusion, bloom, colour grading and motion blur. On WebGPU there is more: a GPU-driven path that culls instances and clusters on the device and draws them with one indirect call, DriftTR temporal reconstruction, which renders below output resolution and resolves back up, DriftRay traced indirect light, and DriftLight, which lets thousands of fixed lights reach a frame.

Worlds. Heightfield terrain whose levels of detail meet without cracks, worlds larger than single precision can address, hierarchical detail for distant geometry, streaming that does its work in slices of a frame, Gaussian splats, and DriftTexture, where a texture is a small compiled program over a learned field instead of an image.

Simulation. A deterministic physics engine of its own: rigid bodies, seven kinds of joint, a character controller, raycast vehicles, ragdolls, cloth and buoyancy. Skeletal animation with blend trees, state machines, two-bone IK and retargeting. Navigation meshes, an entity component system, and agents.

Content. Models import from glTF, OBJ, FBX, USD, STL, 3MF and Blender files, and bake into the .drft container, which streams a coarse outline of a model while its geometry downloads. Audio has a mix tree, positional sources, reverb zones, and a synthesised stand-in for every sound you haven't recorded yet.

Interaction. Keyboard, mouse, touch and gamepads behind one action map. Cameras, including a third-person rig that won't put its lens inside a wall. A 2D layer for sprites and interface, and WebXR.

Systems. The simulation runs on a fixed step with seeded randomness, so a run can be replayed exactly, and the networking is built on that: lockstep, and an authoritative host with prediction and rollback. Video capture, saves, and DriftScript, a scripting language whose modules reload while the game keeps running.

Shipping. Desktop and Android apps from one manifest, Steam cloud saves and achievements, and a native host.

Packages

Install what you use and nothing else. @driftengine/core is the runtime every game needs: the loop, the renderer, input, cameras, the scene graph and geometry. It also re-exports the whole of @driftengine/physics. Every other package is optional and takes core as a peer dependency, so one you never install costs you nothing.

Package	What it is
`@driftengine/ai`	Provider-neutral intelligence sessions, typed tools and context, and an agent loop that does not wait
`@driftengine/animation`	Skeletons, clips, poses and the graphs over them: sampling as a pure function of a caller-supplied time
`@driftengine/assets`	Model readers and the streaming loader for the .drft container
`@driftengine/audio`	Layered stems, synthesis, rhythm analysis and positional placement
`@driftengine/capture`	A video to a playable scene, on the player's device: the models it runs and the stages that use them
`@driftengine/chemistry`	Thermochemistry of bulk matter: elements, species, substances and what they turn into
`@driftengine/core`	The runtime of DriftEngine, a WebGPU game engine with a WebGL2 fallback: renderer, loop, input, cameras, scene graph and physics
`@driftengine/create`	Starts a DriftEngine game: a Vite and TypeScript project, its instructions for a coding agent, and the engine's skill
`@driftengine/drft`	The .drft container: a streaming format for baked 3D scenes
`@driftengine/editor`	The model of a scene editor: a tree of what exists, an inspector over what is selected, and play-in-editor
`@driftengine/entities`	Entities with generational identity, component storage, systems and scenes
`@driftengine/media`	Clip encoding and frame delivery for recording what the engine draws
`@driftengine/native-host`	The engine on a native window and a native WebGPU device, with no browser between them
`@driftengine/nav`	A navigation mesh: geometry to walkable convex polygons, and a straight line across them
`@driftengine/network`	A transport seam, rewind and replay, lockstep and an authoritative host, on the fixed-step loop
`@driftengine/package`	Builds an installable application from a game built on the engine
`@driftengine/physics`	Collision shapes, spatial queries and swept kinematic collision
`@driftengine/script`	The drift/* capability bindings: what this engine provides to DriftScript, and the only place the two are coupled
`@driftengine/splats`	Gaussian splat captures: readers, an off-frame sort, and a pass that composes into the scene
`@driftengine/terrain`	Heightfields: a query that answers the surface that is drawn, and patches that meet without cracks
`@driftengine/texture`	DriftTexture: a texture as a compiled, sampled field rather than an image
`@driftengine/tools`	The editor panels a shipped game can carry, and the command stack that makes their edits undoable
`@driftengine/ui2d`	The 2D layer: batched sprites, sheets, tilemaps, and a retained interface tree over them
`@driftengine/xr`	WebXR sessions, stereo views, controller input and hand joints, over both backends

The shape of the API

The engine takes positions, colours, sizes and time, and it doesn't know what your game is. You won't find a player class to subclass or a level format to adopt: the rules, the world and the HUD are yours. That makes the first program a little longer than in an engine that decides those things for you, and it means you can replace any one piece when you outgrow it.

Three rules run through every page of this manual, and the examples follow all of them.

Import only from a package's top level. @driftengine/core is the public surface. Anything you can't import from there is internal and can change without notice.
Don't allocate in the frame. Build meshes, nodes and buffers once, and rewrite them in place.
Interpolate on alpha. The simulation advances in fixed steps and the display doesn't, so anything that moves is drawn between its last two states.

Where to start

Read Installation, then Hello world, which puts a lit, turning cube on the screen in about a hundred lines. The loop and Moving things explain the two ideas every game here is built on, and Your first game puts them together into a complete game you can play in this page.

This page's source, on GitHub