@directivegames/genesys.js 3.1.24

package/src/physics/implementations/RapierPhysics.ts

@@ -0,0 +1,1419 @@
+/**
+ * RapierPhysicsEngine powers Genesys physics using the Rapier library.
+ *
+ * This implementation extends `BasePhysicsEngine` and converts scene components
+ * into Rapier rigid bodies and colliders. A single `Rapier.World` instance is
+ * maintained along with an event queue to capture collision events which are
+ * then mapped back to components. The engine supports mesh-based colliders,
+ * terrain height fields and character controllers, and it can optionally draw
+ * debug lines using `RapierDebugRenderer`.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Instantiate via `createPhysicsEngine` with `PhysicsEngine.Rapier`.
+ * - Call `addComponent` only after a component's mesh or collision shape is
+ *   initialized so colliders are created correctly.
+ * - Enable the debug renderer during development with
+ *   `setDebugRendererEnabled(true)` to visualize physics bodies.
+ * - Prefer simplified or convex meshes when possible to keep performance high.
+ */
+
+import * as RAPIER from '@dimforge/rapier3d-compat';
+import * as THREE from 'three';
+
+import { CollisionMeshType, PhysicsMotionType } from '../../physics/PhysicsTypes.js';
+import { CollisionConfig, getCollisionChannelBit, resolveChannelName } from '../../systems/collision/CollisionConfig.js';
+import { CollisionMode, CollisionResponse, DefaultCollisionProfile } from '../../systems/collision/CollisionTypes.js';
+import { ensure } from '../../utils/Utils.js';
+import { BasePhysicsEngine } from '../BasePhysicsEngine.js';
+import { JointType } from '../BasePhysicsEngine.js';
+import { PhysicsScalarParam, PhysicsVectorParam } from '../PhysicsEngine.js';
+import { CollisionEventType, type RawCollisionEvent } from '../PhysicsEngine.js';
+
+import { RapierDebugRenderer } from './RapierDebugRender.js';
+import { RapierVehicle } from './RapierVehicle.js';
+
+import type { BasePawnMovementComponent } from '../../components/movement/BasePawnMovementComponent.js';
+import type { PrimitiveComponent } from '../../components/PrimitiveComponent.js';
+import type { CollisionProfile} from '../../systems/collision/CollisionTypes.js';
+import type {
+  BaseDesc,
+  BoxBodyDesc,
+  CapsuleBodyDesc,
+  ConeBodyDesc,
+  CylinderBodyDesc,
+  HeightFieldBodyDesc,
+  JointDesc,
+  MeshBodyDesc,
+  SphereBodyDesc,
+  VoxelBodyDesc
+} from '../BasePhysicsEngine';
+import type { IPhysicsVehicle } from '../IPhysicsVehicle.js';
+import type {
+  CharacterControllerOptions,
+  HitTestOptions,
+  HitTestResult,
+  PhysicsOptions,
+  PrimitiveComponentPhysicsState,
+  VectorArray
+} from '../PhysicsEngine';
+import type { PhysicsBodyDesc } from '../PhysicsEngine.js';
+
+/**
+ * Rapier physics engine integration
+ */
+type TRecord = [RAPIER.RigidBody, RAPIER.Collider, PhysicsMotionType];
+type TCharacterControllerRecord = RAPIER.KinematicCharacterController;
+type TJointRecord = RAPIER.ImpulseJoint;
+
+export class RapierPhysicsEngine extends BasePhysicsEngine<TRecord, TCharacterControllerRecord, TJointRecord> {
+
+  private pendingCollisions: RawCollisionEvent[] = [];
+
+  private world: RAPIER.World | null = null;
+
+  private eventQueue: RAPIER.EventQueue | null = null;
+
+  // Map from collider to component for fast lookup during collision processing
+  private colliderToComponent: Map<number, PrimitiveComponent> = new Map();
+
+  // Set of ignored collider pairs (stored as "handle1,handle2" strings)
+  private ignoredColliderPairs: Set<string> = new Set();
+
+  // Debug renderer
+  private debugRenderer: RapierDebugRenderer | null = null;
+
+  // Vehicle controllers
+  private vehicles: Map<BasePawnMovementComponent, RapierVehicle> = new Map();
+
+  // cache for collider desc without scale, mapping from a list of meshes and the collision mesh type
+  private cachedColliderDescTemplates: Map<string, RAPIER.ColliderDesc | null> = new Map();
+
+  private cachedCharacterControllerCollisions: Map<number, number[]> = new Map();
+
+  constructor(gameWorld?: any) {
+    super(gameWorld);
+  }
+
+  public async doCreate(options: PhysicsOptions): Promise<boolean> {
+    await RAPIER.init();
+    this.world = new RAPIER.World(this.makeVector(options.gravity.toArray()));
+    this.eventQueue = new RAPIER.EventQueue(true);
+
+    // Initialize debug renderer if we have a scene to render to
+    if (this.gameWorld && this.gameWorld.scene) {
+      this.debugRenderer = new RapierDebugRenderer(this.gameWorld.scene, this.world);
+      this.debugRenderer.enabled = options.debugVisualization ?? false;
+    }
+
+    return true;
+  }
+
+  protected doDestroy(): boolean {
+    this.cachedCharacterControllerCollisions.clear();
+    this.pendingCollisions = [];
+
+    const world = this.world!;
+
+    // Clean up vehicles
+    this.vehicles.forEach((vehicle, _) => {
+      vehicle.destroy();
+    });
+    this.vehicles.clear();
+
+    // Remove all physics bodies and colliders first
+    this.bodies.forEach((records, _) => {
+      records.forEach(([body, collider]) => {
+        world.removeRigidBody(body);
+        world.removeCollider(collider, false);
+      });
+    });
+    this.bodies.clear();
+
+
+    // Clean up character controllers
+    this.characterControllers.forEach((controller, _) => {
+      world.removeCharacterController(controller);
+    });
+    this.characterControllers.clear();
+
+    // Clean up joints
+    this.joints.forEach((joint, _) => {
+      world.removeImpulseJoint(joint, true);
+    });
+    this.joints.clear();
+
+    // Free the WASM world object
+    world.free();
+    this.world = null;
+
+    if (this.eventQueue) {
+      this.eventQueue.free();
+      this.eventQueue = null;
+    }
+
+    // Clean up debug renderer
+    if (this.debugRenderer) {
+      this.debugRenderer.dispose();
+      this.debugRenderer = null;
+    }
+
+    this.colliderToComponent.clear();
+    this.ignoredColliderPairs.clear();
+    return true;
+  }
+
+  protected doTick(deltaTime: number): void {
+    this.world!.step(this.eventQueue!);
+
+    for (const vehicle of this.vehicles.values()) {
+      vehicle.tick(deltaTime);
+    }
+
+    // Process collision events from Rapier
+    this.eventQueue!.drainCollisionEvents((handle1, handle2, started) => {
+      this.handleRapierCollision(handle1, handle2, started);
+    });
+
+    const objectPosition = new THREE.Vector3();
+    const objectQuat = new THREE.Quaternion();
+
+    // Update all object positions based on physics
+    this.bodies.forEach((records, object) => {
+      records.forEach(([body, _]) => {
+        const motionType = object.getMotionType();
+        if (motionType === PhysicsMotionType.Static) {
+          // static objects cannot be moved by the physics engine
+          // so there's no need to sync its transform back to the scene component
+          return;
+        }
+        const position = body.translation();
+        const rotation = body.rotation();
+
+        objectPosition.x = position.x;
+        objectPosition.y = position.y;
+        objectPosition.z = position.z;
+
+        objectQuat.x = rotation.x;
+        objectQuat.y = rotation.y;
+        objectQuat.z = rotation.z;
+        objectQuat.w = rotation.w;
+
+        object.syncFromPhysics(objectPosition, objectQuat);
+      });
+    });
+
+    // Update debug renderer if available
+    if (this.debugRenderer) {
+      this.debugRenderer.update();
+    }
+  }
+
+  private handleRapierCollision(handle1: number, handle2: number, started: boolean): void {
+    // Check if this collision pair should be ignored
+    const pairKey1 = `${handle1},${handle2}`;
+    const pairKey2 = `${handle2},${handle1}`;
+    if (this.ignoredColliderPairs.has(pairKey1) || this.ignoredColliderPairs.has(pairKey2)) {
+      return; // Ignore this collision
+    }
+
+    const collider1 = this.world!.getCollider(handle1);
+    const collider2 = this.world!.getCollider(handle2);
+
+    if (!collider1 || !collider2) return;
+
+    const componentA = this.colliderToComponent.get(handle1);
+    const componentB = this.colliderToComponent.get(handle2);
+
+    if (!componentA || !componentB) return;
+
+    const contact = collider1.contactCollider(collider2, 0.1);
+    let contactPointA: THREE.Vector3 | null = null;
+    let contactNormalA: THREE.Vector3 | null = null;
+    let contactPointB: THREE.Vector3 | null = null;
+    let contactNormalB: THREE.Vector3 | null = null;
+    if (contact) {
+      contactPointA = new THREE.Vector3(contact.point1.x, contact.point1.y, contact.point1.z);
+      contactNormalA = new THREE.Vector3(contact.normal1.x, contact.normal1.y, contact.normal1.z);
+      contactPointB = new THREE.Vector3(contact.point2.x, contact.point2.y, contact.point2.z);
+      contactNormalB = new THREE.Vector3(contact.normal2.x, contact.normal2.y, contact.normal2.z);
+    }
+
+    // Calculate relative velocity at the contact point
+    const bodyA = collider1.parent();
+    const bodyB = collider2.parent();
+
+    let relativeVelocity: number | null = null;
+    if (bodyA && bodyB) {
+      const velA = bodyA.linvel();
+      const velB = bodyB.linvel();
+      // Calculate squared length manually
+      const dx = velB.x - velA.x;
+      const dy = velB.y - velA.y;
+      const dz = velB.z - velA.z;
+      relativeVelocity = Math.sqrt(dx*dx + dy*dy + dz*dz);
+    }
+
+    // Create collision info
+    const collision: RawCollisionEvent = {
+      componentA,
+      componentB,
+      pointA: contactPointA,
+      normalA: contactNormalA,
+      pointB: contactPointB,
+      normalB: contactNormalB,
+      relativeVelocity,
+      isTriggerEvent: collider1.isSensor() || collider2.isSensor(),
+      eventType: started ? CollisionEventType.Started : CollisionEventType.Ended,
+    };
+
+    this.pendingCollisions.push(collision);
+  }
+
+  protected doCreateBoxBody(desc: BoxBodyDesc): TRecord | null {
+    const colliderDesc = RAPIER.ColliderDesc.cuboid(desc.size.x / 2, desc.size.y / 2, desc.size.z / 2);
+    const record = this.createBody(colliderDesc, desc);
+    return record;
+  }
+
+  private populateVerticesAndIndices(meshes: THREE.Mesh[], populateIndices: boolean = true): {vertices: Float32Array, indices: Uint32Array} {
+    let totalVertexCount = 0;
+    let totalIndexCount = 0;
+    const validMeshes: THREE.Mesh[] = [];
+
+    for (const mesh of meshes) {
+      const geometry = mesh.geometry;
+      if (!geometry.isBufferGeometry) {
+        console.error('Geometry is not a BufferGeometry');
+        continue;
+      }
+
+      const positionAttribute = geometry.getAttribute('position');
+      if (!positionAttribute) {
+        console.error('Geometry has no position attribute');
+        continue;
+      }
+
+      totalVertexCount += positionAttribute.count;
+
+      const indexAttribute = geometry.getIndex();
+      if (indexAttribute) {
+        totalIndexCount += indexAttribute.count;
+      }
+
+      validMeshes.push(mesh);
+    }
+
+    const vertices = new Float32Array(totalVertexCount * 3);
+    const indices = new Uint32Array(populateIndices ? totalIndexCount: 0);
+
+    let vertexOffset = 0;
+    let indexOffset = 0;
+
+    for (const mesh of validMeshes) {
+      const geometry = mesh.geometry;
+      if (indices !== null) {
+        const indexAttribute = geometry.getIndex();
+        if (indexAttribute) {
+          for (let i = 0; i < indexAttribute.count; i++) {
+            indices[indexOffset + i] = indexAttribute.getX(i) + vertexOffset;
+          }
+          indexOffset += indexAttribute.count;
+        }
+      }
+
+      const matrix = mesh.matrixWorld;
+      const positionAttribute = geometry.getAttribute('position');
+      for (let i = 0; i < positionAttribute.count; i++) {
+        // Must apply the mesh's matrix as there can be a transform from the mesh inside gltf
+        const vertex = new THREE.Vector3(
+          positionAttribute.getX(i),
+          positionAttribute.getY(i),
+          positionAttribute.getZ(i)
+        );
+        vertex.applyMatrix4(matrix);
+
+        vertices[(vertexOffset + i) * 3] = vertex.x;
+        vertices[(vertexOffset + i) * 3 + 1] = vertex.y;
+        vertices[(vertexOffset + i) * 3 + 2] = vertex.z;
+      }
+      vertexOffset += positionAttribute.count;
+    }
+
+    return {vertices, indices};
+  }
+
+  private calcBoundingPrimitive<T extends THREE.Box3 | THREE.Sphere>(
+    meshes: THREE.Mesh[],
+    calcBoundingFunc: (geometry: THREE.BufferGeometry) => void,
+    getBoundingFunc: (geometry: THREE.BufferGeometry) => T | null,
+    primitiveType: new () => T
+  ): T {
+    const combined: T = new primitiveType();
+    for (const mesh of meshes) {
+      const geometry = mesh.geometry;
+      {
+        const bounding = getBoundingFunc(geometry);
+        if (!bounding) {
+          calcBoundingFunc(geometry);
+        }
+      }
+
+      const bounding = getBoundingFunc(geometry)!.clone();
+      // The bounding (box/sphere/etc...) is calculated from the geometry with no transforms
+      // its parent node in glb can carry extra transforms, so we need to take that into account
+      bounding.applyMatrix4(mesh.matrixWorld);
+
+      (combined as any).union(bounding);
+    }
+
+    return combined;
+  }
+
+  private makeMeshColliderDescTemplate(meshes: THREE.Mesh[] | null, collisionMeshType: CollisionMeshType = CollisionMeshType.ConvexHull): RAPIER.ColliderDesc | null {
+    if (!meshes || meshes.length === 0) {
+      console.error('No meshes provided to create mesh body');
+      return null;
+    }
+
+    const cacheKey = meshes.map(m => m.id).sort().join(',') + '|' + collisionMeshType;
+    if (this.cachedColliderDescTemplates.has(cacheKey)) {
+      return this.cachedColliderDescTemplates.get(cacheKey)!;
+    }
+
+    let colliderDesc: RAPIER.ColliderDesc | null = null;
+
+    // Use the combined data for collider creation
+    try {
+      // Determine which type of collider to create based on collisionMeshType
+      switch (collisionMeshType) {
+        case CollisionMeshType.Trimesh:
+        {
+          const { vertices, indices } = this.populateVerticesAndIndices(meshes, true);
+          console.log('Create Trimesh collider with', vertices.length, 'vertices', indices.length, 'indices');
+          colliderDesc = RAPIER.ColliderDesc.trimesh(vertices, indices);
+          break;
+        }
+        case CollisionMeshType.ConvexHull:
+        {
+          const { vertices } = this.populateVerticesAndIndices(meshes, false);
+          console.log('Create ConvexHull collider with', vertices.length, 'vertices');
+          colliderDesc = RAPIER.ColliderDesc.convexHull(vertices);
+          break;
+        }
+        case CollisionMeshType.BoundingBox:
+        {
+          const boundingBox = this.calcBoundingPrimitive(
+            meshes,
+            (geometry) => geometry.computeBoundingBox(),
+            (geometry) => geometry.boundingBox,
+            THREE.Box3
+          );
+          const halfExtents = new THREE.Vector3();
+          boundingBox.getSize(halfExtents);
+          halfExtents.multiplyScalar(0.5);
+
+          // Create box collider using the combined bounding box dimensions
+          console.log('Created box collider with half dimensions', halfExtents.x, halfExtents.y, halfExtents.z, 'from', meshes.length, 'meshes');
+          colliderDesc = RAPIER.ColliderDesc.cuboid(halfExtents.x, halfExtents.y, halfExtents.z);
+          const offset = boundingBox.getCenter(new THREE.Vector3());
+          colliderDesc.setTranslation(offset.x, offset.y, offset.z);
+          break;
+        }
+        case CollisionMeshType.BoundingSphere:
+        {
+          const combinedBoundingSphere = this.calcBoundingPrimitive(
+            meshes,
+            (geometry) => geometry.computeBoundingSphere(),
+            (geometry) => geometry.boundingSphere,
+            THREE.Sphere
+          );
+          const radius = combinedBoundingSphere.radius;
+          console.log('Created sphere collider with radius', radius, 'from', meshes.length, 'meshes');
+
+          colliderDesc = RAPIER.ColliderDesc.ball(radius);
+          const offset = combinedBoundingSphere.center;
+          colliderDesc.setTranslation(offset.x, offset.y, offset.z);
+          break;
+        }
+        case CollisionMeshType.Voxels:
+        {
+          // until we support generating voxels from meshes, we expect the user to provide voxel coords and process that in doCreateVoxelBody
+          console.error('Voxel type collision mesh should be handled by doCreateVoxelBody');
+          break;
+        }
+        default:
+          console.error('Invalid collision mesh type:', collisionMeshType);
+          break;
+      }
+    } catch (error) {
+      console.error('Error creating mesh collider:', error);
+    }
+
+    this.cachedColliderDescTemplates.set(cacheKey, colliderDesc);
+
+    return colliderDesc;
+  }
+
+  private scaleMeshColliderDesc(colliderDesc: RAPIER.ColliderDesc | null, scale: THREE.Vector3): RAPIER.ColliderDesc | null {
+    // don't bother for (1, 1, 1) scale
+    if (scale.x === 1 && scale.y === 1 && scale.z === 1) return colliderDesc;
+
+    if (!colliderDesc) return null;
+
+    switch (colliderDesc.shape.type) {
+      case RAPIER.ShapeType.Cuboid: {
+        const halfExtents = (colliderDesc.shape as RAPIER.Cuboid).halfExtents;
+
+        const scaledDesc = RAPIER.ColliderDesc.cuboid(halfExtents.x * scale.x, halfExtents.y * scale.y, halfExtents.z * scale.z);
+        const translation = colliderDesc.translation;
+        scaledDesc.setTranslation(translation.x * scale.x, translation.y * scale.y, translation.z * scale.z);
+        return scaledDesc;
+      }
+      case RAPIER.ShapeType.Ball: {
+        const radius = (colliderDesc.shape as RAPIER.Ball).radius;
+        const scaledDesc = RAPIER.ColliderDesc.ball(radius * Math.max(scale.x, scale.y, scale.z));
+        const translation = colliderDesc.translation;
+        scaledDesc.setTranslation(translation.x * scale.x, translation.y * scale.y, translation.z * scale.z);
+        return scaledDesc;
+      }
+      case RAPIER.ShapeType.TriMesh: {
+        const vertices = (colliderDesc.shape as RAPIER.TriMesh).vertices.map((v, i) => v * (i % 3 === 0 ? scale.x : (i % 3 === 1 ? scale.y : scale.z)));
+        const indices = (colliderDesc.shape as RAPIER.TriMesh).indices;
+        return RAPIER.ColliderDesc.trimesh(vertices, indices);
+      }
+      case RAPIER.ShapeType.ConvexPolyhedron: {
+        const vertices = (colliderDesc.shape as RAPIER.ConvexPolyhedron).vertices.map((v, i) => v * (i % 3 === 0 ? scale.x : (i % 3 === 1 ? scale.y : scale.z)));
+        return RAPIER.ColliderDesc.convexHull(vertices);
+      }
+    }
+
+    console.error(`Unknown collision type: ${colliderDesc.shape.type}`);
+    return colliderDesc;
+  }
+
+  /**
+   * Creates a mesh-based collider using either trimesh, convexMesh, or convexHull
+   * based on the mesh geometry and collisionMeshType option
+   */
+  protected doCreateMeshBody(desc: MeshBodyDesc, worldScale: THREE.Vector3): TRecord | null {
+    const colliderDesc = this.scaleMeshColliderDesc(
+      this.makeMeshColliderDescTemplate(desc.meshes, desc.options.collisionMeshType), worldScale
+    );
+    if (!colliderDesc) {
+      return null;
+    }
+
+    return this.createBody(colliderDesc, desc);
+  }
+
+  protected doCreateMeshBodiesWithTransformOverrides(desc: MeshBodyDesc, transforms: {position?: THREE.Vector3, rotation?: THREE.Quaternion, scale?: THREE.Vector3}[]): TRecord[] {
+    const templateColliderDesc = this.makeMeshColliderDescTemplate(desc.meshes, desc.options.collisionMeshType);
+    if (!templateColliderDesc) {
+      return [];
+    }
+
+    const baseDesc = {
+      motionType: desc.motionType,
+      options: desc.options,
+      worldPos: desc.worldPos,
+      worldQuat: desc.worldQuat,
+      mass: desc.mass,
+    };
+
+    const cachedColliderDesc: Record<string, RAPIER.ColliderDesc | null> = {};
+
+    const records: TRecord[] = [];
+    for (const transform of transforms) {
+      const scale = transform.scale ?? new THREE.Vector3(1, 1, 1);
+      const scaleKey = String(scale.toArray());
+      cachedColliderDesc[scaleKey] ??= this.scaleMeshColliderDesc(templateColliderDesc, scale);
+      const colliderDesc = cachedColliderDesc[scaleKey];
+      if (colliderDesc) {
+        // overwrite the position and rotation
+        baseDesc.worldPos = transform.position ?? new THREE.Vector3(0, 0, 0);
+        baseDesc.worldQuat = transform.rotation ?? new THREE.Quaternion(0, 0, 0, 1);
+        const record = this.createBody(colliderDesc, baseDesc);
+        if (record) {
+          records.push(record);
+        }
+      }
+    }
+
+    return records;
+  }
+
+  protected doCreateVoxelBody(desc: VoxelBodyDesc): TRecord | null {
+    const voxelSize = desc.voxelSize;
+    const voxels = desc.voxels;
+    const colliderDesc = RAPIER.ColliderDesc.voxels(voxels, new RAPIER.Vector3(voxelSize.x, voxelSize.y, voxelSize.z));
+    const offset = desc.offset;
+    if (offset) {
+      colliderDesc.setTranslation(offset.x, offset.y, offset.z);
+    }
+    return this.createBody(colliderDesc, desc);
+  }
+
+  protected doCreateSphereBody(desc: SphereBodyDesc): TRecord | null {
+    const colliderDesc = RAPIER.ColliderDesc.ball(desc.radius);
+    return this.createBody(colliderDesc, desc);
+  }
+
+  protected doCreateCylinderBody(desc: CylinderBodyDesc): TRecord | null {
+    const colliderDesc = RAPIER.ColliderDesc.cylinder(desc.height / 2, desc.radius);
+    return this.createBody(colliderDesc, desc);
+  }
+
+  protected doCreateConeBody(desc: ConeBodyDesc): TRecord | null {
+    const colliderDesc = RAPIER.ColliderDesc.cone(desc.height / 2, desc.radius);
+    return this.createBody(colliderDesc, desc);
+  }
+
+  protected doCreateCapsuleBody(desc: CapsuleBodyDesc): TRecord | null {
+    const colliderDesc = RAPIER.ColliderDesc.capsule(desc.height / 2, desc.radius);
+    return this.createBody(colliderDesc, desc);
+  }
+
+  protected doCreateHeightFieldBody(desc: HeightFieldBodyDesc): TRecord | null {
+    // Transform heightmap data to match RAPIER's format
+    const transformedHeightMap = new Float32Array(desc.heights.length);
+    for (var z = 0; z < desc.depthPixels; z++) {
+      for (var x = 0; x < desc.widthPixels; x++) {
+        const readIndex = z * desc.widthPixels + x;
+        const writeIndex = x * desc.depthPixels + z;
+        transformedHeightMap[writeIndex] = desc.heights[readIndex];
+      }
+    }
+
+    const terrainScale = this.makeVector([
+      desc.width,
+      1,
+      desc.depth
+    ]);
+    const colliderDesc = RAPIER.ColliderDesc.heightfield(desc.widthPixels - 1, desc.depthPixels - 1, transformedHeightMap, terrainScale);
+    return this.createBody(colliderDesc, desc);
+  }
+
+  protected doRemoveComponent(record: TRecord): boolean {
+    const world = this.world!;
+    const collider = record[1];
+    this.colliderToComponent.delete(collider.handle);
+    world.removeRigidBody(record[0]);
+    world.removeCollider(collider, false);
+    return true;
+  }
+
+  protected doUpdateTransform(component: PrimitiveComponent, record: TRecord): void {
+    const body: RAPIER.RigidBody = record[0];
+    const motionType: PhysicsMotionType = record[2];
+    const worldPosition = new THREE.Vector3();
+    const worldQuat = new THREE.Quaternion();
+    component.getWorldPosition(worldPosition);
+    component.getWorldQuaternion(worldQuat);
+    const flags = component.getPhysicsTransformUpdateFlags();
+
+    const newRotation = this.makeRotation(worldQuat.toArray());
+    const newPosition = this.makeVector(worldPosition.toArray());
+    switch (motionType) {
+      case PhysicsMotionType.Static:
+        if (flags.sendPosition) {
+          body.setTranslation(newPosition, true);
+        }
+        if (flags.sendRotation) {
+          body.setRotation(newRotation, true);
+        }
+        break;
+      case PhysicsMotionType.Dynamic:
+        if (flags.sendPosition) {
+          body.setTranslation(newPosition, true);
+        }
+        if (flags.sendRotation) {
+          body.setRotation(newRotation, true);
+        }
+        break;
+      case PhysicsMotionType.KinematicPositionBased:
+        if (flags.sendPosition) {
+          body.setNextKinematicTranslation(newPosition);
+        }
+        if (flags.sendRotation) {
+          body.setNextKinematicRotation(newRotation);
+        }
+        break;
+      case PhysicsMotionType.KinematicVelocityBased:
+        const userData = (body.userData ?? {}) as any;
+        const linearVelocity = userData[PhysicsVectorParam.LinearVelocity] as VectorArray | undefined;
+        const angularVelocity = userData[PhysicsVectorParam.AngularVelocity] as VectorArray | undefined;
+        if (flags.sendPosition && !linearVelocity) {
+          const currentPosition = body.translation();
+          const timestep = this.world!.timestep;
+          const velocity = {
+            x: (newPosition.x - currentPosition.x) / timestep,
+            y: (newPosition.y - currentPosition.y) / timestep,
+            z: (newPosition.z - currentPosition.z) / timestep,
+          };
+          body.setLinvel(velocity, true);
+        }
+        if (flags.sendRotation && !angularVelocity) {
+          const currentRotation = body.rotation();
+          const timestep = this.world!.timestep;
+
+          // Calculate quaternion difference: q_diff = newRotation * currentRotation^-1
+          const qx = newRotation.w * currentRotation.x - newRotation.x * currentRotation.w - newRotation.y * currentRotation.z + newRotation.z * currentRotation.y;
+          const qy = newRotation.w * currentRotation.y + newRotation.x * currentRotation.z - newRotation.y * currentRotation.w - newRotation.z * currentRotation.x;
+          const qz = newRotation.w * currentRotation.z - newRotation.x * currentRotation.y + newRotation.y * currentRotation.x - newRotation.z * currentRotation.w;
+          const qw = newRotation.w * currentRotation.w + newRotation.x * currentRotation.x + newRotation.y * currentRotation.y + newRotation.z * currentRotation.z;
+
+          // Convert quaternion to axis-angle, then to angular velocity
+          const sinHalfAngle = Math.sqrt(qx * qx + qy * qy + qz * qz);
+          const angle = 2 * Math.atan2(sinHalfAngle, qw);
+          const scale = sinHalfAngle > 1e-6 ? angle / sinHalfAngle / timestep : 2 / timestep;
+
+          const velocity = {
+            x: qx * scale,
+            y: qy * scale,
+            z: qz * scale,
+          };
+          body.setAngvel(velocity, true);
+        }
+        break;
+    }
+  }
+
+  protected doGetScalarParam(record: TRecord, param: PhysicsScalarParam): number | null {
+    const body = record[0];
+    switch (param) {
+      case PhysicsScalarParam.LinearDamping:
+        return body.linearDamping();
+      case PhysicsScalarParam.AngularDamping:
+        return body.angularDamping();
+      case PhysicsScalarParam.GravityScale:
+        return body.gravityScale();
+      default:
+        ensure(false);
+    }
+    return null;
+  }
+
+  protected override doSetScalarParam(records: TRecord[], param: PhysicsScalarParam, value: number): boolean {
+    const doTask = (record: TRecord) => {
+      const body = record[0];
+      switch (param) {
+        case PhysicsScalarParam.LinearDamping:
+          body.setLinearDamping(value);
+          return true;
+        case PhysicsScalarParam.AngularDamping:
+          body.setAngularDamping(value);
+          return true;
+        case PhysicsScalarParam.GravityScale:
+          body.setGravityScale(value, true);
+          return true;
+        default:
+          ensure(false);
+      }
+      return false;
+    };
+
+    let result = true;
+    for (const record of records) {
+      result &&= doTask(record);
+    }
+    return result;
+  }
+
+  protected override doGetVectorParam(record: TRecord, param: PhysicsVectorParam): VectorArray | null {
+    const body = record[0];
+    let ret: RAPIER.Vector | null = null;
+    switch (param) {
+      case PhysicsVectorParam.LinearVelocity:
+        ret = body.linvel();
+        break;
+      case PhysicsVectorParam.AngularVelocity:
+        ret = body.angvel();
+        break;
+      default:
+        ensure(false);
+    }
+    return ret ? [ret.x, ret.y, ret.z] : null;
+  }
+
+  protected override doSetVectorParam(record: TRecord, param: PhysicsVectorParam, value: VectorArray): boolean {
+    const body = record[0];
+    body.userData ??= {};
+    (body.userData as any)[param] = value;
+    switch (param) {
+      case PhysicsVectorParam.LinearVelocity:
+        body.setLinvel(this.makeVector(value), true);
+        return true;
+      case PhysicsVectorParam.AngularVelocity:
+        body.setAngvel(this.makeVector(value), true);
+        return true;
+      default:
+        ensure(false);
+    }
+    return false;
+  }
+
+  protected override doClearVectorParam(record: TRecord, param: PhysicsVectorParam): boolean {
+    const body = record[0];
+    body.userData ??= {};
+    (body.userData as any)[param] = undefined;
+    return true;
+  }
+
+  protected override doCreateCharacterController(options: CharacterControllerOptions): TCharacterControllerRecord | null {
+    const world = this.world!;
+    const controller: RAPIER.KinematicCharacterController = world.createCharacterController(options.offset);
+    controller.setUp({ x: 0.0, y: 1.0, z: 0.0 });
+
+    if (options.applyImpulsesToDynamicBodies !== undefined) {
+      controller.setApplyImpulsesToDynamicBodies(options.applyImpulsesToDynamicBodies);
+    }
+    if (options.characterMass !== undefined) {
+      controller.setCharacterMass(options.characterMass);
+    }
+    if (options.slideEnabled !== undefined) {
+      controller.setSlideEnabled(options.slideEnabled);
+    }
+    if (options.maxSlopeClimbAngle !== undefined) {
+      controller.setMaxSlopeClimbAngle(options.maxSlopeClimbAngle);
+    }
+    if (options.minSlopeSlideAngle !== undefined) {
+      controller.setMinSlopeSlideAngle(options.minSlopeSlideAngle);
+    }
+    if (options.snapToGroundDistance !== undefined) {
+      controller.enableSnapToGround(options.snapToGroundDistance);
+    }
+    if (options.autoStepConfig !== undefined) {
+      controller.enableAutostep(options.autoStepConfig.maxHeight, options.autoStepConfig.minWidth, options.autoStepConfig.includeDynamicBodies);
+    }
+
+    return controller;
+  }
+
+  protected override doRemoveCharacterController(record: TCharacterControllerRecord): boolean {
+    const world = this.world!;
+    world.removeCharacterController(record);
+    return true;
+  }
+
+  protected override doComputeCharacterMovement(record: TCharacterControllerRecord, recordToMove: TRecord, movement: VectorArray, ignoreCollision: boolean): { isGrounded: boolean } {
+    // See https://rapier.rs/docs/user_guides/javascript/character_controller
+    const controller = record;
+    const body = recordToMove[0];
+    const collider = recordToMove[1];
+    const motionType = recordToMove[2];
+    controller.computeColliderMovement(
+      collider,
+      this.makeVector(movement),
+      RAPIER.QueryFilterFlags.EXCLUDE_SENSORS,
+      collider.collisionGroups(),
+      ignoreCollision ? (collider: RAPIER.Collider) => { return false; } : undefined
+    );
+    const actualMovement = controller.computedMovement();
+    const bodyPosition = body.translation();
+    bodyPosition.x += actualMovement.x;
+    bodyPosition.y += actualMovement.y;
+    bodyPosition.z += actualMovement.z;
+    switch (motionType) {
+      case PhysicsMotionType.Dynamic:
+        body.setTranslation(bodyPosition, true);
+        break;
+      case PhysicsMotionType.KinematicPositionBased:
+        body.setNextKinematicTranslation(bodyPosition);
+        break;
+      case PhysicsMotionType.KinematicVelocityBased:
+        const timestep = this.world!.timestep;
+        const velocity = {x: actualMovement.x/timestep, y: actualMovement.y/timestep, z: actualMovement.z/timestep};
+        body.setLinvel(velocity, true);
+        break;
+    }
+
+    // Get grounded state from controller
+    let isGrounded = controller.computedGrounded();
+
+    // Workaround for voxel colliders: if controller says not grounded but we had downward movement
+    // and the actual movement was much less than requested (indicating collision), consider grounded
+    if (!isGrounded && movement[1] < 0) {
+      // We intended to move down, check if we were blocked
+      const intendedVertical = movement[1];
+      const actualVertical = actualMovement.y;
+      // If actual movement is significantly less than intended (more than 90% blocked), we hit ground
+      if (Math.abs(actualVertical) < Math.abs(intendedVertical) * 0.1) {
+        isGrounded = true;
+      }
+    }
+
+    const handleA = collider.handle;
+    const numCollisions = controller.numComputedCollisions();
+    const previousCollidedHandles = this.cachedCharacterControllerCollisions.get(handleA) ?? [];
+    const newCollidedHandles: number[] = [];
+    for (let index = 0; index < numCollisions; index++) {
+      const collision: RAPIER.CharacterCollision | null = controller.computedCollision(index);
+      if (collision && collision.collider) {
+        const handleB = collision.collider.handle;
+        newCollidedHandles.push(handleB);
+        if (!previousCollidedHandles.includes(handleB)) {
+          this.handleRapierCollision(handleA, handleB, true);
+        }
+      }
+    }
+    for(const handleB of previousCollidedHandles) {
+      if (!newCollidedHandles.includes(handleB)) {
+        this.handleRapierCollision(handleA, handleB, false);
+      }
+    }
+    this.cachedCharacterControllerCollisions.set(handleA, newCollidedHandles);
+
+    return { isGrounded };
+  }
+
+  public override getComponentState(component: PrimitiveComponent): PrimitiveComponentPhysicsState | null {
+    const records = this.bodies.get(component);
+    if (!records || records.length === 0) {
+      return null;
+    }
+    const record = records[0];
+    return {
+      isTrigger: record[1].isSensor(),
+      motionType: record[2],
+    };
+  }
+
+  //====================================================================================================
+
+  public override getCollisionEvents(): RawCollisionEvent[] {
+    return this.pendingCollisions;
+  }
+
+  public override clearCollisionEvents(): void {
+    this.pendingCollisions = [];
+  }
+
+  /**
+   * Toggles the physics debug renderer visibility
+   * @param enabled Whether the debug renderer should be visible
+   * @returns Whether the debug renderer is now enabled
+   */
+  public override setDebugRendererEnabled(enabled: boolean): boolean {
+    if (this.debugRenderer) {
+      this.debugRenderer.enabled = enabled;
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Checks if the physics debug renderer is enabled
+   * @returns Whether the debug renderer is currently enabled, or false if not available
+   */
+  public override isDebugRendererEnabled(): boolean {
+    return this.debugRenderer?.enabled ?? false;
+  }
+
+  private createBody(colliderDesc: RAPIER.ColliderDesc, desc: BaseDesc): TRecord | null {
+    const world = this.world!;
+
+    const collisionProfileName = desc.options.collisionProfile ?? DefaultCollisionProfile.Default;
+    const collisionConfig = CollisionConfig.getInstance();
+    const collisionProfile = collisionConfig.profiles.find(p => p.name === collisionProfileName);
+
+    const isSensor = collisionProfile?.mode === CollisionMode.QueryOnly;
+
+    // FIXME: Find out what of this should be configured based on the profile instead
+    const rigidBodyDesc = this.createRigidBodyDesc(desc.motionType);
+    rigidBodyDesc.mass = desc.mass;
+    rigidBodyDesc.setCcdEnabled(!!desc.options.enableCCD);
+
+    const generateCollisionEvents = !!desc.options.generateCollisionEvents || isSensor;
+    colliderDesc.setActiveEvents(generateCollisionEvents ? RAPIER.ActiveEvents.COLLISION_EVENTS : RAPIER.ActiveEvents.NONE);
+    if (generateCollisionEvents) {
+      colliderDesc.setActiveCollisionTypes(RAPIER.ActiveCollisionTypes.ALL);
+    }
+
+    const createCollider = (pos: THREE.Vector3, rot: THREE.Quaternion) => {
+      const rigidBody = world.createRigidBody(rigidBodyDesc);
+      rigidBody.setTranslation(this.makeVector(pos.toArray()), true);
+      rigidBody.setRotation(this.makeRotation(rot.toArray()), true);
+      const collider = world.createCollider(colliderDesc, rigidBody);
+      collider.setSensor(isSensor);
+      rigidBody.setGravityScale(desc.options.gravityScale ?? 1, true);
+      if (collisionProfile) {
+        collider.setCollisionGroups(this.getCollisionGroups(collisionProfile));
+      }
+
+      return { rigidBody, collider };
+    };
+
+    const {rigidBody, collider} = createCollider(desc.worldPos, desc.worldQuat);
+    return [rigidBody, collider, desc.motionType];
+  }
+
+  private getCollisionGroups(collisionProfile: CollisionProfile): number {
+    // top 16 bits indicate what channel this object occupies, for now that's always a single channel
+    // bottom 16 bits indicate what channels it can interact with
+    let groups = getCollisionChannelBit(collisionProfile.objectChannel) << 16;
+    collisionProfile.responses.forEach(r => {
+      // need to set the collision group even for overlapping interaction, otherwise collision event will NOT be generated
+      if (r.response !== CollisionResponse.Ignore) {
+        const channelEnum = typeof r.channel === 'string' ? resolveChannelName(r.channel) : r.channel;
+        if (channelEnum !== undefined) {
+          groups |= getCollisionChannelBit(channelEnum);
+        }
+      }
+    });
+    return groups;
+  }
+
+  private createRigidBodyDesc(motionType: PhysicsMotionType): RAPIER.RigidBodyDesc {
+    switch (motionType) {
+      case PhysicsMotionType.Static:
+        return RAPIER.RigidBodyDesc.fixed();
+      case PhysicsMotionType.KinematicVelocityBased:
+        return RAPIER.RigidBodyDesc.kinematicVelocityBased();
+      case PhysicsMotionType.KinematicPositionBased:
+        return RAPIER.RigidBodyDesc.kinematicPositionBased();
+      case PhysicsMotionType.Dynamic:
+        return RAPIER.RigidBodyDesc.dynamic();
+    }
+  }
+
+  private makeVector(v: [number, number, number]): RAPIER.Vector {
+    return {
+      x: v[0],
+      y: v[1],
+      z: v[2],
+    };
+  }
+
+  private makeRotation(r: [number, number, number, number]): RAPIER.Rotation {
+    return {
+      x: r[0],
+      y: r[1],
+      z: r[2],
+      w: r[3],
+    };
+  }
+
+  // Override addComponent to handle collider mapping
+  public override addComponent(component: PrimitiveComponent): PhysicsMotionType | null {
+
+    const motionType = super.addComponent(component);
+    const records = this.bodies.get(component);
+    if (records) {
+      records.forEach((record) => {
+        const collider = record[1];
+        this.colliderToComponent.set(collider.handle, component);
+      });
+    }
+    return motionType;
+  }
+
+  protected override doSetComponentCollisionIgnore(recordA: TRecord, recordB: TRecord, ignore: boolean): boolean {
+    const colliderA = recordA[1];
+    const colliderB = recordB[1];
+    const pairKey = `${colliderA.handle},${colliderB.handle}`;
+
+    if (ignore) {
+      this.ignoredColliderPairs.add(pairKey);
+    } else {
+      this.ignoredColliderPairs.delete(pairKey);
+    }
+
+    return true;
+  }
+
+  protected doCreateJoint(desc: JointDesc, recordA: TRecord, recordB: TRecord): TJointRecord | null {
+    const world = this.world!;
+    const bodyA = recordA[0];
+    const bodyB = recordB[0];
+
+    try {
+      let jointData: RAPIER.JointData;
+
+      switch (desc.type) {
+        case JointType.Spherical:
+          jointData = RAPIER.JointData.spherical(
+            { x: desc.anchorA.x, y: desc.anchorA.y, z: desc.anchorA.z },
+            { x: desc.anchorB.x, y: desc.anchorB.y, z: desc.anchorB.z }
+          );
+          break;
+
+        case JointType.Fixed:
+          jointData = RAPIER.JointData.fixed(
+            { x: desc.anchorA.x, y: desc.anchorA.y, z: desc.anchorA.z },
+            { x: 0, y: 0, z: 0, w: 1 }, // Identity quaternion for now
+            { x: desc.anchorB.x, y: desc.anchorB.y, z: desc.anchorB.z },
+            { x: 0, y: 0, z: 0, w: 1 }  // Identity quaternion for now
+          );
+          break;
+
+        case JointType.Revolute:
+          if (!desc.axis) {
+            console.error('Revolute joint requires an axis');
+            return null;
+          }
+          jointData = RAPIER.JointData.revolute(
+            { x: desc.anchorA.x, y: desc.anchorA.y, z: desc.anchorA.z },
+            { x: desc.anchorB.x, y: desc.anchorB.y, z: desc.anchorB.z },
+            { x: desc.axis.x, y: desc.axis.y, z: desc.axis.z }
+          );
+          break;
+
+        case JointType.Prismatic:
+          if (!desc.axis) {
+            console.error('Prismatic joint requires an axis');
+            return null;
+          }
+          jointData = RAPIER.JointData.prismatic(
+            { x: desc.anchorA.x, y: desc.anchorA.y, z: desc.anchorA.z },
+            { x: desc.anchorB.x, y: desc.anchorB.y, z: desc.anchorB.z },
+            { x: desc.axis.x, y: desc.axis.y, z: desc.axis.z }
+          );
+          break;
+
+        default:
+          console.error('Unsupported joint type:', desc.type);
+          return null;
+      }
+
+      const joint = world.createImpulseJoint(jointData, bodyA, bodyB, true);
+      return joint;
+    } catch (error) {
+      console.error('Failed to create joint:', error);
+      return null;
+    }
+  }
+
+  protected doRemoveJoint(jointRecord: TJointRecord): boolean {
+    const world = this.world!;
+    try {
+      world.removeImpulseJoint(jointRecord, true);
+      return true;
+    } catch (error) {
+      console.error('Failed to remove joint:', error);
+      return false;
+    }
+  }
+
+  protected doCreateJointFromRecords(
+    type: JointType,
+    recordA: TRecord,
+    recordB: TRecord,
+    anchorA: THREE.Vector3,
+    anchorB: THREE.Vector3,
+    axis?: THREE.Vector3
+  ): TJointRecord | null {
+    const world = this.world!;
+    const bodyA = recordA[0];
+    const bodyB = recordB[0];
+
+    try {
+      let jointData: RAPIER.JointData;
+
+      switch (type) {
+        case JointType.Spherical:
+          jointData = RAPIER.JointData.spherical(
+            { x: anchorA.x, y: anchorA.y, z: anchorA.z },
+            { x: anchorB.x, y: anchorB.y, z: anchorB.z }
+          );
+          break;
+
+        case JointType.Fixed:
+          jointData = RAPIER.JointData.fixed(
+            { x: anchorA.x, y: anchorA.y, z: anchorA.z },
+            { x: 0, y: 0, z: 0, w: 1 }, // Identity quaternion for now
+            { x: anchorB.x, y: anchorB.y, z: anchorB.z },
+            { x: 0, y: 0, z: 0, w: 1 }  // Identity quaternion for now
+          );
+          break;
+
+        case JointType.Revolute:
+          if (!axis) {
+            console.error('Revolute joint requires an axis');
+            return null;
+          }
+          jointData = RAPIER.JointData.revolute(
+            { x: anchorA.x, y: anchorA.y, z: anchorA.z },
+            { x: anchorB.x, y: anchorB.y, z: anchorB.z },
+            { x: axis.x, y: axis.y, z: axis.z }
+          );
+          break;
+
+        case JointType.Prismatic:
+          if (!axis) {
+            console.error('Prismatic joint requires an axis');
+            return null;
+          }
+          jointData = RAPIER.JointData.prismatic(
+            { x: anchorA.x, y: anchorA.y, z: anchorA.z },
+            { x: anchorB.x, y: anchorB.y, z: anchorB.z },
+            { x: axis.x, y: axis.y, z: axis.z }
+          );
+          break;
+
+        default:
+          console.error('Unsupported joint type:', type);
+          return null;
+      }
+
+      const joint = world.createImpulseJoint(jointData, bodyA, bodyB, true);
+      return joint;
+    } catch (error) {
+      console.error('Failed to create joint from records:', error);
+      return null;
+    }
+  }
+
+  // Direct physics body management implementations
+
+  protected doCreateDirectBody(desc: PhysicsBodyDesc): TRecord | null {
+    const world = this.world!;
+
+    try {
+      // Create collider based on shape type
+      let colliderDesc: RAPIER.ColliderDesc;
+
+      switch (desc.shape.type) {
+        case 'box':
+          const size = desc.shape.size!;
+          colliderDesc = RAPIER.ColliderDesc.cuboid(
+            size.x / 2,
+            size.y / 2,
+            size.z / 2
+          );
+          break;
+        case 'sphere':
+          colliderDesc = RAPIER.ColliderDesc.ball(desc.shape.radius!);
+          break;
+        case 'cylinder':
+          colliderDesc = RAPIER.ColliderDesc.cylinder(desc.shape.height! / 2, desc.shape.radius!);
+          break;
+        case 'capsule':
+          colliderDesc = RAPIER.ColliderDesc.capsule(desc.shape.height! / 2, desc.shape.radius!);
+          break;
+        default:
+          console.error(`Unsupported shape type: ${desc.shape.type}`);
+          return null;
+      }
+
+      // Create rigid body
+      let rigidBodyDesc: RAPIER.RigidBodyDesc;
+
+      switch (desc.motionType) {
+        case PhysicsMotionType.Static:
+          rigidBodyDesc = RAPIER.RigidBodyDesc.fixed();
+          break;
+        case PhysicsMotionType.KinematicPositionBased:
+          rigidBodyDesc = RAPIER.RigidBodyDesc.kinematicPositionBased();
+          break;
+        case PhysicsMotionType.KinematicVelocityBased:
+          rigidBodyDesc = RAPIER.RigidBodyDesc.kinematicVelocityBased();
+          break;
+        case PhysicsMotionType.Dynamic:
+        default:
+          rigidBodyDesc = RAPIER.RigidBodyDesc.dynamic();
+          break;
+      }
+
+      rigidBodyDesc
+        .setTranslation(desc.position.x, desc.position.y, desc.position.z)
+        .setRotation({ x: desc.rotation.x, y: desc.rotation.y, z: desc.rotation.z, w: desc.rotation.w });
+
+      const rigidBody = world.createRigidBody(rigidBodyDesc);
+      const collider = world.createCollider(colliderDesc, rigidBody);
+
+      // Set mass for dynamic bodies
+      if (desc.motionType === PhysicsMotionType.Dynamic && desc.mass > 0) {
+        collider.setMass(desc.mass);
+      }
+
+      // Set enabled state
+      if (desc.enabled !== undefined) {
+        rigidBody.setEnabled(desc.enabled);
+      }
+
+      return [rigidBody, collider, desc.motionType];
+    } catch (error) {
+      console.error('Failed to create direct physics body:', error);
+      return null;
+    }
+  }
+
+  protected doRemoveDirectBody(record: TRecord): boolean {
+    const world = this.world!;
+    const [rigidBody, collider] = record;
+
+    try {
+      world.removeRigidBody(rigidBody);
+      world.removeCollider(collider, false);
+      return true;
+    } catch (error) {
+      console.error('Failed to remove direct physics body:', error);
+      return false;
+    }
+  }
+
+  protected doGetBodyPosition(record: TRecord): THREE.Vector3 | null {
+    const [rigidBody] = record;
+
+    try {
+      const translation = rigidBody.translation();
+      return new THREE.Vector3(translation.x, translation.y, translation.z);
+    } catch (error) {
+      console.error('Failed to get body position:', error);
+      return null;
+    }
+  }
+
+  protected doGetBodyRotation(record: TRecord): THREE.Quaternion | null {
+    const [rigidBody] = record;
+
+    try {
+      const rotation = rigidBody.rotation();
+      return new THREE.Quaternion(rotation.x, rotation.y, rotation.z, rotation.w);
+    } catch (error) {
+      console.error('Failed to get body rotation:', error);
+      return null;
+    }
+  }
+
+  protected doSetBodyPosition(record: TRecord, position: THREE.Vector3): boolean {
+    const [rigidBody] = record;
+
+    try {
+      rigidBody.setTranslation({ x: position.x, y: position.y, z: position.z }, true);
+      return true;
+    } catch (error) {
+      console.error('Failed to set body position:', error);
+      return false;
+    }
+  }
+
+  protected doSetBodyRotation(record: TRecord, rotation: THREE.Quaternion): boolean {
+    const [rigidBody] = record;
+
+    try {
+      rigidBody.setRotation({ x: rotation.x, y: rotation.y, z: rotation.z, w: rotation.w }, true);
+      return true;
+    } catch (error) {
+      console.error('Failed to set body rotation:', error);
+      return false;
+    }
+  }
+
+  protected doApplyBodyImpulse(record: TRecord, impulse: THREE.Vector3, worldSpace: boolean): boolean {
+    const [rigidBody] = record;
+
+    try {
+      rigidBody.applyImpulse({ x: impulse.x, y: impulse.y, z: impulse.z }, worldSpace);
+      return true;
+    } catch (error) {
+      console.error('Failed to apply body impulse:', error);
+      return false;
+    }
+  }
+
+  protected doSetBodyEnabled(record: TRecord, enabled: boolean): boolean {
+    const [rigidBody] = record;
+
+    try {
+      rigidBody.setEnabled(enabled);
+      return true;
+    } catch (error) {
+      console.error('Failed to set body enabled state:', error);
+      return false;
+    }
+  }
+
+  private buildHitTestResult(origin: THREE.Vector3, direction: THREE.Vector3, intersection: RAPIER.RayColliderIntersection): HitTestResult {
+    const hitComponent = this.colliderToComponent.get(intersection.collider.handle) ?? null;
+    return {
+      origin: origin,
+      direction: direction,
+      hitLocation: origin.clone().add(direction.clone().multiplyScalar(intersection.timeOfImpact)),
+      hitNormal: new THREE.Vector3(intersection.normal.x, intersection.normal.y, intersection.normal.z),
+      hitComponent: hitComponent,
+      hitActor: hitComponent?.getActor() ?? null,
+    };
+  }
+
+  public override performHitTest(options: HitTestOptions): HitTestResult[] {
+    const world = this.world!;
+    const ray = new RAPIER.Ray(
+      { x: options.origin.x, y: options.origin.y, z: options.origin.z },
+      { x: options.direction.x, y: options.direction.y, z: options.direction.z }
+    );
+
+    const groups = options.collisionProfile ? this.getCollisionGroups(options.collisionProfile) : undefined;
+
+    const filterPredicate = (collider: RAPIER.Collider) => {
+      if (options.ignoredActors || options.ignoredComponents) {
+        const component = this.colliderToComponent.get(collider.handle);
+        if (!component) {
+          return false;
+        }
+        if (options.ignoredActors && options.ignoredActors.includes(component.getActor()!)) {
+          return false;
+        }
+        if (options.ignoredComponents && options.ignoredComponents.includes(component)) {
+          return false;
+        }
+      }
+      return true;
+    };
+
+    const results: HitTestResult[] = [];
+
+    if (options.stopOnFirstHit) {
+      const intersection = world.castRayAndGetNormal(ray, options.maxDistance, true, RAPIER.QueryFilterFlags.EXCLUDE_SENSORS, groups, undefined, undefined, filterPredicate);
+      if (intersection) {
+        results.push(this.buildHitTestResult(options.origin, options.direction, intersection));
+      }
+    } else {
+      world.intersectionsWithRay(ray, options.maxDistance, true, (intersect: RAPIER.RayColliderIntersection) => {
+        results.push(this.buildHitTestResult(options.origin, options.direction, intersect));
+        return true;
+      }, RAPIER.QueryFilterFlags.EXCLUDE_SENSORS, groups, undefined, undefined, filterPredicate);
+    }
+
+    return results;
+  }
+
+  // Vehicle controller implementation
+
+  public override createVehicle(movementComponent: BasePawnMovementComponent, chassisComponent: PrimitiveComponent): IPhysicsVehicle | null {
+    if (!this.world) return null;
+
+    // Get the chassis physics record
+    const chassisRecords = this.bodies.get(chassisComponent);
+    if (!chassisRecords || chassisRecords.length !== 1) {
+      console.error('VehicleController: Chassis component not found in physics simulation');
+      return null;
+    }
+
+    if (this.vehicles.has(movementComponent)) {
+      console.error('VehicleController: Vehicle controller already exists for component:', movementComponent.getPathName());
+      return null;
+    }
+
+    try {
+      // Create the vehicle controller using Rapier's DynamicRayCastVehicleController
+      const chassisRecord = chassisRecords[0];
+      const chassisBody = chassisRecord[0];
+
+      // Create and return the physics vehicle interface
+      const vehicle = new RapierVehicle({
+        world: this.world,
+        chassis: chassisBody,
+      });
+
+      // Store the record for cleanup purposes
+      this.vehicles.set(movementComponent, vehicle);
+
+      console.log('VehicleController: Created vehicle controller for component:', movementComponent.getPathName());
+      return vehicle;
+    } catch (error) {
+      console.error('VehicleController: Failed to create vehicle controller:', error);
+      return null;
+    }
+  }
+}