Physics.core.ts

Physics — pure core.

A minimal rigid-body world used by adapters that don't have a dedicated physics engine (ThreeAdapter today, MockRendererAdapter in tests). Tracks a list of bodies by meshId, applies gravity each step, integrates forward with plain Euler, clamps bodies to a ground plane at y=0, and exposes each body's current position so the adapter can push it back to the 3D mesh.

No imports from @babylonjs, three, solid-js, or the DOM. Inputs and outputs are primitives or tuples. Same (params, inputs) ⇒ same outputs.

This is intentionally simpler than a real constraint solver: Babylon's adapter delegates to Havok, which handles collisions, friction/restitution materials, and contact manifolds. This core exists so Physics still ticks predictably under renderers without a native engine.

Physics.core.ts

export type PhysicsShapeType = 'sphere' | 'box' | 'capsule';
export type PhysicsMotionType = 'dynamic' | 'static' | 'kinematic';

export interface PhysicsBodyOpts {
  shapeType: PhysicsShapeType;
  motionType: PhysicsMotionType;
  mass: number;
  friction: number;
  restitution: number;
  lockRotation: boolean;
  /** Initial world position for the body. */
  posX?: number;
  posY?: number;
  posZ?: number;
}

export interface PhysicsWorldParams {
  /** Vertical gravity in world units / sec^2 (negative = pulls downward). */
  gravityY: number;
  /** Per-frame horizontal velocity damping. 1 = no damping. */
  linearDamping: number;
  /** When a body bottoms out at groundY, vertical velocity scales by this. */
  groundBounce: number;
  /** Plane height the body cannot fall below. Matches BouncyDemo (y=0). */
  groundY: number;
}

export const DEFAULT_PHYSICS_WORLD_PARAMS: PhysicsWorldParams = {
  gravityY: -30,
  linearDamping: 0.995,
  groundBounce: 0.35,
  groundY: 0,
};

export interface PhysicsBodyState {
  meshId: string;
  shapeType: PhysicsShapeType;
  motionType: PhysicsMotionType;
  mass: number;
  friction: number;
  restitution: number;
  lockRotation: boolean;
  posX: number;
  posY: number;
  posZ: number;
  velX: number;
  velY: number;
  velZ: number;
}

export interface PhysicsInstance {
  /** Register a new body in the simulation. */
  createBody(meshId: string, opts: PhysicsBodyOpts): PhysicsBodyState;
  /** Remove a body. No-op if unknown. */
  destroyBody(meshId: string): void;
  /** Read snapshot of a body. Returns `undefined` for unknown ids. */
  getBody(meshId: string): Readonly<PhysicsBodyState> | undefined;
  /** Replace the linear velocity of a body. */
  setBodyVelocity(meshId: string, vx: number, vy: number, vz: number): void;
  /** Replace the position of a body. */
  setBodyPosition(meshId: string, px: number, py: number, pz: number): void;
  /** Advance every body by `dt` seconds. */
  step(dt: number): void;
  /** Iterate all bodies in insertion order. */
  bodies(): ReadonlyArray<Readonly<PhysicsBodyState>>;
  setParams(partial: Partial<PhysicsWorldParams>): void;
  getParams(): Readonly<PhysicsWorldParams>;
  /** Clear all bodies; parameters are untouched. */
  reset(): void;
}

export function createPhysics(params: Partial<PhysicsWorldParams> = {}): PhysicsInstance {
  const active: PhysicsWorldParams = { ...DEFAULT_PHYSICS_WORLD_PARAMS, ...params };
  const bodyList: PhysicsBodyState[] = [];
  const bodyById = new Map<string, PhysicsBodyState>();

  const getBody = (meshId: string) => bodyById.get(meshId);

  return {
    createBody(meshId, opts) {
      // Replace if a body under this meshId already exists so callers don't
      // have to destroyBody first on re-creation (happens during hot-reload).
      const existing = bodyById.get(meshId);
      if (existing) {
        const idx = bodyList.indexOf(existing);
        if (idx >= 0) bodyList.splice(idx, 1);
        bodyById.delete(meshId);
      }
      const body: PhysicsBodyState = {
        meshId,
        shapeType: opts.shapeType,
        motionType: opts.motionType,
        mass: opts.mass,
        friction: opts.friction,
        restitution: opts.restitution,
        lockRotation: opts.lockRotation,
        posX: opts.posX ?? 0,
        posY: opts.posY ?? 0,
        posZ: opts.posZ ?? 0,
        velX: 0,
        velY: 0,
        velZ: 0,
      };
      bodyList.push(body);
      bodyById.set(meshId, body);
      return body;
    },

    destroyBody(meshId) {
      const body = bodyById.get(meshId);
      if (!body) return;
      const idx = bodyList.indexOf(body);
      if (idx >= 0) bodyList.splice(idx, 1);
      bodyById.delete(meshId);
    },

    getBody,

    setBodyVelocity(meshId, vx, vy, vz) {
      const body = bodyById.get(meshId);
      if (!body) return;
      body.velX = vx;
      body.velY = vy;
      body.velZ = vz;
    },

    setBodyPosition(meshId, px, py, pz) {
      const body = bodyById.get(meshId);
      if (!body) return;
      body.posX = px;
      body.posY = py;
      body.posZ = pz;
    },

    step(dt) {
      // Clamp dt so a stutter can't throw bodies off the map.
      const clampedDt = Math.max(0, Math.min(dt, 0.1));
      for (let i = 0; i < bodyList.length; i++) {
        const b = bodyList[i];
        if (b.motionType === 'static') continue;

        // Kinematic bodies ignore gravity — caller drives them via setBodyVelocity / setBodyPosition.
        if (b.motionType !== 'kinematic') {
          b.velY += active.gravityY * clampedDt;
        }

        // Integrate.
        b.posX += b.velX * clampedDt;
        b.posY += b.velY * clampedDt;
        b.posZ += b.velZ * clampedDt;

        // Horizontal damping. Matches how Havok's `linearDamping` attenuates motion per step.
        b.velX *= active.linearDamping;
        b.velZ *= active.linearDamping;

        // Ground plane: reflect vertical velocity by restitution * groundBounce.
        if (b.posY < active.groundY) {
          b.posY = active.groundY;
          b.velY = Math.abs(b.velY) * b.restitution * active.groundBounce;
          // Apply friction on the ground tick to bleed off sliding speed.
          b.velX *= 1 - b.friction;
          b.velZ *= 1 - b.friction;
          // Snap tiny residual bounces to rest so bodies actually settle.
          if (b.velY < 0.01) b.velY = 0;
        }
      }
    },

    bodies() {
      return bodyList;
    },

    setParams(partial) {
      Object.assign(active, partial);
    },

    getParams() {
      return active;
    },

    reset() {
      bodyList.length = 0;
      bodyById.clear();
    },
  };
}

