Taos API Reference
    Preparing search index...

    Module physics

    The Jolt WASM rigid-body backend: PhysicsWorld body factories (box/sphere/mesh/heightfield/convex-hull), constraints, raycasts, the PhysicsScene GameObject coupling layer, and the per-frame step/sync loop.

    All physics goes through this module — never jolt-physics directly. The Jolt WASM backend is loaded lazily on first use (see initializePhysics / PhysicsWorld.create), in its own chunk, so apps that don't import this module ship none of it. It is intentionally NOT re-exported from the engine's top-level barrel; consumers opt in via the taos/physics subpath, which keeps Jolt out of every physics-free bundle.

    Classes - Components

    RigidBody

    A rigid body. shape + its dimensions pick the collider; motion selects static / dynamic / kinematic. A dynamic body is simulated and writes its pose back onto the GameObject each frame.

    CharacterBody

    A kinematic capsule character. Set velocity (x/z) from a script or circuit each frame; gravity drives y. Calls move-and-slide and writes the resolved position back onto the GameObject.

    TriggerVolume

    A box sensor volume: fires onEnter/onExit as bodies overlap it and tracks how many currently do (isOccupied). Assign the callbacks from a script/circuit. Static (stays at its authored transform).

    Classes - Other

    CharacterController
    PhysicsScene
    PhysicsSystem
    PhysicsWorld

    Interfaces

    CharacterOptions
    PhysicsInitOptions

    Options for locating the Jolt .wasm when initializing physics. Omit entirely when building with Vite — the default path uses Vite's ?url asset handling to emit, hash, and fetch the .wasm automatically. Supply one of these only for non-Vite bundlers (webpack/rollup/esbuild/…) or to self-host the file (CDN, custom public path), since the ?url import is a Vite-ism other bundlers don't understand.

    SpawnOptions

    Options accepted by the spawn helpers: physics tuning + visual styling.

    SensorCallbacks

    Callbacks for a sensor (trigger) body's overlap events.

    BodyOptions

    Per-body tuning shared by every shape factory.

    Type Aliases

    GroundState

    Coarse ground classification, mirroring Jolt's EGroundState.

    RigidBodyShape

    Shape of a RigidBody.

    BodyMotion

    How a body participates in the simulation.

    Variables

    CollisionLayer

    Named collision layers as bit flags (Godot-style). A body's layer says which layer(s) it belongs to; its mask says which layers it collides with. Two bodies interact only when each one's layer appears in the other's mask (an AND of both directions, matching Jolt's ObjectLayerPairFilterMask). Give "passively collidable" bodies (static world, the player capsule) mask: All and put the selective filtering on the active body (e.g. a bullet that should hit only World | Enemy).

    LAYER_NON_MOVING

    Back-compat alias for the static-geometry layer (was object layer 0).

    LAYER_MOVING

    Back-compat alias for the default dynamic layer (was object layer 1).

    Functions

    initializePhysics

    Loads the Jolt physics backend (the WASM module) on demand. Call once before using physics, or simply await PhysicsWorld.create() which loads it for you. Idempotent — safe to call repeatedly / concurrently.

    isPhysicsInitialized

    True once the physics backend has finished loading.

    registerPhysicsComponents

    Register the physics component factories (idempotent; called on module import).

    getPhysicsSystem

    The physics system for an engine, created (and Jolt init kicked off) on first use.

    peekPhysicsSystem

    The physics system for an engine if one exists, without creating it (no Jolt spin-up).

    setPhysicsPaused

    Set the pause state for an engine's physics. Records the desired state even before the system exists (so a later-attached body starts correctly gated) and applies it to a live system. Used by the editor to freeze the sim in edit mode.