Made of little things.

// modelsUnderRay(origin, direction, 1, #detailed) against the static copy of
// the level ("3d2" in the original), which the wheels and camera raycast into.
// Shockwave 3D only reports front faces (every level model has the default
// #front visibility): the original's logger shows an upside-down car's wheel
// rays, which start just under the floor, finding no ground. Testing back faces
// made them read full compression and fling the car.
import { BufferAttribute, BufferGeometry, FrontSide, Ray, Vector3 } from 'three';
import { MeshBVH } from 'three-mesh-bvh';

export interface RayHit {
  model: string;
  isectPosition: Vector3;
  isectNormal: Vector3;
  distance: number;
}

export class RayWorld {
  private readonly bvh: MeshBVH;
  private readonly owner: Uint16Array;
  private readonly ray = new Ray();

  constructor(
    positions: Float32Array,
    indices: Uint32Array,
    owner: Uint16Array,
    private readonly modelNames: string[],
  ) {
    const geometry = new BufferGeometry();
    geometry.setAttribute('position', new BufferAttribute(positions, 3));
    geometry.setIndex(new BufferAttribute(indices, 1));
    this.owner = owner;
    this.bvh = new MeshBVH(geometry);
  }

  /** First hit along the ray (direction need not be normalised), or null. */
  modelsUnderRay(origin: Vector3, direction: Vector3): RayHit | null {
    this.ray.origin.copy(origin);
    this.ray.direction.copy(direction).normalize();
    const hit = this.bvh.raycastFirst(this.ray, FrontSide);
    if (!hit || !hit.face || hit.faceIndex == null) return null;
    return {
      model: this.modelNames[this.owner[hit.faceIndex]] ?? '',
      isectPosition: hit.point.clone(),
      isectNormal: hit.face.normal.clone(),
      distance: hit.distance,
    };
  }
}