Physics.defs.ts

Physics — definitions.

Holds the PhysicsComponent class, its event dictionary and the shapes its data and events travel in. No System lives here, which is the point: another component can name Physics in a query, or type an event it listens for, without pulling Physics's behaviour into its own bundle. Import from here, not from Physics.ts.

Physics.defs.ts

import { Component } from '@babylonjsmarket/ecs';
import type { PhysicsBodyOpts } from '@babylonjsmarket/ecs/renderer-types';

Events

Physics.defs.ts

export const PhysicsEvents = {
  /** Emitted once the adapter has successfully created a rigid body for the entity. */
  BODY_CREATED: 'physics.body.created',
  /** Emitted when an entity's rigid body has been disposed. */
  BODY_DISPOSED: 'physics.body.disposed',
} as const;

export const PhysicsInputEvents = {
  /** Directly set a body's linear velocity. Payload: { entityId, vx, vy, vz }. */
  SET_VELOCITY: 'physics.setVelocity',
  /** Pause all physics stepping. Payload: {}. */
  PAUSE: 'physics.pause',
  /** Resume physics stepping. Payload: {}. */
  RESUME: 'physics.resume',
  /**
   * Reconfigure the engine's fixed simulation rate. Payload: { hz }. Higher
   * Hz = smaller substep → fewer tunneling artifacts at the cost of CPU.
   * Adapters without a configurable rate (Three/Mock) no-op.
   */
  SET_TIME_STEP: 'physics.setTimeStep',
  /** Set the world gravity vector. Payload: { x, y, z }. */
  SET_GRAVITY: 'physics.setGravity',
  /** Set a body's restitution (bounciness). Payload: { entityId, restitution }. */
  SET_RESTITUTION: 'physics.setRestitution',
  /** Toggle wireframe outlines of every collider. Payload: { visible }. */
  SET_COLLIDERS_VISIBLE: 'physics.setCollidersVisible',
} as const;

export interface PhysicsSetVelocityEvent {
  entityId: string;
  vx: number;
  vy: number;
  vz: number;
}

export interface PhysicsSetTimeStepEvent {
  hz: number;
}

export interface PhysicsSetGravityEvent {
  x: number;
  y: number;
  z: number;
}

export interface PhysicsSetRestitutionEvent {
  entityId: string;
  restitution: number;
}

export interface PhysicsSetCollidersVisibleEvent {
  visible: boolean;
}

Component

Physics.defs.ts

export type PhysicsShapeTypeName = 'sphere' | 'box' | 'capsule';

export type PhysicsMotionTypeName = 'dynamic' | 'static' | 'kinematic';

export interface PhysicsInput {
  shapeType?: PhysicsShapeTypeName;
  motionType?: PhysicsMotionTypeName;
  mass?: number;
  friction?: number;
  restitution?: number;
  lockRotation?: boolean;
  /**
   * When true (default), the System calls `physicsCreateBody` automatically
   * once the sibling MeshPrimitive's handle is ready. Set false to hand-drive
   * body creation (e.g., respawn flows that want to re-pose the mesh first).
   */
  autoCreate?: boolean;
  /**
   * Engine fixed simulation rate in Hertz. Applied once at system init via
   * `physicsSetTimeStep` and updateable live via the SET_TIME_STEP event
   * (e.g. the Physics debugger panel slider). The Hz lives on the component
   * so a scene-author can pin a higher rate per-game (pinball wants ~240).
   * Only one PhysicsComponent's `simulationHz` is consulted — the first one
   * encountered. Default 60.
   */
  simulationHz?: number;
}

