Physics - Main Thread Physics Engine Interface

High-level API for initializing and controlling the physics engine from the main thread. Manages SharedArrayBuffer creation, worker lifecycle, and provides convenient accessors for physics state.

Architecture

The Physics acts as a facade between the main thread and the physics worker:

SharedArrayBuffer Communication

All physics state is synchronized via typed arrays backed by SharedArrayBuffer. Use Buffer-Backed Objects (BBO) for property-like access:

// Read player position (lock-free, no RPC)
const player = physics.getView('dynamic')[0];
mesh.position.set(player.positionx, player.positiony, player.positionz);

// Read camera state
const cam = physics.cameraState;
camera.position.set(cam.positionx, cam.positiony, cam.positionz);

Basic Usage

import { Physics } from '@three-blocks/pro';
import * as THREE from 'three/webgpu';

const physics = new Physics({ gravity: -9.81, debug: false });
await physics.init();

// Add bodies via worker API
await physics.workerApi.addDynamicBody(mesh, options);
await physics.workerApi.addStaticBody(mesh, options);

// Start simulation
await physics.start();

// Game loop - read state directly from SharedArrayBuffer
function animate() {
  const player = physics.getView('dynamic')[0];
  playerMesh.position.set(player.positionx, player.positiony, player.positionz);

  renderer.render(scene, camera);
}

Events

// Listen for collision events
physics.on('static_collide_0', (data) => {
  console.log('Player collided with static body');
});

// Listen for zone triggers
physics.on('enter_zone_5', (data) => {
  console.log('Player entered zone 5');
});
physics.on('leave_zone_5', (data) => {
  console.log('Player left zone 5');
});