Colossum Physics

Colossum Physics is a browser-first rigid-body runtime built on pinned Box3D WebAssembly. It combines batched body and shape creation, reusable convex hulls, height fields, deterministic fixed-step simulation, SIMD and pthread variants, and one packed WebGPU pose upload per simulation generation.

Install

npm install @colossum/physics
npx colossum-physics-assets public/colossum-physics

The asset command copies the verified Emscripten modules, WebAssembly binaries, and manifest into the same-origin public directory expected by the runtime. Commit those assets or run the command as part of your application's build.

Quick start

import { createPhysicsRuntime } from "@colossum/physics";

const runtime = await createPhysicsRuntime({
  // Defaults to /colossum-physics/manifest.json after copying the assets.
  variant: "auto",
});

const world = runtime.createWorld({
  capacity: 2_001,
  visualCapacity: 2_001,
  gravity: [0, -9.81, 0],
});

const [body] = world.createBodies({
  bodies: [{
    motionType: "dynamic",
    position: [0, 4, 0],
    shape: { kind: "box", halfExtents: [0.5, 0.5, 0.5] },
    density: 1,
  }],
});

world.step(1 / 60, { substeps: 4 });
const render = world.syncPosesForFrame(device);

// Bind render.posePrevious, render.poseCurrent, and render.visualToBody.

world.destroyBody(body);
world.destroy();
runtime.destroy();

The browser never queries transforms one body at a time. A normal simulation frame performs one world step, one packed-pose operation, and at most one contiguous GPUQueue.writeBuffer call. Render-only frames reuse the GPU-resident previous/current pose buffers.

Runtime assets and pthread requirements

The threaded variants create Web Workers and shared WebAssembly memory. Serve the application page and the copied /colossum-physics/ directory from the same origin. The application response must include:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

Without cross-origin isolation, automatic selection falls back to the single-thread SIMD artifact. The package contains these verified fixed-memory variants:

• SIMD, single thread;
• SIMD + pthreads, four total Box3D workers;
• SIMD + pthreads, eight total Box3D workers as an explicit scaling option.

Pthread artifacts use one preallocated worker pool and allow one live world at a time. Destroy the world before creating its replacement. The single-thread runtime supports multiple live worlds up to the configured limit.

Public API

The public surface includes:

• createPhysicsRuntime and deterministic variant selection;
• fixed-capacity PhysicsWorld lifecycle;
• batched boxes, spheres, capsules, cylinders, and reusable convex hulls;
• height-field terrain;
• generation-safe body and hull handles;
• fixed-step simulation and packed WebGPU pose synchronization;
• typed diagnostics and failures.

See the API field manual and the live capability playground.

Browser support

Colossum Physics requires WebAssembly SIMD. The packed pose bridge additionally requires WebGPU. Pthread selection requires SharedArrayBuffer, cross-origin isolation, and enough logical processors for the selected worker count.

License

Colossum Physics is available under the MIT License. Box3D and toolchain notices are included in THIRD_PARTY_NOTICES.md.