export class PhysicsComponent extends Component {
  shapeType: PhysicsShapeTypeName;
  motionType: PhysicsMotionTypeName;
  mass: number;
  friction: number;
  restitution: number;
  lockRotation: boolean;
  autoCreate: boolean;
  simulationHz: number;

  /** Populated by the System once `physicsCreateBody` has run for this entity. */
  isCreated = false;

  constructor(data: PhysicsInput = {}) {
    super();
    this.shapeType = data.shapeType ?? 'sphere';
    // Mirror legacy default: a zero-mass body should be static even if the
    // caller omits `motionType`.
    this.motionType = data.motionType ?? (data.mass === 0 ? 'static' : 'dynamic');
    this.mass = data.mass ?? 1;
    this.friction = data.friction ?? 0.5;
    this.restitution = data.restitution ?? 0.5;
    this.lockRotation = data.lockRotation ?? false;
    this.autoCreate = data.autoCreate ?? true;
    this.simulationHz = data.simulationHz ?? 60;
  }

  toBodyOpts(): PhysicsBodyOpts {
    return {
      shapeType: this.shapeType,
      motionType: this.motionType,
      mass: this.mass,
      friction: this.friction,
      restitution: this.restitution,
      lockRotation: this.lockRotation,
    };
  }

  serialize(): PhysicsInput {
    return {
      shapeType: this.shapeType,
      motionType: this.motionType,
      mass: this.mass,
      friction: this.friction,
      restitution: this.restitution,
      lockRotation: this.lockRotation,
      autoCreate: this.autoCreate,
      simulationHz: this.simulationHz,
    };
  }
}

Physics.ts

Physics.ts — renderer-agnostic System.

Physics state orchestration lives in Physics.core.ts. This System is a thin driver: it watches for entities with MeshPrimitive + PhysicsComponent, asks the adapter to create a rigid body (world.renderer.physicsCreateBody), forwards pause/resume events, and steps physics each frame via the adapter (world.renderer.physicsStep). Under Babylon the adapter delegates to Havok; under Three (or the mock) the adapter uses the pure-core integrator. Zero @babylonjs / three imports — those live in the adapters.

Physics.ts

import { System } from '@babylonjsmarket/ecs';
import type { EventBus } from '@babylonjsmarket/ecs';
import type { Entity } from '@babylonjsmarket/ecs';
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.defs';
import { PhysicsComponent, PhysicsEvents, PhysicsInputEvents, type PhysicsSetCollidersVisibleEvent, type PhysicsSetGravityEvent, type PhysicsSetRestitutionEvent, type PhysicsSetTimeStepEvent, type PhysicsSetVelocityEvent } from './Physics.defs';

System

Physics.ts

export class PhysicsSystem extends System {
  /** Entities whose body has been requested — prevents duplicate creates. */
  private created = new Set<string>();
  private isPaused = false;
  /** Initial Hz applied once during init from the first PhysicsComponent. */
  private timeStepApplied = false;
  protected query = { required: [PhysicsComponent] };

  constructor(eventBus: EventBus) {
    super(eventBus);
  }

  protected onInitialize(): void {
    this.listen(PhysicsInputEvents.SET_VELOCITY, (e: PhysicsSetVelocityEvent) => {
      this.handleSetVelocity(e);
    });
    this.listen(PhysicsInputEvents.PAUSE, () => {
      this.isPaused = true;
    });
    this.listen(PhysicsInputEvents.RESUME, () => {
      this.isPaused = false;
    });
    this.listen(PhysicsInputEvents.SET_TIME_STEP, (e: PhysicsSetTimeStepEvent) => {
      this.handleSetTimeStep(e);
    });
    this.listen(PhysicsInputEvents.SET_GRAVITY, (e: PhysicsSetGravityEvent) => {
      this.world?.renderer?.physicsSetGravity(e.x, e.y, e.z);
    });
    this.listen(PhysicsInputEvents.SET_RESTITUTION, (e: PhysicsSetRestitutionEvent) => {
      const comp = this.world?.getEntity(e.entityId)?.get(PhysicsComponent);
      if (comp) comp.restitution = e.restitution; // mirror for serialize
      this.world?.renderer?.physicsSetRestitution(e.entityId, e.restitution);
    });
    this.listen(PhysicsInputEvents.SET_COLLIDERS_VISIBLE, (e: PhysicsSetCollidersVisibleEvent) => {
      this.world?.renderer?.setCollidersVisible(e.visible);
    });

    // Try to attach any entities that already exist when the system initializes.
    for (const entity of this.entities) this.tryCreateBody(entity);
    this.applyInitialTimeStep();
  }

  protected onShutdown(): void {
    const r = this.world?.renderer;
    if (r) {
      for (const id of this.created) r.physicsDestroyBody(id);
    }
    this.created.clear();
  }

  protected onEntityAdded(entity: Entity): void {
    this.tryCreateBody(entity);
  }

  protected onEntityRemoved(entity: Entity): void {
    if (!this.created.has(entity.id)) return;
    const r = this.world?.renderer;
    r?.physicsDestroyBody(entity.id);
    this.created.delete(entity.id);
    const comp = entity.get(PhysicsComponent);
    if (comp) comp.isCreated = false;
    this.eventBus.emit(PhysicsEvents.BODY_DISPOSED, { entityId: entity.id });
  }

