Physics

The 2D physics world the running scene's document built, or null if it has none.

The seam between authored data and authored behaviour, and the 2D twin of the 3D adapter's accessor of the same name. A collider is data: the document declares it and this provider simulates it, no code on either side. Steering is not: a script attached to a box has no way to name the world the scene root declared, because that world never passed through the document. Without this the only reachable world is one the script opens itself, which is a second world with its own gravity and its own bodies, colliding with nothing in the scene.

Pair it with world.bodyOf(box) to reach the box's own collider: the document built the body, so the handle addRect returned went to this provider and never to the game.

null is the ordinary answer, not an error, and scripts must handle it: the editor's edit viewport deserializes the same document with no provider registered (see play.ts), so a script runs there with no world and must simply do nothing. That is what keeps the workspace from simulating while you author in it.

registerScript('walker', (self) => {
    const world = getPhysicsWorld2d();
    if (!world) return;                          // editing, not playing
    useUpdate(() => {
        // Looked up per frame: the body is registered as the box is built, so at init it may
        // not exist yet.
        world.bodyOf(self)?.setLinearVelocity(120, 0);
    });
});

Call it during scene init, which is when a script runs, so this is the ordinary case. Outside init there is no active game to compare against and the answer is always null.

Installs this as what simulates the flat half of a scene's physics. The one line a game writes, and the only one: everything else about physics is the engine's vocabulary, so a scene says what it is made of and this makes it move.

It is a call and not something that happens on import, for three separate reasons, any one of which would be enough. The engine declares itself free of side effects, so a bundler is allowed to drop an import nothing is used from, and a game that worked in development would sit still once built. A tool must be able to open a scene and NOT simulate it, which is what lets you build a level in a workspace that holds still. And a game may install the solid half as well, which it does the same way, by saying so.

import { installPhysics2d } from 'nacatamalon/physics2d';

installPhysics2d();

Installing twice does nothing the second time.

Load and initialize the Rapier2D WebAssembly module.

Memoizes the promise globally, so multiple calls return the same promise. The WASM is loaded once per page, shared across all scenes and worlds.

-compat and not the plain package, and this is a portability decision rather than a preference. @dimforge/rapier2d reaches its WebAssembly through an ESM import of the .wasm file itself (import * as wasm from './rapier_wasm2d_bg.wasm'), which only works under a bundler that implements WASM-ESM integration. Vite does, with vite-plugin-wasm, and that is why this worked for as long as the editor was the only thing that ran it. An exported build is bundled by something else, and there the import yields a namespace with no functions on it: the failure is rawintegrationparameters_new is not a function, thrown from generated glue, at which point nothing points back at how the module was loaded.

-compat is the same bindings with the WebAssembly carried inline and instantiated by an explicit init(). It costs a larger JavaScript payload and buys one loading path that holds under every bundler (including whatever a desktop shell uses), which matters more, because the alternative is physics that works in the editor and is inert in the shipped game.

The await this adds is free: every caller already went through this promise.

Moves the physics a scene declares, using Rapier2D.

This is the adapter's half of the split: the engine keeps colliders, writes them down and reads them back while deliberately being unable to move them, and registering this is what makes a scene actually fall. Nothing here is needed to author physics: a tool opens, edits and saves a scene with none of it installed.

It is handed everything a scene declares, whether that came from a file or from a line somebody typed, because the engine records it and then asks. There is nothing here that only one of those two paths goes through.

import { registerPhysicsProvider } from 'nacatamalon/extend';
import { rapier2dProvider } from 'nacatamalon/physics2d';

registerPhysicsProvider(rapier2dProvider);

The non-geometric properties of a collider: how it responds to a contact, and whether it resolves the contact at all.

Handle to a physics body registered in the world.

The physics world interface returned by usePhysicsWorld.

World initialization options.

Type of the initialized Rapier2D module.

Moves the physics a scene declares in three dimensions, using box3d.

This is the adapter's half of the split: the engine keeps colliders, writes them down and reads them back while deliberately being unable to move them, and registering this is what makes a scene actually fall. Nothing here is needed to author physics: a tool opens, edits and saves a scene with none of it installed.

It is handed everything a scene declares, whether that came from a file or from a line somebody typed, because the engine records it and then asks. There is nothing here that only one of those two paths goes through.

import { registerPhysicsProvider } from 'nacatamalon/extend';
import { box3dProvider } from 'nacatamalon/physics3d';

registerPhysicsProvider(box3dProvider);

How far a ray reaches when nothing says otherwise.

Finite rather than infinite because the backend takes a translation vector, not a direction: there is no "infinity" to hand it. A kilometre is far beyond any level this engine's retro scope builds, so it reads as unlimited while staying a number the solver can use.

The 3D physics world the running scene built, or null if it has none.

The seam between authored data and authored behaviour, and the twin of the 2D adapter's accessor of the same name. A collider is data: the scene declares it and this provider simulates it, with no code on either side. Steering is not, and neither is a character, a ray or a trigger's answer, so this is the way back out.

Pair it with world.bodyOf(box) to reach an object's own collider: the engine built the body and handed it here, so the handle addBox returned never went to the game.

null is an ordinary answer, not an error, and scripts must handle it: a tool that opens a scene to edit it deserializes the same objects with no provider registered, so a script runs there with no world and must simply do nothing. That is what keeps a workspace from simulating while somebody is building in it.

