Skip to content

Capture iPhone LiDAR and photos, reconstruct editable Three.js rooms, and explore them in a browser.

TypeScript
31.3 KB
Raw Blame
import * as THREE from 'three';
import type RAPIER_NS from '@dimforge/rapier3d-compat';
import type { BuiltRoom } from '../room-runtime/types';
import { decomposeCached } from './hull-cache';
import {
  autoTagConfig,
  guessSurface,
  isNamedObject,
  physicsTag,
  SURFACES,
  type AutoTagConfig,
  type PhysicsTag,
  type ShapeKind,
  type SurfaceKind,
} from './tagging';

export type Rapier = typeof RAPIER_NS;
export type World = RAPIER_NS.World;
export type RigidBody = RAPIER_NS.RigidBody;
export type Collider = RAPIER_NS.Collider;

export const FIXED_DT = 1 / 60;
export const GRAVITY = -9.81;

/** Collision groups (membership << 16 | filter) */
export const GROUP = {
  world: 0x0001,
  player: 0x0002,
  held: 0x0004,
};
export const groups = (member: number, filter: number) => ((member & 0xffff) << 16) | (filter & 0xffff);
/** held objects don't collide with the player's capsule (you'd shove yourself around) */
export const HELD_GROUPS = groups(GROUP.held, 0xffff & ~GROUP.player);
export const DEFAULT_GROUPS = groups(GROUP.world, 0xffff);

export async function loadRapier(): Promise<Rapier> {
  const mod = await import('@dimforge/rapier3d-compat');
  const R = mod.default;
  await R.init();
  return R;
}

/** One dynamic rigid body driving one Object3D */
export interface DynamicThing {
  name: string;
  obj: THREE.Object3D;
  body: RigidBody;
  colliders: Collider[];
  mass: number;
  shape: ShapeKind;
  surface: SurfaceKind;
  auto: boolean;
  /** largest bounding-box side (m) */
  size: number;
  home: { p: THREE.Vector3; q: THREE.Quaternion };
  prev: { p: THREE.Vector3; q: THREE.Quaternion };
  curr: { p: THREE.Vector3; q: THREE.Quaternion };
  asleep: boolean;
  /**
   * Frozen things are fixed bodies until something disturbs them (grab, shove, the player walking
   * into them, or a moving thing hitting them). Rapier wakes sleeping bodies on any new contact,
   * even with static geometry, so without this the whole room would jiggle and settle at load.
   */
  frozen: boolean;
  /** Objects resting directly on top at home; never a symmetric overlap graph. */
  supported: DynamicThing[];
  wakeOnImpact: boolean;
  /** home bounds (world) */
  bounds: THREE.Box3;
}

export interface PhysicsStats {
  staticChunks: number;
  staticTriangles: number;
  staticMeshes: number;
  skippedMeshes: number;
  dynamic: number;
  autoTagged: number;
  buildMs: number;
}

// ---------------------------------------------------------------------------------------------
// Geometry helpers

const _v = new THREE.Vector3();
const _m = new THREE.Matrix4();
const _mi = new THREE.Matrix4();

/** Visit every vertex of a mesh (instanced meshes: every instance) transformed by `M` */
function forEachVertex(mesh: THREE.Mesh, M: THREE.Matrix4, cb: (v: THREE.Vector3) => void) {
  const pos = mesh.geometry.getAttribute('position');
  if (!pos) return;
  const inst = mesh instanceof THREE.InstancedMesh ? mesh : undefined;
  const count = inst ? inst.count : 1;
  for (let k = 0; k < count; k++) {
    if (inst) {
      inst.getMatrixAt(k, _mi);
      _m.multiplyMatrices(M, _mi);
    } else _m.copy(M);
    for (let i = 0; i < pos.count; i++) cb(_v.fromBufferAttribute(pos, i).applyMatrix4(_m));
  }
}

/** Append a mesh's triangles (transformed by M) to flat vertex/index arrays */
function appendTriangles(mesh: THREE.Mesh, M: THREE.Matrix4, verts: number[], idx: number[]) {
  const g = mesh.geometry;
  const pos = g.getAttribute('position');
  if (!pos) return;
  const inst = mesh instanceof THREE.InstancedMesh ? mesh : undefined;
  const count = inst ? inst.count : 1;
  const index = g.index;
  // respect draw range / groups loosely: whole index
  for (let k = 0; k < count; k++) {
    if (inst) {
      inst.getMatrixAt(k, _mi);
      _m.multiplyMatrices(M, _mi);
    } else _m.copy(M);
    const base = verts.length / 3;
    for (let i = 0; i < pos.count; i++) {
      _v.fromBufferAttribute(pos, i).applyMatrix4(_m);
      verts.push(_v.x, _v.y, _v.z);
    }
    if (index) for (let i = 0; i < index.count; i++) idx.push(base + index.getX(i));
    else for (let i = 0; i < pos.count; i++) idx.push(base + i);
  }
}