  protected onUpdate(dt: number): void {
    // New bodies are deferred until the sibling MeshPrimitive's handle lands;
    // re-check every tick is cheap (entities is a filtered query list).
    for (const entity of this.entities) {
      if (!this.created.has(entity.id)) this.tryCreateBody(entity);
    }
    if (!this.timeStepApplied) this.applyInitialTimeStep();
    if (this.isPaused) return;
    this.world?.renderer?.physicsStep(dt);
  }

  private tryCreateBody(entity: Entity): void {
    if (this.created.has(entity.id)) return;
    const comp = entity.get(PhysicsComponent);
    if (!comp || !comp.autoCreate) return;
    const mesh = entity.get(MeshPrimitiveComponent);
    if (!mesh?.handle) return; // mesh not ready yet

    const r = this.world?.renderer;
    if (!r) return;
    r.physicsCreateBody(entity.id, comp.toBodyOpts());
    comp.isCreated = true;
    this.created.add(entity.id);
    this.eventBus.emit(PhysicsEvents.BODY_CREATED, {
      entityId: entity.id,
      shapeType: comp.shapeType,
      motionType: comp.motionType,
      mass: comp.mass,
    });
  }

  private handleSetVelocity(e: PhysicsSetVelocityEvent): void {
    if (!this.created.has(e.entityId)) return;
    this.world?.renderer?.physicsSetBodyVelocity(e.entityId, e.vx, e.vy, e.vz);
  }

  private handleSetTimeStep(e: PhysicsSetTimeStepEvent): void {
    if (!Number.isFinite(e.hz) || e.hz <= 0) return;
    // Mirror into the first PhysicsComponent so reloads / serialize() pick
    // up the live value, then apply to the engine.
    for (const entity of this.entities) {
      const comp = entity.get(PhysicsComponent);
      if (comp) {
        comp.simulationHz = e.hz;
        break;
      }
    }
    this.world?.renderer?.physicsSetTimeStep(e.hz);
  }

  private applyInitialTimeStep(): void {
    if (this.timeStepApplied) return;
    for (const entity of this.entities) {
      const comp = entity.get(PhysicsComponent);
      if (!comp) continue;
      this.world?.renderer?.physicsSetTimeStep(comp.simulationHz);
      this.timeStepApplied = true;
      return;
    }
  }
}

The definitions live in Physics.defs.ts; re-exported so existing importers keep working. New code should import them from './Physics.defs' directly.

Physics.ts

export { PhysicsComponent, PhysicsEvents, type PhysicsInput, PhysicsInputEvents, type PhysicsMotionTypeName, type PhysicsSetCollidersVisibleEvent, type PhysicsSetGravityEvent, type PhysicsSetRestitutionEvent, type PhysicsSetTimeStepEvent, type PhysicsSetVelocityEvent, type PhysicsShapeTypeName } from './Physics.defs';

Physics.contract.test.ts

13 ✓

ArcadeECS contract: Physics

Component() with no args constructs and applies defaults
Component merges sample input on top of defaults
Component.serialize() round-trips into a constructor input
System constructor signature is exactly (eventBus)
System declares a non-empty query.required
world.addSystem + initialize + update runs clean with no entity
adding the Component attaches the entity to the System
world.update(dt) does not throw with the entity attached
Adapter handles: create/dispose balance across entity lifecycle
EventBus has no lingering listeners after world.destroy()
Declared event names follow the "{domain}.{action}" convention
Emits at least one declared output event during an update
Registers a listener for each declared input event

Last run 2026-08-22

Physics.contract.test.ts

import { runMechanicContract } from '@babylonjsmarket/ecs/testing';
import type { MechanicContractContext } from '@babylonjsmarket/ecs/testing';
import {
  PhysicsComponent,
  PhysicsSystem,
  PhysicsEvents,
  PhysicsInputEvents,
} from './Physics';
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.defs';

/**
 * Physics needs a sibling MeshPrimitive with an adapter handle before the
 * system will call `physicsCreateBody` (the body is keyed by the mesh id).
 * We latch onto every new entity and attach a mesh + handle to it so the
 * contract battery's generic "add the Component" entity triggers body
 * creation under Mock renderer.
 */
let latestEntityId = 'physics-contract';

runMechanicContract({
  name: 'Physics',
  componentClass: PhysicsComponent,
  systemClass: PhysicsSystem,
  sampleInput: { shapeType: 'box', mass: 3 },
  events: {
    input: [
      PhysicsInputEvents.SET_VELOCITY,
      PhysicsInputEvents.PAUSE,
      PhysicsInputEvents.RESUME,
    ],
    output: [PhysicsEvents.BODY_CREATED, PhysicsEvents.BODY_DISPOSED],
  },
  setup(ctx: MechanicContractContext) {
    // Auto-attach a MeshPrimitive with a live handle to every entity created
    // during the battery so the Physics system has a mesh to key off.
    ctx.eventBus.on('world.entity.created', (e: { entity: { id: string; add(c: unknown): void; get(c: unknown): unknown } }) => {
      latestEntityId = e.entity.id;
      const mesh = new MeshPrimitiveComponent({ primitive: 'sphere' });
      mesh.handle = ctx.renderer.createMesh(e.entity.id, mesh.toPrimitiveSpec()) as ReturnType<
        typeof ctx.renderer.createMesh
      >;
      e.entity.add(mesh);
    });
  },
  makeInputPayload(event) {
    if (event === PhysicsInputEvents.SET_VELOCITY) {
      return { entityId: latestEntityId, vx: 0, vy: 1, vz: 0 };
    }
    return {};
  },
});