registerScript('walker', (self) => {
    const world = getPhysicsWorld3d();
    if (!world) return;                          // editing, not playing
    useUpdate(() => {
        // Looked up per frame: the body is registered as the object is built, so at init it
        // may not exist yet.
        world.bodyOf(self)?.setLinearVelocity(0, 0, -4);
    });
});

Call it while the scene is being built, which is when a script runs, so this is the ordinary case. Outside that there is no active game to compare against and the answer is always null.

Installs this as what simulates the solid half of a scene's physics. The one line a game writes, and the only one: everything else about physics is the engine's vocabulary, so a scene says what it is made of and this makes it move.

It is a call and not something that happens on import, for three separate reasons, any one of which would be enough. The engine declares itself free of side effects, so a bundler is allowed to drop an import nothing is used from, and a game that worked in development would sit still once built. A tool must be able to open a scene and NOT simulate it, which is what lets you build a level in a workspace that holds still. And a game may install the flat half as well, which it does the same way, by saying so.

import { installPhysics3d } from 'nacatamalon/physics3d';

installPhysics3d();

Installing twice does nothing the second time.

Loads (once) the Box3D WASM runtime and memoizes the promise, so every world in a game shares a single instantiation instead of re-compiling the module per scene. Uses the inline build, so the .wasm is embedded in the bundle as base64, so it works in the browser with no Vite/loader config and in a headless Node/Bun test with no separate file to resolve. The trade is a slightly larger bundle, paid only by games that actually import the physics adapter.

Makes this object a walking character: a capsule moved by asking the world what is in the way, and the thing that makes a room walkable.

It is the one part of physics that a scene cannot write down, and that is not an oversight. A crate is a shape with a weight, and a file can say so. A character is a decision taken sixty times a second about where a body is allowed to be: it climbs a step without jumping, walks up a ramp and not up a wall, and stops dead against a crate instead of tipping over it. None of that is a property of the object, so there is nothing for a scene to keep, and steering one with forces gives you something that slides on slopes and falls over on its face.

Set velocity and it walks. Falling is applied for you, and isGrounded is the answer to whether it may jump.

null when the scene has no physics world, which is what a tool opening a scene to edit it looks like. Handle it the way you would handle getPhysicsWorld3d() coming back empty: do nothing, because nothing is running.

const Player = () => {
    useTransform({ x: 0, y: 1, z: 0 });
    createMesh({ geometry: useUvSphereGeometry({ radius: 0.35 }), tint: BLUE });

    const player = useCharacterBody({ radius: 0.35, height: 1.8 });
    const keys = useKeyboard();
    useUpdate(() => {
        if (!player) return;
        player.velocity.x = keys.isDown('d') ? 4 : keys.isDown('a') ? -4 : 0;
        if (keys.isDown('Space') && player.isGrounded) player.velocity.y = 5;
    });
};

The Box3D WebAssembly runtime, or null: the opaque handle every physics call goes through. Excluded from any serialization exactly like a GPU handle: it is pure runtime, reconstructed on load, never part of a save. Re-exported so the world wrapper can type body/world ids off it without importing Embind internals.

A kinematic character: the thing that separates "boxes that fall" from "somebody walks here".

A character is deliberately not a dynamic body. A dynamic capsule steered by forces fights its own momentum and friction: it slides on slopes, tips over, skates after you let go of the stick, and catches on the seam between two floor tiles. Every engine solves this the same way and so does this one: the character is a capsule moved by queries against the world (b3World_CollideMover + b3SolvePlanes, Box2D v3's mover primitives), resolved to a position that does not overlap anything, then written onto the box's transform.

Set TCharacterBody.velocity, and the world advances it on its own fixed step. Gravity is applied for you (set gravity: 0 for a flyer), because a controller that falls is what "character" means to nearly everyone asking for one.

Everything a character needs beyond its world: the capsule it occupies, how it treats slopes, and where that capsule sits inside its box.

height is the total height including the caps, the same convention Collider3D's capsule uses, so a 1.8 m person is { radius: 0.3, height: 1.8 }.

What every add* takes beyond its own dimensions: the surface, plus where the shape sits inside the object.

offset is in the box's local units before its scale, matching TPhysicsBody3d.offset, and it exists for glTF, which puts a model's origin at its feet while a collider is centred on that origin. Omitted means centred.

Optional surface tuning for a collider: how a contact resolves, and whether it resolves at all. restitution is bounciness (0 = dead, 1 = elastic), friction resists sliding, density (kg/m³) sets the body's mass from its volume, and sensor detects overlaps without resolving them, which is a trigger volume. All optional; omitted fields keep Box3D's defaults.

The grouping mirrors the engine's TPhysicsSurface, which puts the same four together for the same reason: they are the non-geometric half of a collider.

A runtime handle to one simulated body. Runtime only: the body lives in WASM memory, so nothing here is serializable (the serializable form is the mesh's own transform, which this body writes into).

The world a scene declared, and the factory for bodies in it. Deliberately narrow (box + sphere for now); more shapes and queries land when a concrete case needs them, not before.

Options for the world. gravity is metres/second² (the engine's 3D unit is one metre); it defaults to Earth on -Y.

What a ray found: which object, where, and how far along.

box is the very object handed to addBox/addSphere and the rest, so a hit is immediately usable ("move this", "damage that") without a lookup table of your own.

How far a ray reaches and what it is allowed to hit.

collidesWith is a layer bitmask read exactly like a body's own (see the engine's TPhysicsSurface) so a ground check that should ignore enemies, or a cursor pick that should ignore scenery, is the same vocabulary the colliders are already authored in rather than a second one.