/** World-space bounds of the meshes under `root`, skipping subtrees rejected by `skip` */
function meshBounds(root: THREE.Object3D, skip?: (o: THREE.Object3D) => boolean) {
  const box = new THREE.Box3();
  const b = new THREE.Box3();
  const visit = (o: THREE.Object3D) => {
    if (o !== root && skip?.(o)) return;
    if (!o.visible) return;
    if (o instanceof THREE.Mesh) {
      const g = o.geometry;
      if (o instanceof THREE.InstancedMesh) {
        o.computeBoundingBox();
        b.copy(o.boundingBox!).applyMatrix4(o.matrixWorld);
      } else {
        if (!g.boundingBox) g.computeBoundingBox();
        b.copy(g.boundingBox!).applyMatrix4(o.matrixWorld);
      }
      box.union(b);
    }
    for (const c of o.children) visit(c);
  };
  visit(root);
  return box;
}

const materialsOf = (m: THREE.Mesh) => (Array.isArray(m.material) ? m.material : [m.material]);

/** Glows, halos, light cones, cables and crumbs don't get colliders */
function skipStaticMesh(mesh: THREE.Mesh, bounds: THREE.Box3): boolean {
  const mats = materialsOf(mesh);
  if (mats.every((m) => !m || !m.visible)) return true;
  if (mats.every((m) => m.blending === THREE.AdditiveBlending)) return true;
  if (mats.every((m) => m.transparent && m.opacity < 0.35)) return true;
  if (mats.every((m) => m instanceof THREE.MeshBasicMaterial && m.transparent && !m.depthWrite)) return true;
  if (/glow|halo|beam|cone|bloom|sprite|shadow-catcher/i.test(mesh.name)) return true;
  if (/cable|cord|wire/i.test(mesh.name)) return true;
  const size = bounds.getSize(_v);
  if (Math.max(size.x, size.y, size.z) < 0.012) return true;
  const g = mesh.geometry as THREE.BufferGeometry & { parameters?: { radius?: number } };
  if (g.type === 'TubeGeometry' && (g.parameters?.radius ?? 1) * mesh.getWorldScale(_v).x < 0.012) return true;
  return false;
}

// ---------------------------------------------------------------------------------------------
// Classification: walk the room once, sort every mesh into static / dynamic / none

interface DynamicCandidate {
  obj: THREE.Object3D;
  tag: PhysicsTag;
  auto: boolean;
  bounds: THREE.Box3;
}

function classify(room: BuiltRoom, roomId: string, cfg: AutoTagConfig) {
  const root = room.group;
  root.updateMatrixWorld(true);
  const wallGroups = new Set(room.walls.map((w) => w.group));
  const shellParts = new Set<THREE.Object3D>([...wallGroups, ...room.ceiling]);
  root.children.forEach((c) => {
    if (/^(floor|ceiling)$/i.test(c.name)) shellParts.add(c);
  });

  const dynamics: DynamicCandidate[] = [];
  const candidates: { obj: THREE.Object3D; bounds: THREE.Box3; chunk: THREE.Object3D }[] = [];
  /** static meshes, grouped by top-level chunk (one trimesh each) */
  const statics = new Map<THREE.Object3D, THREE.Mesh[]>();
  const addStatic = (chunk: THREE.Object3D, m: THREE.Mesh) => {
    let list = statics.get(chunk);
    if (!list) statics.set(chunk, (list = []));
    list.push(m);
  };

  // meshes under an explicitly-tagged dynamic node belong to its body; nested dynamic tags
  // (a book on a cart) start their own body
  const visit = (o: THREE.Object3D, chunk: THREE.Object3D, underWall: boolean, noAuto: boolean) => {
    if (!o.visible) return;
    if (o.userData.physicsChunk) chunk = o;
    const tag = physicsTag(o);
    if (tag?.type === 'none') return;
    if (o !== root && tag?.type === 'dynamic') {
      dynamics.push({ obj: o, tag, auto: false, bounds: meshBounds(o, (c) => !!physicsTag(c) && physicsTag(c)!.type !== 'static') });
      // find nested dynamic things
      const nested = (c: THREE.Object3D) => {
        for (const cc of c.children) {
          const t = physicsTag(cc);
          if (t?.type === 'none') continue;
          if (t?.type === 'dynamic') visit(cc, chunk, underWall, true);
          else nested(cc);
        }
      };
      nested(o);
      return;
    }
    const isStaticTag = tag?.type === 'static';
    const wall = underWall || wallGroups.has(o as THREE.Group);
    const inShell = shellParts.has(o);
    if (cfg.enabled && !noAuto && !isStaticTag && !wall && !inShell && o !== root && (cfg.requireName ? isNamedObject(o) : !o.name.includes(':')) && !cfg.exclude.test(o.name)) {
      const b = meshBounds(o, (c) => !!physicsTag(c));
      if (!b.isEmpty()) {
        const s = b.getSize(new THREE.Vector3());
        const max = Math.max(s.x, s.y, s.z);
        const thin = [s.x, s.y, s.z].filter((d) => d < cfg.minThickness).length >= 2 || Math.min(s.x, s.y, s.z) < 0.002;
        if (max <= cfg.maxSize && max >= cfg.minSize && !thin && !hasTaggedDescendant(o)) {
          candidates.push({ obj: o, bounds: b, chunk });
          return;
        }
      }
    }
    if (o instanceof THREE.Mesh) addStatic(chunk, o);
    for (const c of o.children) visit(c, o === root ? c : chunk, wall, noAuto || isStaticTag);
  };
  visit(root, root, false, false);

  return { dynamics, candidates, statics, wallGroups };
}