Physics.core.test.ts

12 ✓

Physics core

starts with no bodies and defaults exposed via getParams
createBody registers a body that getBody and bodies() can read
destroyBody removes the body and getBody returns undefined afterwards
applies gravity to dynamic bodies each step
static bodies do not fall under gravity
kinematic bodies do not receive gravity but still integrate via setBodyVelocity
bodies rest on the ground plane and bounce with restitution * groundBounce
horizontal damping attenuates velX/velZ each step
setParams updates world behavior on the next step
reset clears all bodies but leaves params intact
setBodyPosition writes the position of a known body and no-ops for unknown ids
createBody with a duplicate meshId replaces the existing body

Last run 2026-08-22

Physics.core.test.ts

import { describe, it, expect } from 'vitest';
import {
  createPhysics,
  DEFAULT_PHYSICS_WORLD_PARAMS,
} from './Physics.core';

describe('Physics core', () => {
  it('starts with no bodies and defaults exposed via getParams', () => {
    const sim = createPhysics();
    expect(sim.bodies().length).toBe(0);
    expect(sim.getParams()).toEqual(DEFAULT_PHYSICS_WORLD_PARAMS);
  });

  it('createBody registers a body that getBody and bodies() can read', () => {
    const sim = createPhysics();
    const body = sim.createBody('ball', {
      shapeType: 'sphere',
      motionType: 'dynamic',
      mass: 1,
      friction: 0.5,
      restitution: 0.5,
      lockRotation: false,
      posY: 10,
    });
    expect(body.posY).toBe(10);
    expect(sim.bodies().length).toBe(1);
    expect(sim.getBody('ball')?.shapeType).toBe('sphere');
  });

  it('destroyBody removes the body and getBody returns undefined afterwards', () => {
    const sim = createPhysics();
    sim.createBody('a', {
      shapeType: 'box', motionType: 'dynamic', mass: 1,
      friction: 0.2, restitution: 0.2, lockRotation: false,
    });
    sim.destroyBody('a');
    expect(sim.getBody('a')).toBeUndefined();
    expect(sim.bodies().length).toBe(0);
  });

  it('applies gravity to dynamic bodies each step', () => {
    const sim = createPhysics({ gravityY: -10, groundY: -100, linearDamping: 1 });
    sim.createBody('ball', {
      shapeType: 'sphere', motionType: 'dynamic', mass: 1,
      friction: 0, restitution: 0, lockRotation: false,
      posY: 50,
    });
    // dt is clamped to 0.1 internally so a stutter can't throw the world apart.
    sim.step(0.1);
    const body = sim.getBody('ball')!;
    expect(body.velY).toBeCloseTo(-1, 5);
    // velY was added at the start of step: 50 + (-1 * 0.1) = 49.9
    expect(body.posY).toBeCloseTo(49.9, 5);
  });

  it('static bodies do not fall under gravity', () => {
    const sim = createPhysics({ gravityY: -30, groundY: -100 });
    sim.createBody('floor', {
      shapeType: 'box', motionType: 'static', mass: 0,
      friction: 0.5, restitution: 0, lockRotation: false,
      posY: 0,
    });
    sim.step(0.1);
    expect(sim.getBody('floor')!.posY).toBe(0);
    expect(sim.getBody('floor')!.velY).toBe(0);
  });

  it('kinematic bodies do not receive gravity but still integrate via setBodyVelocity', () => {
    const sim = createPhysics({ gravityY: -30, groundY: -100, linearDamping: 1 });
    sim.createBody('kin', {
      shapeType: 'capsule', motionType: 'kinematic', mass: 1,
      friction: 0, restitution: 0, lockRotation: false,
    });
    sim.setBodyVelocity('kin', 3, 0, 0);
    sim.step(0.1);
    expect(sim.getBody('kin')!.velY).toBe(0);
    expect(sim.getBody('kin')!.posX).toBeCloseTo(0.3, 5);
  });

  it('bodies rest on the ground plane and bounce with restitution * groundBounce', () => {
    const sim = createPhysics({
      gravityY: 0, // isolate bounce response
      groundY: 0,
      groundBounce: 0.5,
      linearDamping: 1,
    });
    sim.createBody('ball', {
      shapeType: 'sphere', motionType: 'dynamic', mass: 1,
      friction: 0, restitution: 0.8, lockRotation: false,
      posY: 0,
    });
    sim.setBodyVelocity('ball', 0, -10, 0);
    sim.step(1);
    const body = sim.getBody('ball')!;
    expect(body.posY).toBeGreaterThanOrEqual(0);
    // |velY| * restitution * groundBounce = 10 * 0.8 * 0.5 = 4
    expect(body.velY).toBeCloseTo(4, 5);
  });

  it('horizontal damping attenuates velX/velZ each step', () => {
    const sim = createPhysics({ gravityY: 0, groundY: -100, linearDamping: 0.5 });
    sim.createBody('slide', {
      shapeType: 'box', motionType: 'dynamic', mass: 1,
      friction: 0, restitution: 0, lockRotation: false,
    });
    sim.setBodyVelocity('slide', 10, 0, 10);
    sim.step(1 / 60);
    expect(sim.getBody('slide')!.velX).toBeCloseTo(5, 5);
    expect(sim.getBody('slide')!.velZ).toBeCloseTo(5, 5);
  });

  it('setParams updates world behavior on the next step', () => {
    const sim = createPhysics({ gravityY: 0, groundY: -100, linearDamping: 1 });
    sim.createBody('ball', {
      shapeType: 'sphere', motionType: 'dynamic', mass: 1,
      friction: 0, restitution: 0, lockRotation: false,
      posY: 10,
    });
    sim.step(0.1);
    expect(sim.getBody('ball')!.velY).toBe(0);
    sim.setParams({ gravityY: -20 });
    sim.step(0.1);
    expect(sim.getBody('ball')!.velY).toBeCloseTo(-2, 5);
  });

  it('reset clears all bodies but leaves params intact', () => {
    const sim = createPhysics({ gravityY: -20 });
    sim.createBody('a', {
      shapeType: 'sphere', motionType: 'dynamic', mass: 1,
      friction: 0, restitution: 0, lockRotation: false,
    });
    sim.reset();
    expect(sim.bodies().length).toBe(0);
    expect(sim.getParams().gravityY).toBe(-20);
  });

  it('setBodyPosition writes the position of a known body and no-ops for unknown ids', () => {
    const sim = createPhysics();
    sim.createBody('ball', {
      shapeType: 'sphere', motionType: 'dynamic', mass: 1,
      friction: 0, restitution: 0, lockRotation: false,
    });
    sim.setBodyPosition('ball', 4, 5, 6);
    const body = sim.getBody('ball')!;
    expect(body.posX).toBe(4);
    expect(body.posY).toBe(5);
    expect(body.posZ).toBe(6);
    // Unknown id is a silent no-op (does not throw, creates nothing).
    expect(() => sim.setBodyPosition('ghost', 1, 1, 1)).not.toThrow();
    expect(sim.bodies().length).toBe(1);
  });

  it('createBody with a duplicate meshId replaces the existing body', () => {
    const sim = createPhysics();
    sim.createBody('ball', {
      shapeType: 'sphere', motionType: 'dynamic', mass: 1,
      friction: 0, restitution: 0, lockRotation: false,
      posX: 1,
    });
    sim.createBody('ball', {
      shapeType: 'box', motionType: 'dynamic', mass: 5,
      friction: 0, restitution: 0, lockRotation: false,
      posX: 7,
    });
    expect(sim.bodies().length).toBe(1);
    expect(sim.getBody('ball')!.shapeType).toBe('box');
    expect(sim.getBody('ball')!.posX).toBe(7);
  });
});

