@directivegames/genesys.js 3.1.24

package/src/physics/IPhysicsVehicle.ts

@@ -0,0 +1,162 @@
+/**
+ * Interface for physics vehicle controllers
+ *
+ * This interface encapsulates all vehicle-specific physics operations,
+ * providing a clean abstraction that separates vehicle logic from the
+ * main physics engine implementation.
+ */
+import type * as THREE from 'three';
+
+/**
+ * Configuration for a vehicle wheel
+ */
+export interface VehicleWheelConfig {
+  /** Position relative to vehicle chassis center */
+  position: THREE.Vector3;
+  /** Wheel radius in meters */
+  radius: number;
+  /** Wheel width in meters */
+  width: number;
+  /** Whether this wheel can steer */
+  canSteer: boolean;
+  /** Whether this wheel receives engine power */
+  isPowered: boolean;
+  /** Whether this wheel can brake */
+  canBrake: boolean;
+  /** Suspension rest length in meters */
+  suspensionRestLength: number;
+  /** suspension_stiffness (default: 5.88) - How stiff the suspension springs are. Higher = less compression, stiffer ride */
+  suspensionStiffness?: number;
+  /** suspension_compression (default: 0.83) - Damping during compression. Higher = less bouncing when hitting bumps */
+  suspensionCompression?: number;
+  /** suspension_damping (default: 0.88) - Damping during extension. Higher = prevents overshoot/oscillation */
+  suspensionRelaxation?: number;
+  /** max_suspension_force (default: 6000.0) - Maximum force the suspension can apply */
+  maxSuspensionForce?: number;
+  /** max_suspension_travel (default: 5.0) - Maximum distance suspension can compress/extend from rest position */
+  maxSuspensionTravel?: number;
+  /** side_friction_stiffness (default: 1.0) - Lateral tire grip multiplier for cornering */
+  sideFrictionStiffness?: number;
+  /** friction_slip (default: 10.5) - Tire traction amount. Higher = more grip, more instantaneous braking (risk of flipping) */
+  frictionSlip?: number;
+  /** Wheel direction vector (usually pointing down) */
+  wheelDirection?: THREE.Vector3;
+  /** Wheel axle vector (usually pointing left/right) */
+  wheelAxle?: THREE.Vector3;
+}
+
+/**
+ * Transform information for a vehicle wheel
+ */
+export interface VehicleWheelState {
+  /** Wheel position relative to the chassis */
+  relativePosition: THREE.Vector3;
+  /** Wheel rotation quaternion relative to the chassis */
+  relativeQuaternion: THREE.Quaternion;
+  /** Current steering angle in radians */
+  steeringAngle: number;
+  /** Current wheel rotation angle in radians */
+  rotationAngle: number;
+
+  /** Suspension rest length in meters */
+  suspensionRestLength: number | null;
+  /** Maximum suspension travel */
+  maxSuspensionTravel: number | null;
+  /** Wheel radius in meters */
+  radius: number | null;
+  /** Suspension stiffness (higher = stiffer) */
+  suspensionStiffness: number | null;
+  /** Suspension compression coefficient */
+  suspensionCompression: number | null;
+  /** Suspension relaxation coefficient */
+  suspensionRelaxation: number | null;
+  /** Maximum suspension force */
+  maxSuspensionForce: number | null;
+  /** Current brake force */
+  brakeForce: number | null;
+  /** Current engine force */
+  engineForce: number | null;
+  /** Wheel friction coefficient */
+  frictionSlip: number | null;
+  /** Side friction stiffness */
+  sideFrictionStiffness: number | null;
+  /** Current suspension force */
+  suspensionForce: number | null;
+  /** Contact normal */
+  contactNormal: THREE.Vector3 | null;
+  /** Contact point */
+  contactPoint: THREE.Vector3 | null;
+  /** Current suspension length */
+  suspensionLength: number | null;
+  /** Hard point */
+  hardPoint: THREE.Vector3 | null;
+  /** Whether the wheel is touching the ground */
+  isInContact: boolean | null;
+}
+
+/**
+ * State information for a vehicle
+ */
+export interface VehicleState {
+  /** Current linear velocity */
+  velocity: THREE.Vector3;
+  /** Current angular velocity */
+  angularVelocity: THREE.Vector3;
+  /** Current speed in m/s */
+  speed: number;
+  /** Number of wheels touching the ground */
+  wheelsOnGround: number;
+  /** Total number of wheels */
+  totalWheels: number;
+}
+
+export interface IPhysicsVehicle {
+  /**
+   * Add a wheel to the vehicle
+   * @param wheelConfig Configuration for the wheel
+   * @returns The wheel index, or -1 if failed
+   */
+  addWheel(wheelConfig: VehicleWheelConfig): number;
+
+  /**
+   * Set engine force for specified wheels
+   * @param force Engine force to apply
+   */
+  setEngineForce(force: number): void;
+
+  /**
+   * Set brake force for specified wheels
+   * @param force Brake force to apply
+   */
+  setBrakeForce(force: number): void;
+
+  /**
+   * Set steering angle for specified wheels
+   * @param angle Steering angle in radians
+   */
+  setSteering(angle: number): void;
+
+  /**
+   * Get the transform (position and rotation) of a specific wheel
+   * @param wheelIndex Index of the wheel
+   * @returns Transform data or null if invalid wheel index
+   */
+  getWheelState(wheelIndex: number): VehicleWheelState | null;
+
+  /**
+   * Get the current state of the vehicle (speed, RPM, etc.)
+   * @returns Current vehicle state
+   */
+  getState(): VehicleState | null;
+
+  /**
+   * Get the number of wheels on the vehicle
+   * @returns Number of wheels
+   */
+  numWheels(): number;
+
+  /**
+   * Destroy the vehicle
+   */
+  destroy(): void;
+}