function hasTaggedDescendant(o: THREE.Object3D) {
  let found = false;
  o.traverse((c) => {
    if (c !== o && physicsTag(c)?.type === 'dynamic') found = true;
  });
  return found;
}

/** Is a candidate free-standing on something (not mounted on a wall or hanging in the air)? */
function supportTest(
  cand: { obj: THREE.Object3D; bounds: THREE.Box3 },
  others: THREE.Mesh[],
  room: BuiltRoom,
  cfg: AutoTagConfig,
): { ok: boolean; why: string } {
  const b = cand.bounds;
  // wall-mounted: hugging a wall plane, off the floor
  if (b.min.y > cfg.wallMountMinY) {
    for (const { def } of room.walls) {
      const n = def.n as THREE.Vector3;
      const o = def.origin as THREE.Vector3;
      const u = def.u as THREE.Vector3;
      let minD = Infinity;
      let along0 = Infinity;
      let along1 = -Infinity;
      for (const x of [b.min.x, b.max.x]) {
        for (const z of [b.min.z, b.max.z]) {
          _v.set(x - o.x, 0, z - o.z);
          minD = Math.min(minD, _v.x * n.x + _v.z * n.z);
          const a = _v.x * u.x + _v.z * u.z;
          along0 = Math.min(along0, a);
          along1 = Math.max(along1, a);
        }
      }
      if (minD < cfg.wallGap && along1 > 0 && along0 < def.length) return { ok: false, why: 'wall-mounted' };
    }
  }
  if (b.min.y < 0.02) return { ok: true, why: 'on the floor' };
  // rays straight down from the bottom center + four inset corners
  const ray = new THREE.Raycaster();
  ray.far = cfg.supportGap + 0.03;
  const own = new Set<THREE.Object3D>();
  cand.obj.traverse((c) => own.add(c));
  const near = others.filter((m) => {
    if (own.has(m)) return false;
    const mb = meshBoundsCache.get(m)!;
    return mb.max.y > b.min.y - cfg.supportGap - 0.03 && mb.min.y < b.min.y + 0.03 && mb.min.x < b.max.x && mb.max.x > b.min.x && mb.min.z < b.max.z && mb.max.z > b.min.z;
  });
  if (!near.length) return { ok: false, why: 'nothing below (floating/mounted)' };
  const c = b.getCenter(new THREE.Vector3());
  const hx = (b.max.x - b.min.x) * 0.3;
  const hz = (b.max.z - b.min.z) * 0.3;
  for (const [dx, dz] of [[0, 0], [hx, hz], [-hx, hz], [hx, -hz], [-hx, -hz]]) {
    ray.set(new THREE.Vector3(c.x + dx, b.min.y + 0.03, c.z + dz), new THREE.Vector3(0, -1, 0));
    if (ray.intersectObjects(near, false).length) return { ok: true, why: 'resting on something' };
  }
  return { ok: false, why: 'nothing below (floating/mounted)' };
}

const meshBoundsCache = new WeakMap<THREE.Mesh, THREE.Box3>();

// ---------------------------------------------------------------------------------------------
// The physics scene