Physics.test.ts

20 ✓

PhysicsComponent

applies defaults
defaults to static when mass is zero
respects explicit motionType override even when mass is zero
serialize round-trips
toBodyOpts shape matches the adapter PhysicsBodyOpts fields

PhysicsSystem

calls physicsCreateBody when a mesh-carrying entity is added
emits BODY_CREATED when the body is registered
does not create a body if autoCreate is false
SET_VELOCITY input event forwards to physicsSetBodyVelocity
onUpdate calls physicsStep with the frame dt when not paused
PAUSE + RESUME events gate physicsStep on onUpdate
entity removal emits BODY_DISPOSED and calls physicsDestroyBody
shutdown disposes every body created by the system
SET_GRAVITY input event forwards to physicsSetGravity
SET_RESTITUTION mirrors the component and forwards to physicsSetRestitution
SET_RESTITUTION for an unknown entity still forwards without a component mirror
SET_COLLIDERS_VISIBLE input event forwards to setCollidersVisible
SET_TIME_STEP mirrors simulationHz onto the first component and forwards to physicsSetTimeStep
SET_TIME_STEP ignores non-finite or non-positive hz values
defers body creation until a sibling MeshPrimitive handle is ready

Last run 2026-08-22

Physics.test.ts

import { describe, it, expect, beforeEach, vi } from 'vitest';
import {
  PhysicsComponent,
  PhysicsSystem,
  PhysicsEvents,
  PhysicsInputEvents,
} from './Physics';
import { MeshPrimitiveComponent } from '../MeshPrimitive/MeshPrimitive.defs';
import { EventBus, World } from '@babylonjsmarket/ecs';
import { MockRendererAdapter } from '@babylonjsmarket/ecs';

