physics-system

Physics System

When to Use

Use this skill when:

• Implementing realistic physics simulation
• Adding gravity and forces
• Handling rigid body dynamics
• Integrating physics engines (Cannon.js, Rapier)
• Creating vehicle physics
• Building destruction systems

Core Principles

1. Fixed Timestep: Physics updates at constant rate
2. Separation of Concerns: Physics separate from rendering
3. Integration Ready: Support external physics engines
4. Deterministic: Same input produces same output
5. Performance-Aware: Optimize for many bodies
6. Sleeping Bodies: Don't update static objects

Physics System Implementation

1. Basic Physics Components

// components/RigidBody.ts
import { Vector3 } from 'three';

export enum BodyType {
  Static = 'static',
  Dynamic = 'dynamic',
  Kinematic = 'kinematic',
}

export class RigidBody {
  type: BodyType = BodyType.Dynamic;
  mass: number = 1;
  velocity = new Vector3();
  angularVelocity = new Vector3();
  force = new Vector3();
  torque = new Vector3();

  // Material properties
  restitution: number = 0.3; // Bounciness (0-1)
  friction: number = 0.5; // Friction (0-1)
  linearDamping: number = 0.01; // Air resistance
  angularDamping: number = 0.01; // Rotational resistance

  // Constraints
  lockPositionX: boolean = false;
  lockPositionY: boolean = false;
  lockPositionZ: boolean = false;
  lockRotationX: boolean = false;
  lockRotationY: boolean = false;
  lockRotationZ: boolean = false;

  // Sleep state (optimization)
  isSleeping: boolean = false;
  sleepThreshold: number = 0.01;

  constructor(mass: number = 1, type: BodyType = BodyType.Dynamic) {
    this.mass = mass;
    this.type = type;
  }

  applyForce(force: Vector3, point?: Vector3): void {
    if (this.type !== BodyType.Dynamic) return;

    this.force.add(force);

    if (point) {
      // Apply torque if force applied at offset point
      // torque = point × force
      const torque = new Vector3().crossVectors(point, force);
      this.torque.add(torque);
    }
  }

  applyImpulse(impulse: Vector3): void {
    if (this.type !== BodyType.Dynamic) return;

    // Impulse = instant change in velocity
    this.velocity.add(impulse.clone().divideScalar(this.mass));
  }

  clearForces(): void {
    this.force.set(0, 0, 0);
    this.torque.set(0, 0, 0);
  }

  shouldSleep(): boolean {
    const speed = this.velocity.length() + this.angularVelocity.length();
    return speed < this.sleepThreshold;
  }
}

// components/Collider.ts
export enum ColliderShape {
  Box = 'box',
  Sphere = 'sphere',
  Capsule = 'capsule',
  Cylinder = 'cylinder',
  Mesh = 'mesh',
}

export class Collider {
  shape: ColliderShape = ColliderShape.Box;
  size = new Vector3(1, 1, 1); // Box dimensions or sphere radius
  offset = new Vector3(); // Offset from transform
  isTrigger: boolean = false; // Trigger vs solid collision
  layer: number = 0; // Collision layer
  mask: number = 0xffffffff; // Which layers to collide with

  constructor(shape: ColliderShape = ColliderShape.Box, size?: Vector3) {
    this.shape = shape;
    if (size) this.size.copy(size);
  }
}