export class Physics {
  readonly world: World;
  readonly things: DynamicThing[] = [];
  readonly byCollider = new Map<number, DynamicThing>();
  readonly byBody = new Map<number, DynamicThing>();
  readonly events: RAPIER_NS.EventQueue;
  stats: PhysicsStats = { staticChunks: 0, staticTriangles: 0, staticMeshes: 0, skippedMeshes: 0, dynamic: 0, autoTagged: 0, buildMs: 0 };
  autoLog: { name: string; picked: boolean; why: string; size: string; mass?: number }[] = [];
  /** called before every fixed step (player movement, grabbing) */
  beforeStep: ((dt: number) => void)[] = [];
  /** contact force events: (thing, force N) */
  onImpact?: (thing: DynamicThing, force: number, other?: DynamicThing) => void;
  private acc = 0;
  alpha = 0;
  stepsTaken = 0;
  /** debug: slow motion / freeze-frame */
  timeScale = 1;
  paused = false;

  constructor(
    readonly R: Rapier,
    readonly scene: THREE.Scene,
  ) {
    this.world = new R.World({ x: 0, y: GRAVITY, z: 0 });
    this.world.timestep = FIXED_DT;
    // a few extra iterations for stable stacks of boxes/books
    this.world.numSolverIterations = 6;
    this.events = new R.EventQueue(true);
  }

  async buildFromRoom(room: BuiltRoom, roomId: string, onProgress?: (msg: string) => void) {
    const t0 = performance.now();
    const R = this.R;
    const cfg = autoTagConfig(roomId);
    const { dynamics, candidates, statics } = classify(room, roomId, cfg);

    // support test for auto candidates: raycast against everything else
    const allMeshes: THREE.Mesh[] = [];
    room.group.traverse((o) => {
      if (o instanceof THREE.Mesh && o.visible) {
        allMeshes.push(o);
        meshBoundsCache.set(o, meshBounds(o));
      }
    });
    for (const cand of candidates) {
      const test = supportTest(cand, allMeshes, room, cfg);
      const s = cand.bounds.getSize(new THREE.Vector3());
      const size = `${s.x.toFixed(2)}×${s.y.toFixed(2)}×${s.z.toFixed(2)}`;
      if (test.ok) {
        const surface = guessSurface(cand.obj);
        const mass = THREE.MathUtils.clamp(s.x * s.y * s.z * cfg.fill * SURFACES[surface].density, cfg.minMass, cfg.maxMass);
        const tag: PhysicsTag = { type: 'dynamic', mass: +mass.toFixed(2), surface };
        dynamics.push({ obj: cand.obj, tag, auto: true, bounds: cand.bounds });
        this.autoLog.push({ name: cand.obj.name, picked: true, why: test.why, size, mass: tag.mass });
      } else {
        this.autoLog.push({ name: cand.obj.name, picked: false, why: test.why, size });
        cand.obj.traverse((o) => {
          if (o instanceof THREE.Mesh && o.visible && physicsTag(o)?.type !== 'none') {
            let list = statics.get(cand.chunk);
            if (!list) statics.set(cand.chunk, (list = []));
            list.push(o);
          }
        });
      }
    }

    // --- static geometry: one trimesh per top-level chunk
    onProgress?.('Building static colliders…');
    const floorBox = new THREE.Box3();
    for (const [chunk, meshes] of statics) {
      const verts: number[] = [];
      const idx: number[] = [];
      for (const m of meshes) {
        const b = meshBoundsCache.get(m) ?? meshBounds(m);
        if (skipStaticMesh(m, b)) {
          this.stats.skippedMeshes++;
          continue;
        }
        appendTriangles(m, m.matrixWorld, verts, idx);
        this.stats.staticMeshes++;
        floorBox.union(b);
      }
      if (!idx.length) continue;
      const desc = R.ColliderDesc.trimesh(new Float32Array(verts), new Uint32Array(idx), roomId === 'house'
        ? R.TriMeshFlags.FIX_INTERNAL_EDGES | R.TriMeshFlags.DELETE_DEGENERATE_TRIANGLES | R.TriMeshFlags.DELETE_DUPLICATE_TRIANGLES : undefined)
        .setFriction(0.7)
        .setRestitution(0.1)
        .setCollisionGroups(DEFAULT_GROUPS);
      const c = this.world.createCollider(desc);
      c.setActiveEvents(R.ActiveEvents.NONE);
      this.stats.staticChunks++;
      this.stats.staticTriangles += idx.length / 3;
      void chunk;
      await yieldFrame();
    }
    // a thick floor slab under everything, so fast throws never tunnel through a 2-triangle floor
    if (!floorBox.isEmpty()) {
      const c = floorBox.getCenter(new THREE.Vector3());
      const s = floorBox.getSize(new THREE.Vector3());
      this.world.createCollider(R.ColliderDesc.cuboid(s.x / 2 + 2, 0.5, s.z / 2 + 2).setTranslation(c.x, -0.5, c.z).setFriction(0.7).setRestitution(0.1));
    }

    // --- dynamic bodies
    onProgress?.(`Building ${dynamics.length} dynamic bodies…`);
    let n = 0;
    for (const d of dynamics) {
      try {
        await this.addDynamic(d);
      } catch (e) {
        console.warn(`[play] couldn't build a body for "${d.obj.name}"`, e);
      }
      if (++n % 8 === 0) {
        onProgress?.(`Building dynamic bodies… ${n}/${dynamics.length}`);
        await yieldFrame();
      }
    }
    // A supported object can fall when its support is moved. Side-by-side objects
    // and furniture enclosing loose props must not create a room-wide wake chain.
    for (const support of this.things) {
      for (const item of this.things) {
        if (item === support || !item.wakeOnImpact || physicsTag(item.obj)?.wakeOnSupportLoss === false) continue;
        const a = support.bounds, b = item.bounds;
        if (Math.abs(b.min.y - a.max.y) <= .025 && b.min.y > a.min.y + .01
          && Math.min(a.max.x, b.max.x) - Math.max(a.min.x, b.min.x) > .01
          && Math.min(a.max.z, b.max.z) - Math.max(a.min.z, b.min.z) > .01) support.supported.push(item);
      }
    }
    this.stats.dynamic = this.things.length;
    this.stats.autoTagged = this.things.filter((t) => t.auto).length;
    this.stats.buildMs = Math.round(performance.now() - t0);
  }