describe('PhysicsComponent', () => {
  it('applies defaults', () => {
    const comp = new PhysicsComponent();
    expect(comp.shapeType).toBe('sphere');
    expect(comp.motionType).toBe('dynamic');
    expect(comp.mass).toBe(1);
    expect(comp.friction).toBe(0.5);
    expect(comp.restitution).toBe(0.5);
    expect(comp.lockRotation).toBe(false);
    expect(comp.autoCreate).toBe(true);
    expect(comp.isCreated).toBe(false);
  });

  it('defaults to static when mass is zero', () => {
    const comp = new PhysicsComponent({ mass: 0 });
    expect(comp.motionType).toBe('static');
  });

  it('respects explicit motionType override even when mass is zero', () => {
    const comp = new PhysicsComponent({ mass: 0, motionType: 'kinematic' });
    expect(comp.motionType).toBe('kinematic');
  });

  it('serialize round-trips', () => {
    const original = new PhysicsComponent({
      shapeType: 'capsule',
      motionType: 'kinematic',
      mass: 5,
      friction: 0.9,
      restitution: 0.2,
      lockRotation: true,
      autoCreate: false,
    });
    const copy = new PhysicsComponent(original.serialize());
    expect(copy.shapeType).toBe('capsule');
    expect(copy.motionType).toBe('kinematic');
    expect(copy.mass).toBe(5);
    expect(copy.lockRotation).toBe(true);
    expect(copy.autoCreate).toBe(false);
  });

  it('toBodyOpts shape matches the adapter PhysicsBodyOpts fields', () => {
    const comp = new PhysicsComponent({ shapeType: 'box', mass: 2, friction: 0.3 });
    const opts = comp.toBodyOpts();
    expect(opts.shapeType).toBe('box');
    expect(opts.mass).toBe(2);
    expect(opts.friction).toBe(0.3);
    expect(opts.motionType).toBe('dynamic');
  });
});

