@directivegames/genesys.js 3.1.24

package/src/physics/BasePhysicsEngine.ts

@@ -0,0 +1,1486 @@
+/**
+ * BasePhysicsEngine supplies reusable logic for multiple physics backends.
+ *
+ * This class manages the collection of physics bodies associated with scene
+ * components and dispatches collision events back into Genesys. It defines a
+ * number of abstract `do*` methods which concrete engines implement to hook
+ * into their specific library. The engine also handles mesh simplification,
+ * terrain height field generation and character controller creation so derived
+ * classes only deal with low level data conversions.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Extend this class when adding support for a new physics library to inherit
+ *   consistent scene integration and body lifecycle handling.
+ * - Call `create` with `PhysicsOptions` to initialize and then `tick` each
+ *   frame to step the simulation.
+ * - Override methods like `doCreateBoxBody` or `doSetVectorParam` to translate
+ *   requests into library-specific calls.
+ * - Use `addComponent` to automatically determine body types from component
+ *   geometry or collision shapes.
+ */
+
+import * as THREE from 'three';
+
+import { CollisionShapeComponent, CollisionShapeType } from '../components/CollisionShapeComponent.js';
+import { PrimitiveComponent } from '../components/PrimitiveComponent.js';
+import { GLTFMeshComponent } from '../components/visual/GLTFMeshComponent.js';
+import { InstancedGltfMeshComponent } from '../components/visual/InstancedGltfMeshComponent.js';
+import { InstancedMeshComponent } from '../components/visual/InstancedMeshComponent.js';
+import { MeshComponent } from '../components/visual/MeshComponent.js';
+import { TerrainMeshComponent } from '../components/visual/TerrainMeshComponent.js';
+import { CollisionConfig } from '../systems/collision/CollisionConfig.js';
+import { CollisionMode } from '../systems/collision/CollisionTypes.js';
+import { ConsoleCommand } from '../systems/ConsoleManager.js';
+import { ensure } from '../utils/Utils.js';
+
+
+import { CollisionEventType } from './PhysicsEngine.js';
+import { CollisionMeshType, PhysicsMotionType } from './PhysicsTypes.js';
+
+import type { IPhysicsVehicle } from './IPhysicsVehicle.js';
+import type { PhysicsBodyDesc } from './PhysicsEngine.js';
+import type {
+  CharacterControllerOptions,
+  CollisionEvent,
+  HitTestOptions,
+  HitTestResult,
+  IPhysicsEngine,
+  PhysicsOptions,
+  PhysicsScalarParam,
+  PhysicsVectorParam,
+  PrimitiveComponentPhysicsState,
+  RawCollisionEvent,
+  VectorArray
+} from './PhysicsEngine.js';
+import type { ComponentPhysicsOptions, VoxelCollisionDesc } from './PhysicsTypes.js';
+import type { BasePawnMovementComponent } from '../components/movement/BasePawnMovementComponent.js';
+import type { SceneComponent } from '../components/SceneComponent.js';
+
+
+export type BaseDesc = {
+    motionType: PhysicsMotionType,
+    options: ComponentPhysicsOptions,
+    worldPos: THREE.Vector3,
+    worldQuat: THREE.Quaternion,
+    mass: number,
+}
+
+export type BoxBodyDesc = BaseDesc & {
+    size: THREE.Vector3,
+}
+
+export type MeshBodyDesc = BaseDesc & {
+    meshes: THREE.Mesh[],
+}
+
+export type VoxelBodyDesc = BaseDesc & {
+  voxelSize: THREE.Vector3,
+  offset?: THREE.Vector3,
+  voxels: Float32Array | Int32Array
+}
+
+export type SphereBodyDesc = BaseDesc & {
+    center: THREE.Vector3,
+    radius: number,
+}
+
+export type CylinderBodyDesc = BaseDesc & {
+    height: number,
+    radius: number,
+}
+
+export type CapsuleBodyDesc = BaseDesc & {
+    height: number,
+    radius: number,
+}
+
+export type ConeBodyDesc = BaseDesc & {
+    height: number,
+    radius: number,
+}
+
+export type HeightFieldBodyDesc = BaseDesc & {
+    width: number,
+    depth: number,
+    widthPixels: number,
+    depthPixels: number,
+    heights: Float32Array,
+}
+
+export enum JointType {
+    Spherical = 'spherical',
+    Fixed = 'fixed',
+    Revolute = 'revolute',
+    Prismatic = 'prismatic'
+}
+
+export interface JointDesc {
+    type: JointType;
+    componentA: PrimitiveComponent;
+    componentB: PrimitiveComponent;
+    anchorA: THREE.Vector3;
+    anchorB: THREE.Vector3;
+    axis?: THREE.Vector3; // For revolute/prismatic joints
+}
+
+export abstract class BasePhysicsEngine<TRecord, TCharacterControllerRecord, TJointRecord = any> implements IPhysicsEngine {
+  protected initialized: boolean = false;
+  protected bodies: Map<PrimitiveComponent, TRecord[]> = new Map();
+  protected characterControllers: Map<BasePawnMovementComponent, TCharacterControllerRecord> = new Map();
+  protected joints: Map<string, TJointRecord> = new Map(); // Using string ID as key
+  protected directBodies: Map<string, TRecord> = new Map(); // Direct physics bodies by handle
+  protected options: PhysicsOptions | null = null;
+  private nextJointId: number = 0;
+  private nextBodyId: number = 0;
+
+  // Reference to the game world that owns this physics engine
+  protected gameWorld: any;
+
+  protected physicMeshesCache: Map<number, THREE.Mesh[]> = new Map();
+
+  constructor(gameWorld?: any) {
+    this.gameWorld = gameWorld;
+    if (gameWorld) {
+      gameWorld?.consoleManager.addCommandHandler(this);
+    }
+  }
+
+  public performHitTest(options: HitTestOptions): HitTestResult[] {
+    return []; // Override in derived class
+  }
+
+  @ConsoleCommand('debugphysics', 'Enable/disable physics debug visualization (usage: debugphysics <true | false>)')
+  private debugPhysics(enable: string = ''): string {
+    // Use truthy value to enable debug visualization
+    if (enable === 'true' || enable === '1') {
+      this.setDebugRendererEnabled(true);
+    } else {
+      this.setDebugRendererEnabled(false);
+    }
+    return 'Debug physics ' + (this.isDebugRendererEnabled() ? 'enabled' : 'disabled');
+  }
+
+
+  /**
+     * Initializes the physics engine with the specified options
+     * @param options Physics engine configuration options
+     * @returns Promise that resolves to true if initialization was successful
+     */
+  public async create(options: PhysicsOptions): Promise<boolean> {
+    if (!ensure(!this.initialized)) {
+      return false;
+    }
+    this.initialized = await this.doCreate(options);
+    this.options = options;
+    return this.initialized;
+  }
+
+  /**
+     * Get the physics engine options
+     * @returns Physics engine options
+     */
+  public getOptions(): PhysicsOptions | null {
+    return this.options;
+  }
+
+  /**
+     * Destroys the physics engine and cleans up resources
+     */
+  public destroy(): void {
+    if (!this.initialized) {
+      return;
+    }
+
+    // Clean up all joints before destroying the physics world
+    for (const [jointId, jointRecord] of this.joints) {
+      this.doRemoveJoint(jointRecord);
+    }
+    this.joints.clear();
+
+    // Clean up all direct physics bodies
+    for (const [handle, record] of this.directBodies) {
+      this.doRemoveDirectBody(record);
+    }
+    this.directBodies.clear();
+
+    if (this.doDestroy()) {
+      this.initialized = false;
+    }
+
+    if (this.gameWorld) {
+      this.gameWorld?.consoleManager.removeCommandHandler(this);
+    }
+  }
+
+  /**
+     * Updates the physics simulation by one time step
+     * @param deltaTime Time elapsed since last tick in seconds
+     */
+  public tick(deltaTime: number): void {
+    if (!this.initialized) {
+      return;
+    }
+
+    // update component transform to the physics just before ticking
+    for (const component of this.bodies.keys()) {
+      component.syncToPhysics(this);
+    }
+
+    this.doTick(deltaTime);
+    this.processCollisionEvents();
+  }
+
+  private cloneMesh(originalMesh: THREE.Mesh): THREE.Mesh {
+    const clonedMesh = new THREE.Mesh(
+      originalMesh.geometry.clone(),
+      originalMesh.material
+    );
+    return clonedMesh;
+  }
+
+  /**
+   * Processes a GLTF model to extract physics meshes with proper scaling and transforms
+   * @param model The GLTF scene model
+   * @returns Array of processed physics meshes. The meshes are always meshes at Identity, i.e. sitting at origin, no rotation, no scale
+   */
+  private processGLTFModelForPhysics(model: THREE.Object3D): THREE.Mesh[] {
+    // Collect all physics meshes
+    const physicsMeshes: THREE.Mesh[] = [];
+
+    // we're now using the model template, so that means it is sitting at Identity, and we don't need to do any transforms to it.
+    // of course, while this saves the copy, we are expecting they NEVER get modified
+    model.traverse((object) => {
+      if (object instanceof THREE.Mesh) {
+        physicsMeshes.push(object);
+      }
+    });
+
+    return physicsMeshes;
+
+    // // alternative way is to clone all meshes, and apply the local to root transform to each mesh
+    // const worldToRootMatrix = model.matrixWorld.clone().invert();
+
+    // // Process all meshes in the cloned model
+    // model.traverse((object) => {
+    //   if (object instanceof THREE.Mesh) {
+    //     const physicsMesh = this.cloneMesh(object);
+
+    //     physicsMesh.matrixAutoUpdate = false;
+    //     // object local to world -> object local to root -> physics mesh is placed at Identity, so an extra `premultiply(Identity);` is omitted
+    //     const matrix = object.matrixWorld.clone().premultiply(worldToRootMatrix);
+    //     physicsMesh.matrix.copy(matrix);
+    //     physicsMesh.updateMatrixWorld(true);
+
+    //     physicsMeshes.push(physicsMesh);
+    //   }
+    // });
+
+    // // caching in this.physicMeshesCache
+
+    // return physicsMeshes;
+  }
+
+  /**
+   * Processes a model to extract physics mesh with proper scaling and transforms
+   * @param model The scene model
+   * @param worldScale The world scale to apply
+   * @returns Array of processed physics meshes. The meshes are always meshes at Identity, i.e. sitting at origin, no rotation, no scale
+   */
+  private processModelForPhysics(mesh: THREE.Mesh): THREE.Mesh {
+    const cacheKey = mesh.id;
+    if (this.physicMeshesCache.has(cacheKey)) {
+      return this.physicMeshesCache.get(cacheKey)![0];
+    }
+
+    const physicsMesh = this.cloneMesh(mesh);
+    physicsMesh.matrixAutoUpdate = false;
+    physicsMesh.matrix.copy(new THREE.Matrix4());
+    physicsMesh.updateMatrixWorld(true);
+
+    // cache it so we have the same physicsMesh always, which is good for cache of collider desc
+    this.physicMeshesCache.set(cacheKey, [physicsMesh]);
+
+    return physicsMesh;
+  }
+
+  /**
+     * Adds a scene component to the physics simulation
+     * @param component The scene component to add
+     * @returns The motion type assigned to the component, or null if addition failed
+     */
+  public addComponent(component: PrimitiveComponent): PhysicsMotionType | null {
+    if (!ensure(this.initialized)) {
+      return null;
+    }
+
+    if (!ensure(!this.bodies.has(component))) {
+      return null;
+    }
+
+    const physicsOptions = component.getPhysicsOptions();
+
+    const collisionConfig = CollisionConfig.getInstance();
+    const collisionProfile = collisionConfig.profiles.find(profile => profile.name === physicsOptions?.collisionProfile);
+    if (collisionProfile?.mode === CollisionMode.NoCollision) {
+      return null;
+    }
+
+    // FIXME: deprecate? Or should it be a combination of enabled and collisionProfile?
+    if (!physicsOptions?.enabled) {
+      return null;
+    }
+
+    let motionType: PhysicsMotionType | null = null;
+    const worldPos = new THREE.Vector3();
+    const worldQuat = new THREE.Quaternion();
+    const worldScale = new THREE.Vector3();
+    component.getWorldPosition(worldPos);
+    component.getWorldQuaternion(worldQuat);
+    component.getWorldScale(worldScale);
+
+    let records: TRecord[] = [];
+    let record: TRecord | null = null;
+    if (component instanceof(MeshComponent)) {
+      [record, motionType] = this.createMeshComponentRecord(component, physicsOptions, worldPos, worldQuat, worldScale);
+    } else if (component instanceof(CollisionShapeComponent)) {
+      [record, motionType] = this.createCollisionShapeRecord(component, physicsOptions, worldPos, worldQuat, worldScale);
+    } else if (component instanceof(TerrainMeshComponent)) {
+      [record, motionType] = this.createTerrainMeshRecord(component, physicsOptions, worldPos, worldQuat, worldScale);
+    } else if (component instanceof(GLTFMeshComponent)) {
+      [record, motionType] = this.createGLTFMeshRecord(component, physicsOptions, worldPos, worldQuat, worldScale);
+    }
+
+    if (record) {
+      records.push(record);
+    }
+
+    if (component instanceof(InstancedGltfMeshComponent)) {
+      [records, motionType] = this.createInstancedGltfMeshRecord(component, physicsOptions, worldPos, worldQuat);
+    } else if (component instanceof(InstancedMeshComponent)) {
+      [records, motionType] = this.createInstancedMeshRecord(component, physicsOptions, worldPos, worldQuat, worldScale);
+    }
+
+    if (records.length > 0) {
+      this.bodies.set(component, records);
+    }
+    return motionType;
+  }
+
+  /**
+   * Creates a physics record for a MeshComponent
+   * @param component The mesh component
+   * @param physicsOptions The physics options
+   * @param worldPos The world position
+   * @param worldQuat The world quaternion
+   * @param worldScale The world scale
+   * @returns [record, motionType] tuple
+   */
+  protected createMeshComponentRecord(
+    component: MeshComponent,
+    physicsOptions: ComponentPhysicsOptions | undefined,
+    worldPos: THREE.Vector3,
+    worldQuat: THREE.Quaternion,
+    worldScale: THREE.Vector3,
+  ): [TRecord | null, PhysicsMotionType | null] {
+    const mesh = component.getMesh();
+    if (!mesh) {
+      return [null, null];
+    }
+
+    const [records, motionType] = this.createMeshRecord(mesh, physicsOptions, [{worldPos, worldQuat, worldScale}], component);
+    return [records.length > 0 ? records[0] : null, motionType];
+  }
+
+  /**
+   *
+   * @param mesh
+   * @param physicsOptions
+   * @param worldTransforms Array of world position, rotation, scale for each instance,
+   *                        NOTE: for voxels, it creates the voxels collision using the collisionData.voxels per transform.
+   *                        so be aware, most likely you only need to pass the component's transform
+   * @param context Optional context object for logging
+   * @returns
+   */
+  private createMeshRecord(
+    mesh: THREE.Mesh,
+    physicsOptions: ComponentPhysicsOptions | undefined,
+    worldTransforms: {worldPos: THREE.Vector3, worldQuat: THREE.Quaternion, worldScale: THREE.Vector3}[],
+    context?: any
+  ): [(TRecord | null)[], PhysicsMotionType | null] {
+    const records: (TRecord | null)[] = [];
+    const motionType = physicsOptions?.motionType ?? PhysicsMotionType.Dynamic;
+
+    const geometry = mesh.geometry;
+    if (geometry instanceof(THREE.SphereGeometry) || geometry instanceof(THREE.DodecahedronGeometry) || geometry instanceof(THREE.IcosahedronGeometry)) {
+      // sphere
+      geometry.computeBoundingSphere();
+      for (const {worldPos, worldQuat, worldScale} of worldTransforms) {
+      // Apply world scale to radius
+        const scaleFactor = Math.max(worldScale.x, worldScale.y, worldScale.z);
+        const scaledRadius = geometry.boundingSphere!.radius * scaleFactor;
+        const record = this.doCreateSphereBody({
+          motionType,
+          options: physicsOptions!,
+          worldPos,
+          worldQuat,
+          mass: this.calculateSphereMass(scaledRadius, physicsOptions?.density),
+          center: geometry.boundingSphere!.center,
+          radius: scaledRadius,
+        });
+        records.push(record);
+      }
+    } else if (geometry instanceof(THREE.CapsuleGeometry)) {
+      const capsuleParams = (geometry as THREE.CapsuleGeometry).parameters;
+      for (const {worldPos, worldQuat, worldScale} of worldTransforms) {
+      // Apply world scale
+        const height = capsuleParams.height * worldScale.y;
+        const radius = capsuleParams.radius * Math.max(worldScale.x, worldScale.z);
+        const record = this.doCreateCapsuleBody({
+          motionType,
+          options: physicsOptions!,
+          worldPos,
+          worldQuat,
+          mass: this.calculateCapsuleMass(height, radius, physicsOptions?.density),
+          height,
+          radius,
+        });
+        records.push(record);
+      }
+    } else if (geometry instanceof(THREE.ConeGeometry)) {
+      const coneParams = (geometry as THREE.ConeGeometry).parameters;
+      for (const {worldPos, worldQuat, worldScale} of worldTransforms) {
+      // Apply world scale
+        const height = coneParams.height * worldScale.y;
+        const radius = coneParams.radius * Math.max(worldScale.x, worldScale.z);
+        const record = this.doCreateConeBody({
+          motionType,
+          options: physicsOptions!,
+          worldPos,
+          worldQuat,
+          mass: this.calculateConeMass(height, radius, physicsOptions?.density),
+          height,
+          radius,
+        });
+        records.push(record);
+      }
+    } else if (geometry instanceof(THREE.CylinderGeometry)) {
+      const cylinderParams = (geometry as THREE.CylinderGeometry).parameters;
+      for (const {worldPos, worldQuat, worldScale} of worldTransforms) {
+      // Apply world scale
+        const height = cylinderParams.height * worldScale.y;
+        const radius = (cylinderParams.radiusTop + cylinderParams.radiusBottom) / 2 * Math.max(worldScale.x, worldScale.z);
+        const record = this.doCreateCylinderBody({
+          motionType,
+          options: physicsOptions!,
+          worldPos,
+          worldQuat,
+          mass: this.calculateCylinderMass(height, radius, physicsOptions?.density),
+          height,
+          radius,
+        });
+        records.push(record);
+      }
+    } else if (physicsOptions?.collisionMeshType) {
+      // Use mesh collider for arbitrary geometry when collisionMeshType is specified
+      console.log('Using mesh collider for', context, 'with type', physicsOptions.collisionMeshType);
+
+      const isVoxelsCollision = physicsOptions.collisionMeshType === CollisionMeshType.Voxels;
+      if (isVoxelsCollision) {
+        const voxelsCollisionDesc: VoxelCollisionDesc | undefined = physicsOptions.collisionData?.voxels;
+        if (!voxelsCollisionDesc) {
+          console.log('No voxel collision data provided, using default single voxel at origin. Either provide collisionData.voxels in constructor, or use `overridePhysicsOptions`/`replacePhysicsOptions` to set it later.');
+        }
+
+        if (worldTransforms.length > 1) {
+          console.warn('Multiple transforms provided for voxel mesh collision, each transform will create a full voxel body based on `collisionData.voxels`.');
+        }
+
+        for (const {worldPos, worldQuat, worldScale} of worldTransforms) {
+          const voxelSize = voxelsCollisionDesc?.voxelSize ?? new THREE.Vector3(1, 1, 1);
+          const voxels: Float32Array | Int32Array = voxelsCollisionDesc?.coordinates ?? new Int32Array([0, 0, 0]);
+          const voxelCount = voxels.length / 3;
+          const mass = this.calculateBoxMass(voxelSize, physicsOptions?.density) * voxelCount;
+          const record = this.doCreateVoxelBody({
+            motionType,
+            options: physicsOptions!,
+            worldPos,
+            worldQuat,
+            mass,
+            voxels,
+            voxelSize,
+            offset: voxelsCollisionDesc?.offset,
+          });
+          records.push(record);
+        }
+      }
+      else  {
+        // Non-Voxel, build the collision from the mesh geometry
+        const physicsMesh = this.processModelForPhysics(mesh);
+        const transforms = worldTransforms.map(t => ({position: t.worldPos, rotation: t.worldQuat, scale: t.worldScale}));
+
+        // Now create the physics body at the component's world position/rotation
+        records.push(...this.doCreateMeshBodiesWithTransformOverrides({
+          motionType,
+          options: physicsOptions!,
+          worldPos: new THREE.Vector3(), // transforms will provide the position/rotation overrides
+          worldQuat: new THREE.Quaternion(),  // same as above
+          mass: this.calculateMeshMass(physicsMesh.geometry, physicsOptions?.density),
+          meshes: [physicsMesh],
+        }, transforms));
+      }
+    } else {
+      // box
+      for (const {worldPos, worldQuat, worldScale} of worldTransforms) {
+        const size = new THREE.Vector3();
+        mesh.geometry.computeBoundingBox();
+        mesh.geometry.boundingBox!.getSize(size);
+        // Apply world scale to size
+        size.multiply(worldScale);
+        const record = this.doCreateBoxBody({
+          motionType,
+          options: physicsOptions!,
+          worldPos,
+          worldQuat,
+          mass: this.calculateBoxMass(size, physicsOptions?.density),
+          size,
+        });
+        records.push(record);
+      }
+    }
+
+    return [records, motionType];
+  }
+
+  /**
+   * Creates a physics record for a CollisionShapeComponent
+   * @param component The collision shape component
+   * @param physicsOptions The physics options
+   * @param worldPos The world position
+   * @param worldQuat The world quaternion
+   * @param worldScale The world scale
+   * @returns [record, motionType] tuple
+   */
+  protected createCollisionShapeRecord(
+    component: CollisionShapeComponent,
+    physicsOptions: ComponentPhysicsOptions | undefined,
+    worldPos: THREE.Vector3,
+    worldQuat: THREE.Quaternion,
+    worldScale: THREE.Vector3
+  ): [TRecord | null, PhysicsMotionType | null] {
+    const motionType = physicsOptions?.motionType ?? PhysicsMotionType.Dynamic;
+    const shapeType = component.getShapeType();
+    let record: TRecord | null;
+
+    if (shapeType === CollisionShapeType.Sphere) {
+      // For sphere, use the maximum scale component as radius
+      // CollisionShapeComponent creates unit-sized shapes that are scaled by the transform
+      const radius = Math.max(worldScale.x, worldScale.y, worldScale.z);
+      record = this.doCreateSphereBody({
+        motionType,
+        options: physicsOptions!,
+        worldPos,
+        worldQuat,
+        mass: this.calculateSphereMass(radius, physicsOptions?.density),
+        center: new THREE.Vector3(0, 0, 0),
+        radius: radius,
+      });
+    } else {
+      // Cube or default
+      // CollisionShapeComponent creates unit-sized shapes (1x1x1) that are scaled by the transform
+      // So the final size is simply the world scale
+      const size = worldScale.clone();
+
+      record = this.doCreateBoxBody({
+        motionType,
+        options: physicsOptions!,
+        worldPos,
+        worldQuat,
+        mass: this.calculateBoxMass(size, physicsOptions?.density),
+        size,
+      });
+    }
+
+    return [record, motionType];
+  }
+
+  /**
+   * Creates a physics record for a TerrainMeshComponent
+   * @param component The terrain mesh component
+   * @param physicsOptions The physics options
+   * @param worldPos The world position
+   * @param worldQuat The world quaternion
+   * @param worldScale The world scale
+   * @returns [record, motionType] tuple
+   */
+  protected createTerrainMeshRecord(
+    component: TerrainMeshComponent,
+    physicsOptions: ComponentPhysicsOptions | undefined,
+    worldPos: THREE.Vector3,
+    worldQuat: THREE.Quaternion,
+    worldScale: THREE.Vector3
+  ): [TRecord | null, PhysicsMotionType | null] {
+    const heightMap = component.getHeightMap();
+    // Apply world scale to terrain dimensions
+    const width = component.options.width * worldScale.x;
+    const depth = component.options.depth * worldScale.z;
+    const widthPixels = component.options.widthSegments + 1;
+    const depthPixels = component.options.depthSegments + 1;
+    const numPixels = widthPixels * depthPixels;
+
+    if (!ensure(heightMap)) {
+      return [null, null];
+    } else if (!ensure(heightMap!.length === numPixels)) {
+      return [null, null];
+    }
+
+    // Scale the height values
+    const scaledHeightMap = new Float32Array(heightMap!.length);
+    for (let i = 0; i < heightMap!.length; i++) {
+      scaledHeightMap[i] = heightMap![i] * worldScale.y;
+    }
+
+    const motionType = PhysicsMotionType.Static;
+    const record = this.doCreateHeightFieldBody({
+      motionType,
+      options: physicsOptions!,
+      worldPos,
+      worldQuat,
+      mass: 0,
+      width,
+      depth,
+      widthPixels,
+      depthPixels,
+      heights: scaledHeightMap,
+    });
+
+    return [record, motionType];
+  }
+
+  /**
+   * Creates a physics record for a GLTFMeshComponent
+   * @param component The GLTF mesh component
+   * @param physicsOptions The physics options
+   * @param worldPos The world position
+   * @param worldQuat The world quaternion
+   * @param worldScale The world scale
+   * @returns [record, motionType] tuple
+   */
+  protected createGLTFMeshRecord(
+    component: GLTFMeshComponent,
+    physicsOptions: ComponentPhysicsOptions,
+    worldPos: THREE.Vector3,
+    worldQuat: THREE.Quaternion,
+    worldScale: THREE.Vector3,
+  ): [TRecord | null, PhysicsMotionType | null] {
+    // Only proceed if the model is loaded
+    if (!component.isModelLoaded()) {
+      return [null, null];
+    }
+
+    const motionType = physicsOptions?.motionType ?? PhysicsMotionType.Dynamic;
+
+    const model = component.getModelTemplate();  // use model template as that's the copy living in resource manager and making it easy for cache
+    let record: TRecord | null = null;
+    const isVoxelsCollision = physicsOptions?.collisionMeshType === CollisionMeshType.Voxels;
+    if (isVoxelsCollision) {
+      const voxelsCollisionDesc: VoxelCollisionDesc | undefined = physicsOptions.collisionData?.voxels;
+      if (!voxelsCollisionDesc) {
+        console.log('No voxel collision data provided, using default single voxel at origin. Either provide collisionData.voxels in constructor, or use `overridePhysicsOptions`/`replacePhysicsOptions` to set it later.');
+      }
+      const voxelSize = voxelsCollisionDesc?.voxelSize ?? new THREE.Vector3(1, 1, 1);
+      const voxels: Float32Array | Int32Array = voxelsCollisionDesc?.coordinates ?? new Int32Array([0, 0, 0]);
+      const voxelCount = voxels.length / 3;
+      const mass = this.calculateBoxMass(voxelSize, physicsOptions?.density) * voxelCount;
+      record = this.doCreateVoxelBody({
+        motionType,
+        options: physicsOptions!,
+        worldPos,
+        worldQuat,
+        mass,
+        voxels,
+        voxelSize,
+        offset: voxelsCollisionDesc?.offset,
+      });
+    }
+    else {
+    // Collect all meshes from the model and create a single combined physics body
+      if (model) {
+      // don't bother finding physics meshes for voxel collision, as it comes from the physicsOptions.collisionData provided by user
+        const physicsMeshes = this.processGLTFModelForPhysics(model);
+
+        // Create a single physics body for all meshes combined
+        if (physicsMeshes.length > 0) {
+          record = this.doCreateMeshBody({
+            motionType: motionType!,
+            options: physicsOptions!,
+            worldPos,
+            worldQuat,
+            mass: physicsMeshes.reduce((sum, mesh) => sum + this.calculateMeshMass(mesh.geometry, physicsOptions?.density), 0),
+            meshes: physicsMeshes,
+          }, worldScale);
+
+          if (record) {
+          // should contain only one record as there is only one worldPos and worldQuat
+            console.log('Created combined physics body for GLTF model with', physicsMeshes.length, 'meshes');
+          }
+        }
+      }
+    }
+
+    return [record, motionType];
+  }
+
+  /**
+   *
+   * @param component The instanced mesh component
+   * @param physicsOptions The physics options
+   * @param worldPos The world position
+   * @param worldQuat The world quaternion
+   * @param worldScale The world scale
+   * @returns
+   */
+  protected createInstancedMeshRecord(
+    component: InstancedMeshComponent,
+    physicsOptions: ComponentPhysicsOptions | undefined,
+    worldPos: THREE.Vector3,
+    worldQuat: THREE.Quaternion,
+    worldScale: THREE.Vector3
+  ): [TRecord[], PhysicsMotionType | null] {
+    let records: TRecord[] = [];
+    const motionType = physicsOptions?.motionType ?? PhysicsMotionType.Dynamic;
+    const transforms = component.getInstancesTransforms(true);
+    const isVoxelsCollision = physicsOptions?.collisionMeshType === CollisionMeshType.Voxels;
+    const mesh = component.getInstancedMesh();
+    if (!mesh) {
+      return [[], null];
+    }
+
+    const instanceCount = component.getInstanceCount();
+    if (!instanceCount || instanceCount === 0) {
+      return [[], null];
+    }
+
+    const worldTransforms = isVoxelsCollision ? [{worldPos, worldQuat, worldScale}] :
+      transforms.map(transform => ({
+        worldPos: transform.position ?? new THREE.Vector3(),
+        worldQuat: transform.rotation ? new THREE.Quaternion().setFromEuler(transform.rotation) : new THREE.Quaternion(),
+        worldScale: transform.scale ?? new THREE.Vector3(1, 1, 1)
+      }));
+
+    const [createdRecords, ] = this.createMeshRecord(mesh, physicsOptions, worldTransforms, component);
+    records = createdRecords.filter(r => r !== null) as TRecord[];
+
+    return [records, motionType];
+  }
+
+  /**
+   * Creates physics records for an InstancedGltfMeshComponent
+   * @param component The instanced GLTF mesh component
+   * @param physicsOptions The physics options
+   * @param worldScale The world scale
+   * @returns [records, motionType] tuple
+   */
+  protected createInstancedGltfMeshRecord(
+    component: InstancedGltfMeshComponent,
+    physicsOptions: ComponentPhysicsOptions | undefined,
+    worldPos: THREE.Vector3,
+    worldQuat: THREE.Quaternion
+  ): [TRecord[], PhysicsMotionType | null] {
+    // Only proceed if the model is loaded (check if we have instanced meshes)
+    if (component.isLoading()) {
+      return [[], null];
+    }
+
+    const instancedMeshes = component.getInstancedMeshes();
+    if (!instancedMeshes || instancedMeshes.length === 0) {
+      return [[], null];
+    }
+
+    // Get the number of instances
+    const instanceCount = component.getInstanceCount();
+
+    if (!instanceCount || instanceCount === 0) {
+      return [[], null];
+    }
+
+    let records: TRecord[] = [];
+    const motionType = physicsOptions?.motionType ?? PhysicsMotionType.Dynamic;
+    const isVoxelsCollision = physicsOptions?.collisionMeshType === CollisionMeshType.Voxels;
+    if (isVoxelsCollision) {
+      const voxelsCollisionDesc: VoxelCollisionDesc | undefined = physicsOptions.collisionData?.voxels;
+      if (!voxelsCollisionDesc) {
+        console.log('No voxel collision data provided, using default single voxel at origin. Either provide collisionData.voxels in constructor, or use `overridePhysicsOptions`/`replacePhysicsOptions` to set it later.');
+      }
+      const voxelSize = voxelsCollisionDesc?.voxelSize ?? new THREE.Vector3(1, 1, 1);
+      const voxels: Float32Array | Int32Array = voxelsCollisionDesc?.coordinates ?? new Int32Array([0, 0, 0]);
+      const voxelCount = voxels.length / 3;
+      const mass = this.calculateBoxMass(voxelSize, physicsOptions?.density) * voxelCount;
+      const record = this.doCreateVoxelBody({
+        motionType,
+        options: physicsOptions!,
+        worldPos,
+        worldQuat,
+        mass,
+        voxels,
+        voxelSize,
+        offset: voxelsCollisionDesc?.offset,
+      });
+      if (record) {
+        records = [record];
+      }
+    }
+    else {
+      const model = component.getModelTemplate();
+      if (model) {
+      // Process the GLTF model to create physics meshes (same as regular GLTF)
+        const physicsMeshes = this.processGLTFModelForPhysics(model);
+
+        // Create physics bodies for the instances
+        if (physicsMeshes.length > 0) {
+          const transforms = component.getInstancesTransforms(true);
+          const paramTransforms = transforms.map(transform => ({
+            position: transform.position ?? new THREE.Vector3(),
+            rotation: transform.rotation ? new THREE.Quaternion().setFromEuler(transform.rotation) : new THREE.Quaternion(),
+            scale: transform.scale ?? new THREE.Vector3(1, 1, 1)
+          }));
+
+          records = this.doCreateMeshBodiesWithTransformOverrides({
+            motionType: motionType!,
+            options: physicsOptions!,
+            worldPos: paramTransforms[0].position,
+            worldQuat: paramTransforms[0].rotation,
+            // sum of all physicsMeshes
+            mass: physicsMeshes.reduce((sum, mesh) => sum + this.calculateMeshMass(mesh.geometry, physicsOptions?.density), 0),
+            meshes: physicsMeshes,
+          }, paramTransforms);
+        }
+      }
+    }
+
+    return [records, motionType];
+  }
+
+  /**
+     * Removes a scene component from the physics simulation
+     * @param component The scene component to remove
+     */
+  public removeComponent(component: PrimitiveComponent): void {
+    if (!ensure(this.initialized)) {
+      return;
+    }
+
+    const records = this.bodies.get(component);
+    if (!records) {
+      return;
+    }
+
+    records.forEach((record) => {
+      this.doRemoveComponent(record);
+    });
+    this.bodies.delete(component);
+  }
+
+  /**
+     * Updates the transform (position/rotation) of a physics body
+     * @param component The primitive component whose transform should be updated
+     */
+  public updateTransform(component: PrimitiveComponent): void {
+    if (!ensure(this.initialized)) {
+      return;
+    }
+
+    const records = this.bodies.get(component);
+    if (!records) {
+      return;
+    }
+
+    records.forEach((record) => {
+      this.doUpdateTransform(component, record);
+    });
+  }
+
+  /**
+     * Gets a scalar physics parameter value for a component
+     * @param component The scene component to query
+     * @param param The scalar parameter to get
+     * @returns The parameter value or null if not found
+     */
+  public getScalarParam(component: PrimitiveComponent, param: PhysicsScalarParam): number | null {
+    if (!ensure(this.initialized)) {
+      return null;
+    }
+
+    const records = this.bodies.get(component);
+    if (!records || records.length === 0) {
+      return null;
+    }
+
+    return this.doGetScalarParam(records[0], param);
+  }
+
+  /**
+     * Sets a scalar physics parameter value for a component
+     * @param component The scene component to modify
+     * @param param The scalar parameter to set
+     * @param value The new parameter value
+     * @returns True if the parameter was set successfully
+     */
+  public setScalarParam(component: PrimitiveComponent, param: PhysicsScalarParam, value: number): boolean {
+    if (!ensure(this.initialized)) {
+      return false;
+    }
+
+    const records = this.bodies.get(component);
+    if (!records) {
+      return false;
+    }
+
+    return this.doSetScalarParam(records, param, value);
+  }
+
+  /**
+     * Gets a vector physics parameter value for a component
+     * @param component The scene component to query
+     * @param param The vector parameter to get
+     * @returns The parameter value array or null if not found
+     */
+  public getVectorParam(component: PrimitiveComponent, param: PhysicsVectorParam): VectorArray | null {
+    if (!ensure(this.initialized)) {
+      return null;
+    }
+
+    const records = this.bodies.get(component);
+    if (!records || records.length === 0) {
+      return null;
+    }
+
+    return this.doGetVectorParam(records[0], param);
+  }
+
+  /**
+     * Sets a vector physics parameter value for a component
+     * @param component The scene component to modify
+     * @param param The vector parameter to set
+     * @param value The new parameter value array
+     * @returns True if the parameter was set successfully
+     */
+  public setVectorParam(component: PrimitiveComponent, param: PhysicsVectorParam, value: VectorArray): boolean {
+    if (!ensure(this.initialized)) {
+      return false;
+    }
+
+    const records = this.bodies.get(component);
+    if (!records || records.length === 0) {
+      return false;
+    }
+    return records.reduce((acc, record) => acc && this.doSetVectorParam(record, param, value), true);
+  }
+
+  /**
+   * Clears a vector physics parameter value for a component
+   * @param component The scene component to modify
+   * @param param The vector parameter to clear
+   * @returns True if the parameter was cleared successfully
+   */
+  public clearVectorParam(component: PrimitiveComponent, param: PhysicsVectorParam): boolean {
+    if (!ensure(this.initialized)) {
+      return false;
+    }
+
+    const records = this.bodies.get(component);
+    if (!records || records.length === 0) {
+      return false;
+    }
+    return records.reduce((acc, record) => acc && this.doClearVectorParam(record, param), true);
+  }
+
+  /**
+   * Create a character controller for a scene component
+   * @param movementComponent Component to create controller for
+   * @param options Character controller options
+   * @returns True if the character controller was created successfully, false otherwise
+   */
+  public createCharacterController(movementComponent: BasePawnMovementComponent, options: CharacterControllerOptions): boolean {
+    if (!ensure(this.initialized)) {
+      return false;
+    }
+
+    if (!ensure(!this.characterControllers.has(movementComponent))) {
+      return false;
+    }
+
+    const record = this.doCreateCharacterController(options);
+    if (!record) {
+      return false;
+    }
+    this.characterControllers.set(movementComponent, record);
+    return true;
+  }
+
+  /**
+   * Remove a character controller for a scene component
+   * @param movementComponent Component to remove controller for
+   */
+  public removeCharacterController(movementComponent: BasePawnMovementComponent): void {
+    if (!ensure(this.initialized)) {
+      return;
+    }
+
+    const record = this.characterControllers.get(movementComponent);
+    if (!record) {
+      return;
+    }
+
+    if (this.doRemoveCharacterController(record)) {
+      this.characterControllers.delete(movementComponent);
+    }
+  }
+
+  /**
+   * Compute character movement for a scene component
+   * @param movementComponent Component to compute movement for
+   * @param componentToMove Component to move
+   * @param movement Movement vector [x, y, z]
+   */
+  public computeCharacterMovement(movementComponent: BasePawnMovementComponent, componentToMove: PrimitiveComponent, movement: VectorArray, ignoreCollision: boolean): { isGrounded: boolean } {
+    if (!ensure(this.initialized)) {
+      return { isGrounded: false };
+    }
+
+    const record = this.characterControllers.get(movementComponent);
+    if (!record) {
+      return { isGrounded: false };
+    }
+
+    const recordsToMove = this.bodies.get(componentToMove);
+    if (!recordsToMove || recordsToMove.length === 0) {
+      return { isGrounded: false };
+    }
+
+    // only handle recordsToMove[0] for now
+    return this.doComputeCharacterMovement(record, recordsToMove[0], movement, ignoreCollision);
+  }
+
+  /**
+   * Configure collision filtering between two components
+   * @param componentA First component
+   * @param componentB Second component
+   * @param ignore Whether componentA should ignore collisions with componentB
+   */
+  public setComponentCollisionIgnore(componentA: PrimitiveComponent, componentB: PrimitiveComponent, ignore: boolean): boolean {
+    if (!ensure(this.initialized)) {
+      return false;
+    }
+
+    const recordsA = this.bodies.get(componentA);
+    const recordsB = this.bodies.get(componentB);
+
+    if (!recordsA || !recordsB) {
+      return false;
+    }
+
+    let result = true;
+    for (const recordA of recordsA) {
+      for (const recordB of recordsB) {
+        result = result && this.doSetComponentCollisionIgnore(recordA, recordB, ignore);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Creates a joint between two physics bodies
+   * @param desc Joint description containing type, components, and connection points
+   * @returns Joint ID if successful, null if failed
+   */
+  public createJoint(desc: JointDesc): string | null {
+    if (!ensure(this.initialized)) {
+      return null;
+    }
+
+    const recordsA = this.bodies.get(desc.componentA);
+    const recordsB = this.bodies.get(desc.componentB);
+
+    if (!recordsA || !recordsB) {
+      console.error('Cannot create joint: one or both components not found in physics engine');
+      return null;
+    }
+
+    if (recordsA.length !== 1 || recordsB.length !== 1) {
+      console.error('Cannot create joint: one or both components have multiple or none body count');
+      return null;
+    }
+
+    const jointRecord = this.doCreateJoint(desc, recordsA[0], recordsB[0]);
+    if (!jointRecord) {
+      return null;
+    }
+
+    const jointId = `joint_${this.nextJointId++}`;
+    this.joints.set(jointId, jointRecord);
+    return jointId;
+  }
+
+  /**
+   * Removes a joint from the physics simulation
+   * @param jointId The joint ID returned from createJoint
+   * @returns True if the joint was successfully removed
+   */
+  public removeJoint(jointId: string): boolean {
+    if (!ensure(this.initialized)) {
+      return false;
+    }
+
+    const jointRecord = this.joints.get(jointId);
+    if (!jointRecord) {
+      return false;
+    }
+
+    if (this.doRemoveJoint(jointRecord)) {
+      this.joints.delete(jointId);
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Gets all active joint IDs
+   * @returns Array of joint IDs
+   */
+  public getActiveJoints(): string[] {
+    return Array.from(this.joints.keys());
+  }
+
+  /**
+   * Creates a joint directly from physics body records (for special cases like ragdoll)
+   * @param type Joint type
+   * @param recordA First physics body record
+   * @param recordB Second physics body record
+   * @param anchorA Anchor point on first body
+   * @param anchorB Anchor point on second body
+   * @param axis Optional axis for revolute/prismatic joints
+   * @returns Joint ID if successful, null if failed
+   */
+  public createJointFromRecords(
+    type: JointType,
+    recordA: TRecord,
+    recordB: TRecord,
+    anchorA: THREE.Vector3,
+    anchorB: THREE.Vector3,
+    axis?: THREE.Vector3
+  ): string | null {
+    if (!ensure(this.initialized)) {
+      return null;
+    }
+
+    const jointRecord = this.doCreateJointFromRecords(type, recordA, recordB, anchorA, anchorB, axis);
+    if (!jointRecord) {
+      return null;
+    }
+
+    const jointId = `joint_${this.nextJointId++}`;
+    this.joints.set(jointId, jointRecord);
+    return jointId;
+  }
+
+  // Direct physics body management methods (for special cases like ragdolls)
+
+  public createPhysicsBody(desc: PhysicsBodyDesc): string | null {
+    if (!ensure(this.initialized)) {
+      return null;
+    }
+
+    const record = this.doCreateDirectBody(desc);
+    if (!record) {
+      return null;
+    }
+
+    const handle = `body_${this.nextBodyId++}`;
+    this.directBodies.set(handle, record);
+    return handle;
+  }
+
+  public removePhysicsBody(handle: string): boolean {
+    if (!ensure(this.initialized)) {
+      return false;
+    }
+
+    const record = this.directBodies.get(handle);
+    if (!record) {
+      return false;
+    }
+
+    const success = this.doRemoveDirectBody(record);
+    if (success) {
+      this.directBodies.delete(handle);
+    }
+    return success;
+  }
+
+  public isValidPhysicsBody(handle: string): boolean {
+    return this.directBodies.has(handle);
+  }
+
+  public getPhysicsBodyPosition(handle: string): THREE.Vector3 | null {
+    const record = this.directBodies.get(handle);
+    if (!record) {
+      return null;
+    }
+    return this.doGetBodyPosition(record);
+  }
+
+  public getPhysicsBodyRotation(handle: string): THREE.Quaternion | null {
+    const record = this.directBodies.get(handle);
+    if (!record) {
+      return null;
+    }
+    return this.doGetBodyRotation(record);
+  }
+
+  public setPhysicsBodyPosition(handle: string, position: THREE.Vector3): boolean {
+    const record = this.directBodies.get(handle);
+    if (!record) {
+      return false;
+    }
+    return this.doSetBodyPosition(record, position);
+  }
+
+  public setPhysicsBodyRotation(handle: string, rotation: THREE.Quaternion): boolean {
+    const record = this.directBodies.get(handle);
+    if (!record) {
+      return false;
+    }
+    return this.doSetBodyRotation(record, rotation);
+  }
+
+  public applyImpulseToPhysicsBody(handle: string, impulse: THREE.Vector3, worldSpace: boolean = true): boolean {
+    const record = this.directBodies.get(handle);
+    if (!record) {
+      return false;
+    }
+    return this.doApplyBodyImpulse(record, impulse, worldSpace);
+  }
+
+  public setPhysicsBodyEnabled(handle: string, enabled: boolean): boolean {
+    const record = this.directBodies.get(handle);
+    if (!record) {
+      return false;
+    }
+    return this.doSetBodyEnabled(record, enabled);
+  }
+
+  public createJointFromBodies(
+    type: JointType,
+    bodyA: string,
+    bodyB: string,
+    anchorA: THREE.Vector3,
+    anchorB: THREE.Vector3,
+    axis?: THREE.Vector3
+  ): string | null {
+    if (!ensure(this.initialized)) {
+      return null;
+    }
+
+    const recordA = this.directBodies.get(bodyA);
+    const recordB = this.directBodies.get(bodyB);
+
+    if (!recordA || !recordB) {
+      return null;
+    }
+
+    const jointRecord = this.doCreateJointFromRecords(type, recordA, recordB, anchorA, anchorB, axis);
+    if (!jointRecord) {
+      return null;
+    }
+
+    const jointId = `joint_${this.nextJointId++}`;
+    this.joints.set(jointId, jointRecord);
+    return jointId;
+  }
+
+  //====================================================================================================
+
+  protected calculateBoxMass(size: THREE.Vector3, density: number | undefined): number {
+    const volume = size.x * size.y * size.z;
+    return volume * (density ?? 1);
+  }
+
+  protected calculateSphereMass(radius: number, density: number | undefined): number {
+    const volume = (4 / 3) * Math.PI * radius * radius * radius;
+    return volume * (density ?? 1);
+  }
+
+  protected calculateCylinderMass(height: number, radius: number, density: number | undefined): number {
+    const volume = Math.PI * radius * radius * height;
+    return volume * (density ?? 1);
+  }
+
+  protected calculateCapsuleMass(height: number, radius: number, density: number | undefined): number {
+    // Capsule is a cylinder with two hemisphere caps
+    const cylinderVolume = Math.PI * radius * radius * height;
+    const hemisphereVolume = (2/3) * Math.PI * radius * radius * radius;
+    const volume = cylinderVolume + 2 * hemisphereVolume;
+    return volume * (density ?? 1);
+  }
+
+  protected calculateConeMass(height: number, radius: number, density: number | undefined): number {
+    const volume = (1 / 3) * Math.PI * radius * radius * height;
+    return volume * (density ?? 1);
+  }
+
+  protected calculateMeshMass(geometry: THREE.BufferGeometry, density: number | undefined): number {
+    // Approximate mass based on bounding box volume
+    geometry.computeBoundingBox();
+    const bbox = geometry.boundingBox;
+    if (!bbox) {
+      return 1; // default mass
+    }
+    const size = new THREE.Vector3();
+    bbox.getSize(size);
+    const volume = size.x * size.y * size.z;
+    return volume * (density ?? 1);
+  }
+
+
+    protected abstract doCreate(options: PhysicsOptions): Promise<boolean>;
+    protected abstract doDestroy(): boolean;
+    protected abstract doTick(deltaTime: number): void;
+    protected abstract doRemoveComponent(record: TRecord): boolean;
+    protected abstract doUpdateTransform(component: SceneComponent, record: TRecord): void;
+    protected abstract doGetScalarParam(record: TRecord, param: PhysicsScalarParam): number | null;
+    protected abstract doSetScalarParam(records: TRecord[], param: PhysicsScalarParam, value: number): boolean;
+    protected abstract doGetVectorParam(record: TRecord, param: PhysicsVectorParam): VectorArray | null;
+    protected abstract doSetVectorParam(record: TRecord, param: PhysicsVectorParam, value: VectorArray): boolean;
+    protected abstract doClearVectorParam(record: TRecord, param: PhysicsVectorParam): boolean;
+    protected abstract doCreateBoxBody(desc: BoxBodyDesc): TRecord | null;
+    protected abstract doCreateMeshBody(desc: MeshBodyDesc, scale: THREE.Vector3): TRecord | null;
+    protected abstract doCreateMeshBodiesWithTransformOverrides(desc: MeshBodyDesc, transforms: {position?: THREE.Vector3, rotation?: THREE.Quaternion, scale?: THREE.Vector3}[]): TRecord[];
+    protected abstract doCreateVoxelBody(desc: VoxelBodyDesc): TRecord | null;
+    protected abstract doCreateSphereBody(desc: SphereBodyDesc): TRecord | null;
+    protected abstract doCreateCylinderBody(desc: CylinderBodyDesc): TRecord | null;
+    protected abstract doCreateCapsuleBody(desc: CapsuleBodyDesc): TRecord | null;
+    protected abstract doCreateConeBody(desc: ConeBodyDesc): TRecord | null;
+    protected abstract doCreateHeightFieldBody(desc: HeightFieldBodyDesc): TRecord | null;
+    protected doCreateCharacterController(options: CharacterControllerOptions): TCharacterControllerRecord | null {
+      throw new Error('Not implemented');
+    }
+    protected doRemoveCharacterController(record: TCharacterControllerRecord): boolean {
+      throw new Error('Not implemented');
+    }
+    protected doComputeCharacterMovement(record: TCharacterControllerRecord, recordToMove: TRecord, movement: VectorArray, ignoreCollision: boolean): { isGrounded: boolean } {
+      throw new Error('Not implemented');
+    }
+    protected doSetComponentCollisionIgnore(recordA: TRecord, recordB: TRecord, ignore: boolean): boolean {
+      throw new Error('Not implemented');
+    }
+    protected abstract doCreateJoint(desc: JointDesc, recordA: TRecord, recordB: TRecord): TJointRecord | null;
+    protected abstract doRemoveJoint(jointRecord: TJointRecord): boolean;
+    protected abstract doCreateJointFromRecords(
+      type: JointType,
+      recordA: TRecord,
+      recordB: TRecord,
+      anchorA: THREE.Vector3,
+      anchorB: THREE.Vector3,
+      axis?: THREE.Vector3
+    ): TJointRecord | null;
+
+    // Abstract methods for direct physics body management
+    protected abstract doCreateDirectBody(desc: PhysicsBodyDesc): TRecord | null;
+    protected abstract doRemoveDirectBody(record: TRecord): boolean;
+    protected abstract doGetBodyPosition(record: TRecord): THREE.Vector3 | null;
+    protected abstract doGetBodyRotation(record: TRecord): THREE.Quaternion | null;
+    protected abstract doSetBodyPosition(record: TRecord, position: THREE.Vector3): boolean;
+    protected abstract doSetBodyRotation(record: TRecord, rotation: THREE.Quaternion): boolean;
+    protected abstract doApplyBodyImpulse(record: TRecord, impulse: THREE.Vector3, worldSpace: boolean): boolean;
+    protected abstract doSetBodyEnabled(record: TRecord, enabled: boolean): boolean;
+    public abstract getComponentState(component: PrimitiveComponent): PrimitiveComponentPhysicsState | null;
+    public abstract getCollisionEvents(): RawCollisionEvent[];
+    public abstract clearCollisionEvents(): void;
+    public abstract setDebugRendererEnabled(enabled: boolean): boolean;
+    public abstract isDebugRendererEnabled(): boolean;
+
+    /**
+   * Process any pending collision events in the physics system
+   * This is called internally by the tick method
+   */
+    protected processCollisionEvents(): void {
+      const events = this.getCollisionEvents();
+      for (const event of events) {
+        this.handleCollisionEvent(event);
+      }
+      // Clear the collision events after processing them
+      this.clearCollisionEvents();
+    }
+
+    /**
+   * Handles a single collision event by notifying the involved components
+   * @param event Collision event information
+   */
+    protected handleCollisionEvent(event: RawCollisionEvent): void {
+      const componentA = event.componentA;
+      const componentB = event.componentB;
+
+      const eventA: CollisionEvent = {
+        thisComponent: componentA,
+        otherComponent: componentB,
+        thisPoint: event.pointA,
+        thisNormal: event.normalA,
+        otherPoint: event.pointB,
+        otherNormal: event.normalB,
+        relativeVelocity: event.relativeVelocity,
+      };
+
+      const eventB: CollisionEvent = {
+        thisComponent: componentB,
+        otherComponent: componentA,
+        thisPoint: event.pointB,
+        thisNormal: event.normalB,
+        otherPoint: event.pointA,
+        otherNormal: event.normalA,
+        relativeVelocity: event.relativeVelocity,
+      };
+
+      if (componentA && componentB) {
+        const actorA = componentA.getActor();
+        const actorB = componentB.getActor();
+
+        if(event.eventType === CollisionEventType.Started) {
+          if (event.isTriggerEvent) {
+            // Component events
+            componentA.onOverlapWith.invoke(componentA, componentB, eventA);
+            componentB.onOverlapWith.invoke(componentB, componentA, eventB);
+            // Actor events
+            if (actorA && actorB) actorA.onOverlapWith.invoke(actorA, componentA, actorB, componentB, eventA);
+            if (actorB && actorA) actorB.onOverlapWith.invoke(actorB, componentB, actorA, componentA, eventB);
+          } else {
+            // Component events
+            componentA.onCollideWith.invoke(componentA, componentB, eventA);
+            componentB.onCollideWith.invoke(componentB, componentA, eventB);
+            // Actor events
+            if (actorA && actorB) actorA.onCollideWith.invoke(actorA, componentA, actorB, componentB, eventA);
+            if (actorB && actorA) actorB.onCollideWith.invoke(actorB, componentB, actorA, componentA, eventB);
+          }
+        } else {
+          if (event.isTriggerEvent) {
+            // Component events
+            componentA.onStopOverlappingWith.invoke(componentA, componentB, eventA);
+            componentB.onStopOverlappingWith.invoke(componentB, componentA, eventB);
+            // Actor events
+            if (actorA && actorB) actorA.onStopOverlappingWith.invoke(actorA, componentA, actorB, componentB, eventA);
+            if (actorB && actorA) actorB.onStopOverlappingWith.invoke(actorB, componentB, actorA, componentA, eventB);
+          } else {
+            // Component events
+            componentA.onStopCollidingWith.invoke(componentA, componentB, eventA);
+            componentB.onStopCollidingWith.invoke(componentB, componentA, eventB);
+            // Actor events
+            if (actorA && actorB) actorA.onStopCollidingWith.invoke(actorA, componentA, actorB, componentB, eventA);
+            if (actorB && actorA) actorB.onStopCollidingWith.invoke(actorB, componentB, actorA, componentA, eventB);
+          }
+        }
+      }
+    }
+
+    // Vehicle controller methods - default implementations that throw errors
+    public abstract createVehicle(movementComponent: BasePawnMovementComponent, chassisComponent: PrimitiveComponent): IPhysicsVehicle | null;
+}