  private async addDynamic({ obj, tag, auto, bounds }: DynamicCandidate) {
    const R = this.R;
    obj.updateWorldMatrix(true, true);
    // the body frame: the object's world position/rotation (no scale)
    const p = new THREE.Vector3();
    const q = new THREE.Quaternion();
    const s = new THREE.Vector3();
    obj.matrixWorld.decompose(p, q, s);
    const frameInv = new THREE.Matrix4().compose(p, q, new THREE.Vector3(1, 1, 1)).invert();

    // meshes that belong to this body (not nested dynamic/none subtrees)
    const meshes: THREE.Mesh[] = [];
    const collect = (o: THREE.Object3D) => {
      if (o !== obj) {
        const t = physicsTag(o);
        if (t?.type === 'dynamic' || t?.type === 'none') return;
      }
      if (!o.visible) return;
      if (o instanceof THREE.Mesh && !skipDynamicMesh(o)) meshes.push(o);
      for (const c of o.children) collect(c);
    };
    collect(obj);
    if (!meshes.length) return;

    const surface = tag.surface ?? guessSurface(obj);
    const surf = SURFACES[surface];
    const size = bounds.getSize(new THREE.Vector3());
    const maxSize = Math.max(size.x, size.y, size.z);
    const mass = tag.mass ?? THREE.MathUtils.clamp(size.x * size.y * size.z * 0.35 * surf.density, 0.05, 40);
    let shape: ShapeKind = tag.shape ?? autoShape(meshes, obj);

    // local-frame bounds of the body's meshes
    const local = new THREE.Box3();
    const M = new THREE.Matrix4();
    for (const m of meshes) {
      M.multiplyMatrices(frameInv, m.matrixWorld);
      forEachVertex(m, M, (v) => local.expandByPoint(v));
    }
    const lc = local.getCenter(new THREE.Vector3());
    const ls = local.getSize(new THREE.Vector3()).max(new THREE.Vector3(0.004, 0.004, 0.004));

    const descs: { desc: RAPIER_NS.ColliderDesc; vol: number }[] = [];
    const hullOf = (points: Float32Array) => R.ColliderDesc.convexHull(points);
    const inset = tag.boxInset ?? [0, 0, 0];
    const boxDesc = () => ({ desc: R.ColliderDesc.cuboid(Math.max(.002, ls.x / 2 - inset[0]), Math.max(.002, ls.y / 2 - inset[1]), Math.max(.002, ls.z / 2 - inset[2])).setTranslation(lc.x, lc.y, lc.z), vol: ls.x * ls.y * ls.z });

    if (shape === 'box') descs.push(boxDesc());
    else if (shape === 'sphere') {
      const r = (ls.x + ls.y + ls.z) / 6;
      descs.push({ desc: R.ColliderDesc.ball(r).setTranslation(lc.x, lc.y, lc.z), vol: (4 / 3) * Math.PI * r ** 3 });
    } else if (shape === 'cylinder') {
      const r = Math.max(ls.x, ls.z) / 2;
      descs.push({ desc: R.ColliderDesc.cylinder(ls.y / 2, r).setTranslation(lc.x, lc.y, lc.z), vol: Math.PI * r * r * ls.y });
    } else if (shape === 'container') {
      descs.push(...containerDescs(R, local, !!tag.round));
    } else if (shape === 'compound') {
      for (const m of meshes) {
        M.multiplyMatrices(frameInv, m.matrixWorld);
        const pts = hullPoints([m], [M.clone()]);
        const d = pts.length >= 12 ? hullOf(pts) : null;
        if (d) descs.push({ desc: d, vol: boxVolume(pts) });
      }
    } else if (shape === 'decompose') {
      const verts: number[] = [];
      const idx: number[] = [];
      for (const m of meshes) appendTriangles(m, M.multiplyMatrices(frameInv, m.matrixWorld), verts, idx);
      const parts = await decomposeCached(R, `${obj.name}|${idx.length}|${ls.toArray().map((x) => x.toFixed(3)).join(',')}`, verts, idx);
      for (const pts of parts) {
        const d = hullOf(pts);
        if (d) descs.push({ desc: d, vol: boxVolume(pts) });
      }
    }
    if (!descs.length) {
      // default + fallback: one convex hull over everything
      const mats = meshes.map((m) => new THREE.Matrix4().multiplyMatrices(frameInv, m.matrixWorld));
      const pts = hullPoints(meshes, mats);
      const d = pts.length >= 12 ? hullOf(pts) : null;
      if (d) descs.push({ desc: d, vol: ls.x * ls.y * ls.z });
      else descs.push(boxDesc());
      if (shape !== 'hull' && shape !== 'box') shape = 'hull';
    }

    const bodyDesc = R.RigidBodyDesc.dynamic()
      .setTranslation(p.x, p.y, p.z)
      .setRotation({ x: q.x, y: q.y, z: q.z, w: q.w })
      .setCcdEnabled(true)
      .setLinearDamping(surf.damping)
      // no rolling resistance in Rapier: balls and cylinders would roll across the whole room
      .setAngularDamping((shape === 'sphere' || shape === 'cylinder' ? 0.9 : 0.25) + surf.damping)
      .setSleeping(true);
    const body = this.world.createRigidBody(bodyDesc);
    const totalVol = descs.reduce((a, d) => a + d.vol, 0) || 1;
    const friction = tag.friction ?? surf.friction;
    const restitution = tag.restitution ?? surf.restitution;
    const colliders: Collider[] = [];
    for (const { desc, vol } of descs) {
      desc
        .setMass((mass * vol) / totalVol)
        .setFriction(friction)
        .setRestitution(restitution)
        .setRestitutionCombineRule(surface === 'rubber' ? R.CoefficientCombineRule.Max : R.CoefficientCombineRule.Average)
        .setCollisionGroups(DEFAULT_GROUPS)
        .setActiveEvents(R.ActiveEvents.CONTACT_FORCE_EVENTS | R.ActiveEvents.COLLISION_EVENTS)
        .setContactForceEventThreshold(Math.max(1.5, mass * 22));
      colliders.push(this.world.createCollider(desc, body));
    }
    // frozen (fixed) until disturbed, so the room stays exactly as modeled
    body.setBodyType(R.RigidBodyType.Fixed, false);

    // the body drives the Object3D from now on: move it to the scene root, keep its world transform
    this.scene.attach(obj);
    obj.matrixAutoUpdate = true;

    if (!obj.name) obj.name = `${surface}-${shape}-${this.things.length}`;
    const thing: DynamicThing = {
      name: obj.name,
      obj,
      body,
      colliders,
      mass,
      shape,
      surface,
      auto,
      size: maxSize,
      home: { p: p.clone(), q: q.clone() },
      prev: { p: p.clone(), q: q.clone() },
      curr: { p: p.clone(), q: q.clone() },
      asleep: true,
      frozen: true,
      supported: [],
      wakeOnImpact: tag.wakeOnImpact !== false,
      bounds: bounds.clone(),
    };
    obj.userData.playThing = thing;
    this.things.push(thing);
    this.byBody.set(body.handle, thing);
    for (const c of colliders) this.byCollider.set(c.handle, thing);
  }