describe('PhysicsSystem', () => {
  let eventBus: EventBus;
  let world: World;
  let renderer: MockRendererAdapter;
  let system: PhysicsSystem;

  beforeEach(() => {
    eventBus = new EventBus();
    renderer = new MockRendererAdapter();
    world = new World({ eventBus, renderer });
    system = new PhysicsSystem(eventBus);
    world.addSystem(system);
    world.initialize();
  });

  function makeBodyEntity(meshId = 'body-mesh') {
    const entity = world.createEntity();
    const mesh = new MeshPrimitiveComponent({ primitive: 'sphere' });
    mesh.handle = renderer.createMesh(meshId, mesh.toPrimitiveSpec()) as ReturnType<
      typeof renderer.createMesh
    >;
    entity.add(mesh);
    entity.add(new PhysicsComponent({ shapeType: 'sphere', mass: 2, friction: 0.4 }));
    return entity;
  }

  it('calls physicsCreateBody when a mesh-carrying entity is added', () => {
    renderer.calls.length = 0;
    const entity = makeBodyEntity();
    const creates = renderer.calls.filter((c) => c.method === 'physicsCreateBody');
    expect(creates.length).toBe(1);
    expect(creates[0].args[0]).toBe(entity.id);
    const opts = creates[0].args[1] as Record<string, unknown>;
    expect(opts.shapeType).toBe('sphere');
    expect(opts.mass).toBe(2);
  });

  it('emits BODY_CREATED when the body is registered', () => {
    const spy = vi.fn();
    eventBus.on(PhysicsEvents.BODY_CREATED, spy);
    const entity = makeBodyEntity();
    expect(spy).toHaveBeenCalledTimes(1);
    expect(spy).toHaveBeenCalledWith(
      expect.objectContaining({ entityId: entity.id, shapeType: 'sphere', mass: 2 }),
    );
  });

  it('does not create a body if autoCreate is false', () => {
    const entity = world.createEntity();
    const mesh = new MeshPrimitiveComponent({ primitive: 'box' });
    mesh.handle = renderer.createMesh('m', mesh.toPrimitiveSpec()) as ReturnType<
      typeof renderer.createMesh
    >;
    entity.add(mesh);
    entity.add(new PhysicsComponent({ autoCreate: false }));
    renderer.calls.length = 0;
    world.update(1 / 60);
    expect(renderer.calls.some((c) => c.method === 'physicsCreateBody')).toBe(false);
  });

  it('SET_VELOCITY input event forwards to physicsSetBodyVelocity', () => {
    const entity = makeBodyEntity();
    renderer.calls.length = 0;
    eventBus.emit(PhysicsInputEvents.SET_VELOCITY, {
      entityId: entity.id,
      vx: 1, vy: 2, vz: 3,
    });
    const setVel = renderer.calls.find((c) => c.method === 'physicsSetBodyVelocity');
    expect(setVel).toBeDefined();
    expect(setVel?.args).toEqual([entity.id, 1, 2, 3]);
  });

  it('onUpdate calls physicsStep with the frame dt when not paused', () => {
    makeBodyEntity();
    renderer.calls.length = 0;
    world.update(0.016);
    const steps = renderer.calls.filter((c) => c.method === 'physicsStep');
    expect(steps.length).toBe(1);
    expect(steps[0].args[0]).toBe(0.016);
  });

  it('PAUSE + RESUME events gate physicsStep on onUpdate', () => {
    makeBodyEntity();
    eventBus.emit(PhysicsInputEvents.PAUSE, {});
    renderer.calls.length = 0;
    world.update(0.016);
    expect(renderer.calls.filter((c) => c.method === 'physicsStep').length).toBe(0);
    eventBus.emit(PhysicsInputEvents.RESUME, {});
    renderer.calls.length = 0;
    world.update(0.016);
    expect(renderer.calls.filter((c) => c.method === 'physicsStep').length).toBe(1);
  });

  it('entity removal emits BODY_DISPOSED and calls physicsDestroyBody', () => {
    const spy = vi.fn();
    eventBus.on(PhysicsEvents.BODY_DISPOSED, spy);
    const entity = makeBodyEntity();
    renderer.calls.length = 0;
    world.removeEntity(entity.id);
    const disposes = renderer.calls.filter((c) => c.method === 'physicsDestroyBody');
    expect(disposes.length).toBe(1);
    expect(disposes[0].args[0]).toBe(entity.id);
    expect(spy).toHaveBeenCalledWith({ entityId: entity.id });
  });

  it('shutdown disposes every body created by the system', () => {
    const a = makeBodyEntity('a');
    const b = makeBodyEntity('b');
    renderer.calls.length = 0;
    world.destroy();
    const disposeIds = new Set(
      renderer.calls.filter((c) => c.method === 'physicsDestroyBody').map((c) => c.args[0]),
    );
    expect(disposeIds.has(a.id)).toBe(true);
    expect(disposeIds.has(b.id)).toBe(true);
  });

  it('SET_GRAVITY input event forwards to physicsSetGravity', () => {
    makeBodyEntity();
    renderer.calls.length = 0;
    eventBus.emit(PhysicsInputEvents.SET_GRAVITY, { x: 0, y: -9.8, z: 0 });
    const call = renderer.calls.find((c) => c.method === 'physicsSetGravity');
    expect(call).toBeDefined();
    expect(call?.args).toEqual([0, -9.8, 0]);
  });

  it('SET_RESTITUTION mirrors the component and forwards to physicsSetRestitution', () => {
    const entity = makeBodyEntity();
    renderer.calls.length = 0;
    eventBus.emit(PhysicsInputEvents.SET_RESTITUTION, {
      entityId: entity.id,
      restitution: 0.9,
    });
    // Component is mirrored so serialize() picks up the live value.
    expect(entity.get(PhysicsComponent)?.restitution).toBe(0.9);
    const call = renderer.calls.find((c) => c.method === 'physicsSetRestitution');
    expect(call).toBeDefined();
    expect(call?.args).toEqual([entity.id, 0.9]);
  });

  it('SET_RESTITUTION for an unknown entity still forwards without a component mirror', () => {
    makeBodyEntity();
    renderer.calls.length = 0;
    eventBus.emit(PhysicsInputEvents.SET_RESTITUTION, {
      entityId: 'nope',
      restitution: 0.1,
    });
    const call = renderer.calls.find((c) => c.method === 'physicsSetRestitution');
    expect(call).toBeDefined();
    expect(call?.args).toEqual(['nope', 0.1]);
  });

  it('SET_COLLIDERS_VISIBLE input event forwards to setCollidersVisible', () => {
    makeBodyEntity();
    renderer.calls.length = 0;
    eventBus.emit(PhysicsInputEvents.SET_COLLIDERS_VISIBLE, { visible: true });
    const call = renderer.calls.find((c) => c.method === 'setCollidersVisible');
    expect(call).toBeDefined();
    expect(call?.args).toEqual([true]);
  });

  it('SET_TIME_STEP mirrors simulationHz onto the first component and forwards to physicsSetTimeStep', () => {
    const entity = makeBodyEntity();
    renderer.calls.length = 0;
    eventBus.emit(PhysicsInputEvents.SET_TIME_STEP, { hz: 240 });
    expect(entity.get(PhysicsComponent)?.simulationHz).toBe(240);
    const call = renderer.calls.find((c) => c.method === 'physicsSetTimeStep');
    expect(call).toBeDefined();
    expect(call?.args).toEqual([240]);
  });

  it('SET_TIME_STEP ignores non-finite or non-positive hz values', () => {
    const entity = makeBodyEntity();
    const before = entity.get(PhysicsComponent)!.simulationHz;
    renderer.calls.length = 0;
    eventBus.emit(PhysicsInputEvents.SET_TIME_STEP, { hz: 0 });
    eventBus.emit(PhysicsInputEvents.SET_TIME_STEP, { hz: -5 });
    eventBus.emit(PhysicsInputEvents.SET_TIME_STEP, { hz: Number.NaN });
    expect(entity.get(PhysicsComponent)!.simulationHz).toBe(before);
    expect(renderer.calls.some((c) => c.method === 'physicsSetTimeStep')).toBe(false);
  });

  it('defers body creation until a sibling MeshPrimitive handle is ready', () => {
    const entity = world.createEntity();
    const mesh = new MeshPrimitiveComponent({ primitive: 'sphere' });
    // No handle yet — mimics the interval between component attach and System mount.
    entity.add(mesh);
    entity.add(new PhysicsComponent());
    renderer.calls.length = 0;
    world.update(1 / 60);
    expect(renderer.calls.some((c) => c.method === 'physicsCreateBody')).toBe(false);
    // Mesh handle lands; next tick the body comes online.
    mesh.handle = renderer.createMesh('late', mesh.toPrimitiveSpec()) as ReturnType<
      typeof renderer.createMesh
    >;
    renderer.calls.length = 0;
    world.update(1 / 60);
    expect(renderer.calls.filter((c) => c.method === 'physicsCreateBody').length).toBe(1);
  });
});