Installation

Install the package

The controllers depend on jolt-ts (the physics wrapper) and three (used for its math types — Vector3, Quaternion). Install all three:

pnpm

pnpm add jolt-ts-character-controller jolt-ts three

npm

npm install jolt-ts-character-controller jolt-ts three

yarn

yarn add jolt-ts-character-controller jolt-ts three

If you use TypeScript, add the Three.js types as a dev dependency:

pnpm

pnpm add -D @types/three

npm

npm install -D @types/three

yarn

yarn add -D @types/three

ESM only

The package is published as ESM with bundled type declarations ("type": "module"). Import it with import syntax from an ESM project or a bundler such as Vite. There is no CommonJS require build.

Create a physics world

Everything in this library operates on a jolt-ts World. The simplest setup creates a world and lets it load the Jolt runtime for you:

import { World, Shape } from "jolt-ts";

const world = await World.create({ gravity: [0, -9.81, 0] });

// A static floor to stand on.
world.createBody({
  type: "static",
  shape: Shape.box({ halfExtents: [25, 0.5, 25] }),
  position: [0, -0.5, 0],
  layer: "static",
  friction: 0.8,
});

Deterministic worlds

For headless simulation, tests, or networked play where every peer must produce identical results, ask Jolt for cross-platform determinism:

const world = await World.create({
  gravity: [0, -9.81, 0],
  deterministic: "cross-platform",
});

See Network Sync for why this matters.

Controlling the WebAssembly runtime

World.create will load the Jolt WASM module on demand. In a browser bundle you may want to load it explicitly (for example to control the build variant or to pre-warm it), then hand the runtime to every world you create:

1. Load the runtime once at startup:

   import { loadJolt, World } from "jolt-ts";
   
   const runtime = await loadJolt({ build: "wasm" });

2. Pass it into each world:

   const world = await World.create({
     runtime,
     gravity: [0, -9.81, 0],
   });

Bundler asset handling

jolt-ts ships a .wasm asset. Bundlers like Vite serve it automatically, but for other setups you may need to make the WASM file available to the browser. Refer to the jolt-ts documentation for build-tool specifics — this library does not change how Jolt is loaded.

Next

You now have a world and a floor. Continue to the Quick Start to drop in a keyboard-controlled character.