  /** Advance by real time `dt` in fixed 60 Hz steps, then interpolate the visuals */
  update(dt: number) {
    if (this.paused) return this.interpolate();
    this.acc += Math.min(dt, 0.1) * this.timeScale;
    let steps = 0;
    while (this.acc >= FIXED_DT && steps < 4) {
      for (const f of this.beforeStep) f(FIXED_DT);
      this.preStepVelocity.clear();
      for (const thing of this.things) if (!thing.frozen) this.preStepVelocity.set(thing.body.handle, thing.body.linvel());
      this.world.step(this.events);
      this.afterStep();
      this.acc -= FIXED_DT;
      steps++;
      this.stepsTaken++;
    }
    if (steps === 4) this.acc = 0; // way behind (tab was hidden): don't spiral
    this.alpha = this.acc / FIXED_DT;
    return this.interpolate();
  }

  private preStepVelocity = new Map<number, { x: number; y: number; z: number }>();
  private pendingImpacts = new Map<string, number>();
  private lastImpact = new Map<number, number>();
  private pairKey(a: number, b: number) { return a < b ? `${a}:${b}` : `${b}:${a}`; }
  private relativeSpeed(a?: DynamicThing, b?: DynamicThing) {
    const va = a && this.preStepVelocity.get(a.body.handle);
    const vb = b && this.preStepVelocity.get(b.body.handle);
    return Math.hypot((va?.x ?? 0) - (vb?.x ?? 0), (va?.y ?? 0) - (vb?.y ?? 0), (va?.z ?? 0) - (vb?.z ?? 0));
  }
  private afterStep() {
    for (const t of this.things) {
      const b = t.body;
      if (t.frozen) continue;
      const sleeping = b.isSleeping();
      if (sleeping && t.asleep) continue;
      t.asleep = sleeping;
      t.prev.p.copy(t.curr.p);
      t.prev.q.copy(t.curr.q);
      const tr = b.translation();
      const rot = b.rotation();
      t.curr.p.set(tr.x, tr.y, tr.z);
      t.curr.q.set(rot.x, rot.y, rot.z, rot.w);
      // fell out of the world (through an open door into the void): put it back
      if (tr.y < -5) this.resetThing(t);
    }
    this.events.drainCollisionEvents((h1, h2, started) => {
      const key = this.pairKey(h1, h2);
      if (!started) { this.pendingImpacts.delete(key); return; }
      const a = this.byCollider.get(h1), b = this.byCollider.get(h2);
      const speed = this.relativeSpeed(a, b);
      if (speed >= .6) this.pendingImpacts.set(key, this.stepsTaken + 3);
      // Overlapping home colliders and resting contact are not a new strike.
      if (speed < .35) return;
      if (a?.frozen && a.wakeOnImpact && b && !b.frozen) this.unfreeze(a);
      else if (b?.frozen && b.wakeOnImpact && a && !a.frozen) this.unfreeze(b);
    });
    this.events.drainContactForceEvents(e => {
      const key = this.pairKey(e.collider1(), e.collider2());
      if (!this.pendingImpacts.has(key)) return;
      this.pendingImpacts.delete(key); // One sound per fresh contact, never sustained force.
      const a = this.byCollider.get(e.collider1()), b = this.byCollider.get(e.collider2());
      const thing = a && this.preStepVelocity.has(a.body.handle) ? a : b;
      if (!thing) return;
      const last = this.lastImpact.get(thing.body.handle) ?? -Infinity;
      if (this.stepsTaken - last < 15) return;
      this.lastImpact.set(thing.body.handle, this.stepsTaken);
      this.onImpact?.(thing, e.totalForceMagnitude(), thing === a ? b : a);
    });
    for (const [key, expires] of this.pendingImpacts) if (this.stepsTaken >= expires) this.pendingImpacts.delete(key);
  }