package/src/physics/PhysicsEngine.ts

@@ -0,0 +1,517 @@
+/**
+ * PhysicsEngine defines the public interface and factory for physics backends.
+ *
+ * The module collects option types, parameter enums and the `IPhysicsEngine`
+ * contract shared by all implementations. It also hosts the convenience
+ * `createPhysicsEngine` function which instantiates the configured backend,
+ * currently Rapier. This keeps high level game code agnostic to the underlying
+ * library and ensures consistent behavior across different engines.
+ *
+ * Recommended usage (for humans and AI assistants):
+ * - Select an engine in `PhysicsOptions` then pass those options to
+ *   `createPhysicsEngine` during world setup.
+ * - Call `tick` once per frame and use `addComponent`/`removeComponent` to keep
+ *   physics bodies in sync with scene components.
+ * - Query and update body parameters through `getScalarParam` or
+ *   `setVectorParam` to tweak motion at runtime.
+ */
+
+
+
+import { RapierPhysicsEngine } from './implementations/RapierPhysics.js';
+
+import type { IPhysicsVehicle } from './IPhysicsVehicle.js';
+import type { PhysicsMotionType } from './PhysicsTypes.js';
+import type { BasePawnMovementComponent } from '../components/movement/BasePawnMovementComponent.js';
+import type { PrimitiveComponent } from '../components/PrimitiveComponent.js';
+import type { SceneComponent } from '../components/SceneComponent.js';
+import type { Actor } from 'src/actors/Actor.js';
+import type { CollisionProfile } from 'src/systems/collision/CollisionTypes.js';
+import type * as THREE from 'three';
+
+export enum PhysicsEngine {
+    Disable = 'disable',
+    Rapier = 'rapier',
+}
+
+/**
+ * Configuration options for physics simulation
+ */
+export interface PhysicsOptions {
+    /** Gravity vector (m/s²) */
+    gravity: THREE.Vector3;
+    /** Physics engine to use */
+    engine: PhysicsEngine;
+    /** Whether to enable debug visualization */
+    debugVisualization?: boolean;
+}
+
+/**
+ * Description of a scene component's state in the physics engine
+ */
+export interface PrimitiveComponentPhysicsState {
+  motionType: PhysicsMotionType;
+  isTrigger: boolean;
+}
+
+/**
+ * Options for performing a hit test
+ */
+export interface HitTestOptions {
+  origin: THREE.Vector3;
+  direction: THREE.Vector3;
+  maxDistance: number;
+  stopOnFirstHit: boolean;
+  collisionProfile?: CollisionProfile | null;
+  ignoredActors?: Array<Actor>;
+  ignoredComponents?: Array<SceneComponent>;
+}
+
+/**
+ * Result of a hit test
+ */
+export interface HitTestResult {
+  origin: THREE.Vector3;
+  direction: THREE.Vector3;
+  hitLocation: THREE.Vector3;
+  hitNormal: THREE.Vector3;
+  hitComponent: PrimitiveComponent | null;
+  hitActor: Actor | null;
+}
+
+/**
+ * Opaque handle to a physics body (abstracts away engine-specific types)
+ */
+export type PhysicsBodyHandle = string;
+
+/**
+ * Configuration for creating physics bodies directly
+ */
+export interface PhysicsBodyDesc {
+  /** Body shape configuration */
+  shape: PhysicsBodyShape;
+  /** Mass (0 for static bodies) */
+  mass: number;
+  /** Initial world position */
+  position: THREE.Vector3;
+  /** Initial world rotation */
+  rotation: THREE.Quaternion;
+  /** Motion type */
+  motionType: PhysicsMotionType;
+  /** Whether the body starts enabled */
+  enabled?: boolean;
+}
+
+/**
+ * Shape configuration for physics bodies
+ */
+export interface PhysicsBodyShape {
+  type: 'box' | 'sphere' | 'cylinder' | 'capsule';
+  // For box
+  size?: THREE.Vector3;
+  // For sphere
+  radius?: number;
+  // For cylinder/capsule
+  height?: number;
+}
+
+/**
+ * Configuration options for character controllers
+ * See https://rapier.rs/docs/user_guides/javascript/character_controller
+ */
+export interface CharacterControllerOptions {
+  /** The gap the controller will leave between the character and its environment. */
+  offset: number;
+
+  /** The scale of the simulated gravity that is applied to the character controller.*/
+  simulatedGravityScale: number;
+
+  /** Whether to apply impulses to dynamic bodies. */
+  applyImpulsesToDynamicBodies?: boolean;
+
+  /** The mass of the character controller. */
+  characterMass?: number;
+
+  /** Whether to slide against obstacles. */
+  slideEnabled?: boolean;
+
+  /** The maximum angle (radians) between the floor's normal and the `up` vector that the character is able to climb. */
+  maxSlopeClimbAngle?: number;
+
+  /** The minimum angle (radians) between the floor's normal and the `up` vector before the character starts to slide down automatically. */
+  minSlopeSlideAngle?: number;
+
+  /** The distance threshold for snapping the character to the ground. If set, will enable snap to ground. */
+  snapToGroundDistance?: number;
+
+  /** Configuration for automatic step detection. If set, will enable auto stepping. */
+  autoStepConfig?: {
+    maxHeight: number,
+    minWidth: number,
+    includeDynamicBodies: boolean,
+  }
+}
+
+/**
+ * Scalar physics parameters that can be get/set on physics bodies
+ */
+export enum PhysicsScalarParam {
+    /** Linear damping (0 = no damping, 1 = full damping) */
+    LinearDamping = 'linearDamping',
+    /** Angular damping (0 = no damping, 1 = full damping) */
+    AngularDamping = 'angularDamping',
+    /** Gravity scale multiplier (1 = normal gravity) */
+    GravityScale = 'gravityScale',
+}
+
+/**
+ * Vector physics parameters that can be get/set on physics bodies
+ */
+export enum PhysicsVectorParam {
+    /** Linear velocity vector (m/s) */
+    LinearVelocity = 'linearVelocity',
+    /** Angular velocity vector (rad/s) */
+    AngularVelocity = 'angularVelocity',
+}
+
+export type VectorArray = [/* x */ number, /* y */ number, /* z */ number];
+
+export enum CollisionEventType {
+  Started = 'started',
+  Ended = 'ended',
+}
+
+export interface RawCollisionEvent {
+  /** The first component involved in the collision */
+  componentA: PrimitiveComponent;
+  /** The second component involved in the collision */
+  componentB: PrimitiveComponent;
+  /** The collision point on the first component in world space */
+  pointA: THREE.Vector3 | null;
+  /** The collision normal pointing from A to B */
+  normalA: THREE.Vector3 | null;
+  /** The collision point on the second component in world space */
+  pointB: THREE.Vector3 | null;
+  /** The collision normal pointing from B to A */
+  normalB: THREE.Vector3 | null;
+  /** The relative velocity at the point of impact */
+  relativeVelocity: number | null;
+  /** Whether the collision is a trigger event */
+  isTriggerEvent: boolean;
+  /** The type of collision event */
+  eventType: CollisionEventType;
+}
+
+/**
+ * Contains information about a physics collision between two components
+ */
+export interface CollisionEvent {
+  /** The component that was hit */
+  thisComponent: PrimitiveComponent;
+  /** The component that was hit */
+  otherComponent: PrimitiveComponent;
+  /** The collision point on this component in world space */
+  thisPoint: THREE.Vector3 | null;
+  /** The collision normal pointing from this component to the other component */
+  thisNormal: THREE.Vector3 | null;
+  /** The collision point on the other component in world space */
+  otherPoint: THREE.Vector3 | null;
+  /** The collision normal pointing from the other component to the this component */
+  otherNormal: THREE.Vector3 | null;
+  /** The relative velocity at the point of impact */
+  relativeVelocity: number | null;
+}
+
+/**
+ * Interface for physics engine implementations
+ */
+export interface IPhysicsEngine {
+    /**
+     * Initialize the physics engine
+     * @param options Physics configuration options
+     */
+    create(options: PhysicsOptions): Promise<boolean>;
+
+    /**
+     * Get the physics engine options
+     * @returns Physics engine options
+     */
+    getOptions(): PhysicsOptions | null;
+
+    /**
+     * Clean up and destroy the physics engine
+     */
+    destroy(): void;
+
+    /**
+     * Advance physics simulation by deltaTime
+     * @param deltaTime Time step in seconds
+     */
+    tick(deltaTime: number): void;
+
+    /**
+     * Add a scene component to physics simulation
+     * @param component Component to add
+     * @returns Physics motion type if successful, null otherwise
+     */
+  addComponent(component: PrimitiveComponent): PhysicsMotionType | null;
+
+    /**
+     * Remove a scene component from physics simulation
+     * @param component Component to remove
+     */
+  removeComponent(component: PrimitiveComponent): void;
+
+  /**
+   * Update transform of a physics component from its scene component
+   * @param component Component to update
+   */
+  updateTransform(component: PrimitiveComponent): void;
+
+    /**
+     * Get scalar physics parameter for a component
+     * @param component Target component
+     * @param param Parameter to get
+     * @returns Parameter value or null if not applicable
+     */
+  getScalarParam(component: PrimitiveComponent, param: PhysicsScalarParam): number | null;
+
+    /**
+     * Set scalar physics parameter for a component
+     * @param component Target component
+     * @param param Parameter to set
+     * @param value New parameter value
+     * @returns True if successful, false otherwise
+     */
+  setScalarParam(component: PrimitiveComponent, param: PhysicsScalarParam, value: number): boolean;
+
+    /**
+     * Get vector physics parameter for a component
+     * @param component Target component
+     * @param param Parameter to get
+     * @returns Parameter value as [x,y,z] array or null if not applicable
+     */
+  getVectorParam(component: PrimitiveComponent, param: PhysicsVectorParam): VectorArray | null;
+
+    /**
+     * Set vector physics parameter for a component
+     * @param component Target component
+     * @param param Parameter to set
+     * @param value New parameter value as [x,y,z] array
+     * @returns True if successful, false otherwise
+     */
+  setVectorParam(component: PrimitiveComponent, param: PhysicsVectorParam, value: VectorArray): boolean;
+
+    /**
+     * Clear vector physics parameter for a component
+     * @param component Target component
+     * @param param Parameter to clear
+     * @returns True if successful, false otherwise
+     */
+  clearVectorParam(component: PrimitiveComponent, param: PhysicsVectorParam): boolean;
+
+  /**
+   * Gets all collision events that occurred in the last physics step
+   * @returns Array of collision info objects
+   */
+  getCollisionEvents(): RawCollisionEvent[];
+
+  /**
+   * Clear the stored collision events
+   */
+  clearCollisionEvents(): void;
+
+  /**
+   * Toggles the physics debug renderer visibility
+   * @param enabled Whether the debug renderer should be visible
+   * @returns Whether the debug renderer is now enabled
+   */
+  setDebugRendererEnabled(enabled: boolean): boolean;
+
+  /**
+   * Checks if the physics debug renderer is enabled
+   * @returns Whether the debug renderer is currently enabled, or false if not available
+   */
+  isDebugRendererEnabled(): boolean;
+
+  /* Create a character controller for a scene component
+    * @param component Component to create controller for
+    * @param options Character controller options
+    */
+  createCharacterController(movementComponent: BasePawnMovementComponent, options: CharacterControllerOptions): boolean;
+
+  /**
+   * Remove a character controller for a scene component
+   * @param movementComponent Component to remove controller for
+   */
+  removeCharacterController(movementComponent: BasePawnMovementComponent): void
+
+  /**
+   * 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]
+   * @param ignoreCollision Whether to ignore collisions
+   */
+  computeCharacterMovement(movementComponent: BasePawnMovementComponent, componentToMove: PrimitiveComponent, movement: VectorArray, ignoreCollision: boolean): { isGrounded: boolean };
+
+  // Vehicle controller methods
+
+  /**
+   * Creates a vehicle controller for a scene component
+   * @param movementComponent Component to create vehicle controller for
+   * @param chassisComponent The chassis scene component (usually a MeshComponent)
+   * @returns Vehicle controller interface if successful, null if failed
+   */
+  createVehicle(movementComponent: BasePawnMovementComponent, chassisComponent: PrimitiveComponent): IPhysicsVehicle | null;
+
+  /**
+   * Configure collision filtering between two components
+   * @param componentA First component
+   * @param componentB Second component
+   * @param ignore Whether componentA should ignore collisions with componentB
+   */
+  setComponentCollisionIgnore(componentA: PrimitiveComponent, componentB: PrimitiveComponent, ignore: boolean): boolean;
+
+  /**
+   * 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
+   */
+  createJointFromRecords(type: any, recordA: any, recordB: any, anchorA: any, anchorB: any, axis?: any): string | null;
+
+  /**
+   * Removes a joint from the physics simulation
+   * @param jointId The joint ID returned from createJoint
+   * @returns True if the joint was successfully removed
+   */
+  removeJoint(jointId: string): boolean;
+
+  // Direct physics body management methods (for special cases like ragdolls)
+
+  /**
+   * Create a physics body directly (not tied to a SceneComponent)
+   * @param desc Body descriptor with shape, mass, transform, etc.
+   * @returns Physics body handle if successful, null otherwise
+   */
+  createPhysicsBody(desc: PhysicsBodyDesc): PhysicsBodyHandle | null;
+
+  /**
+   * Remove a physics body from simulation
+   * @param handle Physics body handle
+   * @returns True if successful
+   */
+  removePhysicsBody(handle: PhysicsBodyHandle): boolean;
+
+  /**
+   * Check if a physics body handle is valid
+   * @param handle Physics body handle
+   * @returns True if handle is valid
+   */
+  isValidPhysicsBody(handle: PhysicsBodyHandle): boolean;
+
+  /**
+   * Get world position of a physics body
+   * @param handle Physics body handle
+   * @returns World position or null if invalid handle
+   */
+  getPhysicsBodyPosition(handle: PhysicsBodyHandle): THREE.Vector3 | null;
+
+  /**
+   * Get world rotation of a physics body
+   * @param handle Physics body handle
+   * @returns World rotation or null if invalid handle
+   */
+  getPhysicsBodyRotation(handle: PhysicsBodyHandle): THREE.Quaternion | null;
+
+  /**
+   * Set world position of a physics body
+   * @param handle Physics body handle
+   * @param position New world position
+   * @returns True if successful
+   */
+  setPhysicsBodyPosition(handle: PhysicsBodyHandle, position: THREE.Vector3): boolean;
+
+  /**
+   * Set world rotation of a physics body
+   * @param handle Physics body handle
+   * @param rotation New world rotation
+   * @returns True if successful
+   */
+  setPhysicsBodyRotation(handle: PhysicsBodyHandle, rotation: THREE.Quaternion): boolean;
+
+  /**
+   * Apply an impulse to a physics body
+   * @param handle Physics body handle
+   * @param impulse Impulse vector
+   * @param worldSpace Whether impulse is in world space (default: true)
+   * @returns True if successful
+   */
+  applyImpulseToPhysicsBody(handle: PhysicsBodyHandle, impulse: THREE.Vector3, worldSpace?: boolean): boolean;
+
+  /**
+   * Enable or disable a physics body
+   * @param handle Physics body handle
+   * @param enabled Whether the body should be enabled
+   * @returns True if successful
+   */
+  setPhysicsBodyEnabled(handle: PhysicsBodyHandle, enabled: boolean): boolean;
+
+  /**
+   * Creates a joint between two physics bodies using handles
+   * @param type Joint type
+   * @param bodyA First physics body handle
+   * @param bodyB Second physics body handle
+   * @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
+   */
+  createJointFromBodies(
+      type: any,
+      bodyA: PhysicsBodyHandle,
+      bodyB: PhysicsBodyHandle,
+      anchorA: THREE.Vector3,
+      anchorB: THREE.Vector3,
+      axis?: THREE.Vector3
+  ): string | null;
+
+  /**
+   * Perform a hit test to find the first collider hit
+   * @param options The options for the hit test
+   * @returns The list of hits
+   */
+  performHitTest(options: HitTestOptions): HitTestResult[];
+
+
+    /**
+     * Get the physics state of a scene component
+     * @param component The scene component
+     * @returns The physics state of the component
+     */
+  getComponentState(component: PrimitiveComponent): PrimitiveComponentPhysicsState | null;
+}
+
+/**
+ * Create and initialize a physics engine instance
+ * @param options Physics configuration options
+ * @param world The world instance that owns the physics engine
+ * @returns Promise that resolves to physics engine instance or null if failed
+ */
+export async function createPhysicsEngine(options: PhysicsOptions, world?: any): Promise<IPhysicsEngine | null> {
+  let engine: IPhysicsEngine | null = null;
+  switch (options.engine) {
+    case PhysicsEngine.Rapier:
+      engine = new RapierPhysicsEngine(world);
+      break;
+  }
+  if (engine) {
+    await engine.create(options);
+  }
+  return engine;
+}