Three.js Blocks

Home
Documentation
Examples
Tools

Body

@three-blocks/proPhysicsBodyWebGPUWebGL
new Body(views : Object, type : string, index : number, entity : THREE.Object3D|null, physics : Object|null)

Body - Physics body wrapper with Three.js-like interface

Provides position and quaternion properties that behave like THREE.Vector3 and THREE.Quaternion, but read/write to SharedArrayBuffer for lock-free physics synchronization. Automatically attached to API objects returned by physics.addBody() and physics.addBodies().

Position Methods

Quaternion Methods

api.body.quaternion.set(x, y, z, w)       // Set absolute rotation
api.body.quaternion.copy(quaternion)      // Copy from Quaternion
api.body.quaternion.identity()            // Reset to no rotation
api.body.quaternion.setFromEuler(euler)   // Set from Euler angles
api.body.quaternion.setFromAxisAngle(axis, angle)  // Set from axis-angle
api.body.quaternion.toQuaternion()        // Get as THREE.Quaternion
Constructor Parameters
viewsObject
Physics views object containing type-indexed body arrays.
typestring
Body type: 'dynamic', 'kinematic', 'static', 'zone'.
indexnumber
Body index in the views array.
entityoptionalTHREE.Object3D | null
Optional entity to sync transforms to.
Default is null.
physicsoptionalObject | null
Physics instance for event registration.
Default is null.
Example
api.body.position.set(x, y, z)      // Set absolute position
api.body.position.x = 10            // Set individual component
api.body.position.copy(vector3)     // Copy from Vector3
api.body.position.add(dx, dy, dz)   // Add to current position
api.body.position.addVector(v)      // Add Vector3 to position
api.body.position.toVector3()       // Get as THREE.Vector3

Properties

.isBody : boolean

Three.js-style type flag. Always true for Body instances.

.position : Object

Position interface with THREE.Vector3-like methods. Changes are written to SharedArrayBuffer and optionally synced to entity mesh.

.quaternion : Object

Quaternion interface with THREE.Quaternion-like methods. Changes are written to SharedArrayBuffer and optionally synced to entity mesh.

.index : number

The body index in the physics system.

.type : string

The body type ('dynamic', 'kinematic', 'static', 'zone').

.entity : THREE.Object3D|null

The associated Three.js entity (mesh/group).

.view : Object|null

Direct access to the raw BBO view for advanced usage.

.scale : THREE.Vector3

Scale used by sync() for mesh transforms. Set automatically from mesh matrixWorld or instance matrix during body creation.

.angularVelocity : Object

Angular velocity in radians per second (local space). Only used when enableRotationResponse is true.

.velocity : Object

Linear velocity in units per second (world space). Use this to give bodies an initial velocity or modify velocity during gameplay.

.angularDamping : number

Angular damping factor (0 = no damping, 1 = instant stop). Applied each physics step when enableRotationResponse is true. Default: 0.1

.enableRotationResponse : boolean

Enable rotation response during collisions. When disabled (default), only position is affected by collisions. When enabled, collisions apply angular impulses causing objects to spin and roll.

.enableCCD : boolean

Continuous Collision Detection (CCD) enabled. When enabled, uses speculative contacts to prevent fast-moving bodies from tunneling through geometry. Useful for character controllers at high speeds.
Default is false.

.momentOfInertia : number

Moment of inertia (scalar approximation). Auto-calculated from mass and collision shape during body creation. Can be overridden for custom physics behavior.

Methods

addEventListener#

addEventListener(type : string, listener : function)

Add an event listener for a body event. Automatically registers the event with the physics worker on first listener.

Parameters
typestring
Event type (use BodyEvent constants)
listenerfunction
Callback function

hasEventListener#

hasEventListener(type : string, listener : function) : boolean

Check if an event listener exists for a body event.

Parameters
typestring
Event type
listenerfunction
Callback function
Returns
boolean — True if listener exists

removeEventListener#

removeEventListener(type : string, listener : function)

Remove an event listener for a body event. Automatically unregisters from the physics worker when no listeners remain.

Parameters
typestring
Event type
listenerfunction
Callback function to remove

dispatchEvent#

dispatchEvent(event : Object)

Dispatch an event to all registered listeners.

Parameters
eventObject
Event object with type property

sync#

sync(alpha : number) : Body

Synchronize physics state to the entity mesh with interpolation.

Applies position, quaternion, and scale to the mesh. For BatchedMesh/InstancedMesh, updates the instance matrix. For regular meshes, sets position/quaternion/scale properties directly.

Scale is stored on body creation (from instance matrix for BatchedMesh) and can be changed via body.scale.set(x, y, z).

Parameters
alphaoptionalnumber
Interpolation factor (0-1). Use controller.getInterpolationAlpha().
Default is 1.
Returns
Body — Returns this for chaining.

dispose#

dispose()

Dispose of the body, cleaning up all event listeners. Called automatically by Physics.removeBody().

Example

// Moving a kinematic platform
const api = await physics.addBody(BodyType.KINEMATIC, platformMesh);

function animate() {
  const time = performance.now() * 0.001;
  api.body.position.set(
    Math.sin(time) * 5,
    2,
    Math.cos(time) * 5
  );
  api.body.quaternion.setFromAxisAngle({ x: 0, y: 1, z: 0 }, time);
}