  /** returns how many things are moving (for shadow map refresh) */
  private interpolate() {
    let moving = 0;
    for (const t of this.things) {
      if (t.asleep && t.prev.p.equals(t.curr.p) && t.prev.q.equals(t.curr.q)) continue;
      moving++;
      t.obj.position.lerpVectors(t.prev.p, t.curr.p, this.alpha);
      t.obj.quaternion.slerpQuaternions(t.prev.q, t.curr.q, this.alpha);
      if (t.asleep) {
        // settle the visual on the final pose once asleep
        t.prev.p.copy(t.curr.p);
        t.prev.q.copy(t.curr.q);
        t.obj.position.copy(t.curr.p);
        t.obj.quaternion.copy(t.curr.q);
      }
    }
    return moving;
  }

  /** Move this object and any loose items resting on top, never adjoining furniture. */
  unfreeze(t: DynamicThing | undefined) {
    if (!t?.frozen) return;
    t.frozen = false;
    t.body.setBodyType(this.R.RigidBodyType.Dynamic, true);
    t.body.wakeUp();
    t.asleep = false;
    for (const n of t.supported) this.unfreeze(n);
  }

  resetThing(t: DynamicThing) {
    const b = t.body;
    if (!t.frozen) {
      b.setBodyType(this.R.RigidBodyType.Fixed, false);
      t.frozen = true;
    }
    b.setTranslation(t.home.p, false);
    b.setRotation(t.home.q, false);
    b.setLinvel({ x: 0, y: 0, z: 0 }, false);
    b.setAngvel({ x: 0, y: 0, z: 0 }, false);
    t.prev.p.copy(t.home.p);
    t.prev.q.copy(t.home.q);
    t.curr.p.copy(t.home.p);
    t.curr.q.copy(t.home.q);
    t.obj.position.copy(t.home.p);
    t.obj.quaternion.copy(t.home.q);
    t.asleep = true;
  }

  resetAll() {
    this.pendingImpacts.clear();
    this.lastImpact.clear();
    this.preStepVelocity.clear();
    for (const t of this.things) this.resetThing(t);
  }

  thingForCollider(c: Collider | null | undefined) {
    return c ? this.byCollider.get(c.handle) : undefined;
  }

  find(name: string) {
    const exact = this.things.find((t) => t.name === name);
    if (exact) return exact;
    const lower = name.toLowerCase();
    return this.things.find((t) => t.name.toLowerCase().includes(lower));
  }
}

function skipDynamicMesh(m: THREE.Mesh) {
  const mats = materialsOf(m);
  return mats.every((x) => x.blending === THREE.AdditiveBlending || (x.transparent && x.opacity < 0.2));
}

/** A lone sphere mesh gets a real ball collider (so balls roll) */
function autoShape(meshes: THREE.Mesh[], obj: THREE.Object3D): ShapeKind {
  if (meshes.length === 1 && meshes[0].geometry.type === 'SphereGeometry') {
    // a real ball: round in world space (pillows and sacks are deformed spheres)
    const size = meshBounds(meshes[0]).getSize(new THREE.Vector3());
    const [lo, hi] = [Math.min(size.x, size.y, size.z), Math.max(size.x, size.y, size.z)];
    if (hi - lo < 0.08 * hi) return 'sphere';
  }
  if (/\bball\b/i.test(obj.name)) return 'sphere';
  return 'hull';
}

/** Unique-ish hull input points: quantized to 3 mm (1 cm for huge meshes) */
function hullPoints(meshes: THREE.Mesh[], mats: THREE.Matrix4[]) {
  let total = 0;
  for (const m of meshes) total += m.geometry.getAttribute('position')?.count ?? 0;
  const q = total > 60000 ? 0.01 : 0.003;
  const seen = new Set<string>();
  const out: number[] = [];
  meshes.forEach((m, i) => {
    forEachVertex(m, mats[i], (v) => {
      const k = `${Math.round(v.x / q)},${Math.round(v.y / q)},${Math.round(v.z / q)}`;
      if (seen.has(k)) return;
      seen.add(k);
      out.push(v.x, v.y, v.z);
    });
  });
  return new Float32Array(out);
}

function boxVolume(pts: Float32Array) {
  const b = new THREE.Box3();
  for (let i = 0; i < pts.length; i += 3) b.expandByPoint(_v.set(pts[i], pts[i + 1], pts[i + 2]));
  const s = b.getSize(_v);
  return Math.max(1e-6, s.x * s.y * s.z);
}

/** Open-top container: a floor and thin walls around its (local) bounds */
function containerDescs(R: Rapier, b: THREE.Box3, round: boolean) {
  const c = b.getCenter(new THREE.Vector3());
  const s = b.getSize(new THREE.Vector3());
  const t = THREE.MathUtils.clamp(Math.min(s.x, s.z) * 0.06, 0.008, 0.025);
  const out: { desc: RAPIER_NS.ColliderDesc; vol: number }[] = [];
  const add = (hx: number, hy: number, hz: number, x: number, y: number, z: number, rotY = 0) => {
    const d = R.ColliderDesc.cuboid(hx, hy, hz).setTranslation(x, y, z);
    if (rotY) d.setRotation({ x: 0, y: Math.sin(rotY / 2), z: 0, w: Math.cos(rotY / 2) });
    out.push({ desc: d, vol: 8 * hx * hy * hz });
  };
  add(s.x / 2, t / 2, s.z / 2, c.x, b.min.y + t / 2, c.z); // floor
  const hy = s.y / 2;
  if (round) {
    const r = (s.x + s.z) / 4 - t / 2;
    const n = 12;
    const half = Math.tan(Math.PI / n) * (r + t / 2) + t / 2;
    for (let i = 0; i < n; i++) {
      const a = (i / n) * Math.PI * 2;
      add(half, hy, t / 2, c.x + Math.sin(a) * r, c.y, c.z + Math.cos(a) * r, a);
    }
  } else {
    add(s.x / 2, hy, t / 2, c.x, c.y, b.min.z + t / 2);
    add(s.x / 2, hy, t / 2, c.x, c.y, b.max.z - t / 2);
    add(t / 2, hy, s.z / 2, b.min.x + t / 2, c.y, c.z);
    add(t / 2, hy, s.z / 2, b.max.x - t / 2, c.y, c.z);
  }
  return out;
}

const yieldFrame = () => new Promise<void>((r) => setTimeout(r, 0));