@hology/core 0.0.90 → 0.0.91

package/dist/gameplay/actors/camera/third-person-camera-component.js

@@ -1,4 +1,4 @@
-import{__decorate as t,__metadata as e}from"tslib";import{ActorComponent as i,Component as s}from"../component.js";import{Vector3 as o,MathUtils as n,PerspectiveCamera as a}from"three";import{ViewController as r}from"../../services/render.js";import{DecimalInput as h,RestrictedRotationInput as c}from"../../input/index.js";import{PhysicsSystem as d,RayTestResult as m}from"../../services/physics/physics-system.js";import{Parameter as l}from"../../../shader/parameter.js";import{World as p}from"../../services/world.js";import{inject as u}from"../../inject.js";const f=void 0!==window&&/Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);let w=class extends i{constructor(t,e){super(),this.viewController=t,this.physicsSystem=e,this.aspect=this.viewController.htmlElement.clientWidth/this.viewController.htmlElement.clientHeight,this.near=.5,this.far=500,this.viewAngle=f?30:45,this.camera=new a(this.viewAngle,this.aspect,this.near,this.far),this.distance=9,this.minDistance=1.5,this.maxDistance=this.distance,this.height=3,this.offsetX=-1,this.offsetZ=1.5,this.autoActivate=!0,this.bounceBackSpeed=5,this.collisionCheckRadius=.5,this.restrictedDistance=Math.max(this.distance,this.maxDistance),this.rotationInput=new c(-Math.PI/4,Math.PI/2-.7),this.zoomInput=new h(1,0,1),this.offset=new o,this.lookAtOffset=new o(this.offsetX,0,this.offsetZ),this.fixedBehind=!0,this.world=u(p),this.isMouseLocked=!1,this.canvas=null,this.pointerLockInactivatedAt=null,this.onMouseDown=t=>{this.isMouseLocked||this.hideCursor()},this.onKeyDown=t=>{"Escape"===t.key&&this.showCursor()},this.onPointerLockChange=()=>{null!=document.pointerLockElement||null!=document.mozPointerLockElement||this.showCursor()}}async onInit(){this.world.scene.add(this.camera),this.rotationInput.rotation.copy(this.actor.rotation),this.restrictedDistance=Math.max(this.distance,this.maxDistance),this.lookAtOffset.set(this.offsetX,0,this.offsetZ),this.autoActivate&&this.activate()}activate(){this.viewController.setCamera(this.camera);const t=this.element;null!=document.body.requestPointerLock&&(t.addEventListener("mousedown",this.onMouseDown),t.addEventListener("keydown",this.onKeyDown),document.addEventListener("pointerlockchange",this.onPointerLockChange,!1),this.disposed.subscribe((()=>{t.removeEventListener("mousedown",this.onMouseDown),t.removeEventListener("keydown",this.onKeyDown),document.removeEventListener("pointerlockchange",this.onPointerLockChange,!1)})))}onLateUpdate(t){this.setFromRotation(t)}get element(){return this.viewController.htmlElement}hideCursor(){"ontouchstart"in window||navigator.maxTouchPoints>0||navigator.msMaxTouchPoints>0||null!=this.pointerLockInactivatedAt&&performance.now()-this.pointerLockInactivatedAt<1600||(this.element.style.cursor="none",null==this.canvas&&(this.canvas=this.element.getElementsByTagName("canvas")[0]),this.canvas&&(this.canvas.requestPointerLock(),this.isMouseLocked=!0))}showCursor(){this.pointerLockInactivatedAt=performance.now(),this.element.style.cursor="default",window.document.exitPointerLock(),this.isMouseLocked=!1}setFromRotation(t){this.checkForCollision(t);const e=n.clamp(Math.min(this.restrictedDistance,this.distance),Math.min(this.minDistance,this.restrictedDistance),Math.max(this.distance*this.zoomInput.value,this.minDistance)),i=Math.cos(this.rotationInput.rotation.x)*e,s=this.fixedBehind?0:this.rotationInput.rotation.y;this.offset.x=Math.sin(-s)*i,this.offset.y=Math.sin(this.rotationInput.rotation.x)*e+2,this.offset.z=Math.cos(-s)*-i,this.offset.add(this.lookAtOffset),this.updateCameraPosition()}checkForCollision(t){const e=this.getLookAtPosition(),i=y;let s=!1,o=this.distance;const a=new m,r=this.camera.getWorldPosition(g);for(let t=-1;t<=1;t++){const n=k.subVectors(r,e);i.copy(r).add(n.multiplyScalar(1.2)),i.x+=t*this.collisionCheckRadius,this.physicsSystem.rayTest(e,i,a,{debugLifetime:0,excludeActor:this.actor,excludeTriggers:!0}),a.hasHit&&a.distance<this.distance&&(o=Math.min(a.distance,o),s||=a.hasHit)}s||(this.restrictedDistance=n.lerp(this.restrictedDistance,this.distance,n.clamp(this.bounceBackSpeed*t,0,1)))}getLookAtPosition(){const t=v;return t.set(0,0,0),t.y=this.height,t.add(this.lookAtOffset),t.applyMatrix4(this.actor.object.matrixWorld),t}updateCameraPosition(){this.fixedBehind?(this.actor.object.updateWorldMatrix(!0,!1),this.camera.position.set(this.offset.x,this.offset.y,this.offset.z),this.camera.rotation.set(0,0,0),this.camera.scale.set(1,1,1),this.camera.applyMatrix4(this.actor.object.matrix)):this.camera.position.copy(this.actor.position).add(this.offset);const t=this.getLookAtPosition();this.camera.lookAt(t)}};t([l(),e("design:type",Number)],w.prototype,"near",void 0),t([l(),e("design:type",Number)],w.prototype,"far",void 0),t([l(),e("design:type",Number)],w.prototype,"viewAngle",void 0),w=t([s(),e("design:paramtypes",[r,d])],w);export{w as ThirdPersonCameraComponent};const v=new o,y=new o,k=(new o,new o),g=new o;export class ThirdPartyCameraComponent extends w{}
+import{__decorate as t,__metadata as e}from"tslib";import{ActorComponent as i,Component as s}from"../component.js";import{Vector3 as o,MathUtils as n,PerspectiveCamera as a}from"three";import{ViewController as r}from"../../services/render.js";import{DecimalInput as h,RestrictedRotationInput as c}from"../../input/index.js";import{PhysicsSystem as d,RayTestResult as m}from"../../services/physics/physics-system.js";import{Parameter as l}from"../../../shader/parameter.js";import{World as p}from"../../services/world.js";import{inject as u}from"../../inject.js";const f=void 0!==window&&/Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);let w=class extends i{constructor(t,e){super(),this.viewController=t,this.physicsSystem=e,this.aspect=this.viewController.htmlElement.clientWidth/this.viewController.htmlElement.clientHeight,this.near=.5,this.far=500,this.viewAngle=f?30:45,this.camera=new a(this.viewAngle,this.aspect,this.near,this.far),this.distance=9,this.minDistance=1.5,this.maxDistance=this.distance,this.height=3,this.offsetX=-1,this.offsetZ=1.5,this.autoActivate=!0,this.bounceBackSpeed=5,this.collisionCheckRadius=.5,this.restrictedDistance=Math.max(this.distance,this.maxDistance),this.rotationInput=new c(-Math.PI/4,Math.PI/2-.7),this.zoomInput=new h(1,0,1),this.offset=new o,this.lookAtOffset=new o(this.offsetX,0,this.offsetZ),this.fixedBehind=!0,this.world=u(p),this.isMouseLocked=!1,this.canvas=null,this.pointerLockInactivatedAt=null,this.onMouseDown=t=>{this.isMouseLocked||"mouse"!==t.pointerType||this.hideCursor()},this.onKeyDown=t=>{"Escape"===t.key&&this.showCursor()},this.onPointerLockChange=()=>{null!=document.pointerLockElement||null!=document.mozPointerLockElement||this.showCursor()}}async onInit(){this.world.scene.add(this.camera),this.rotationInput.rotation.copy(this.actor.rotation),this.restrictedDistance=Math.max(this.distance,this.maxDistance),this.lookAtOffset.set(this.offsetX,0,this.offsetZ),this.autoActivate&&this.activate()}activate(){this.viewController.setCamera(this.camera);const t=this.element;null!=document.body.requestPointerLock&&(t.addEventListener("pointerdown",this.onMouseDown),t.addEventListener("keydown",this.onKeyDown),document.addEventListener("pointerlockchange",this.onPointerLockChange,!1),this.disposed.subscribe((()=>{t.removeEventListener("pointerdown",this.onMouseDown),t.removeEventListener("keydown",this.onKeyDown),document.removeEventListener("pointerlockchange",this.onPointerLockChange,!1)})))}onLateUpdate(t){this.setFromRotation(t)}get element(){return this.viewController.htmlElement}hideCursor(){null!=this.pointerLockInactivatedAt&&performance.now()-this.pointerLockInactivatedAt<1600||(this.element.style.cursor="none",null==this.canvas&&(this.canvas=this.element.getElementsByTagName("canvas")[0]),this.canvas&&(this.canvas.requestPointerLock(),this.isMouseLocked=!0))}showCursor(){this.pointerLockInactivatedAt=performance.now(),this.element.style.cursor="default",window.document.exitPointerLock(),this.isMouseLocked=!1}setFromRotation(t){this.checkForCollision(t);const e=n.clamp(Math.min(this.restrictedDistance,this.distance),Math.min(this.minDistance,this.restrictedDistance),Math.max(this.distance*this.zoomInput.value,this.minDistance)),i=Math.cos(this.rotationInput.rotation.x)*e,s=this.fixedBehind?0:this.rotationInput.rotation.y;this.offset.x=Math.sin(-s)*i,this.offset.y=Math.sin(this.rotationInput.rotation.x)*e+2,this.offset.z=Math.cos(-s)*-i,this.offset.add(this.lookAtOffset),this.updateCameraPosition()}checkForCollision(t){const e=this.getLookAtPosition(),i=y;let s=!1,o=this.distance;const a=new m,r=this.camera.getWorldPosition(g);for(let t=-1;t<=1;t++){const n=k.subVectors(r,e);i.copy(r).add(n.multiplyScalar(1.2)),i.x+=t*this.collisionCheckRadius,this.physicsSystem.rayTest(e,i,a,{debugLifetime:0,excludeActor:this.actor,excludeTriggers:!0}),a.hasHit&&a.distance<this.distance&&(o=Math.min(a.distance,o),s||=a.hasHit)}s||(this.restrictedDistance=n.lerp(this.restrictedDistance,this.distance,n.clamp(this.bounceBackSpeed*t,0,1)))}getLookAtPosition(){const t=v;return t.set(0,0,0),t.y=this.height,t.add(this.lookAtOffset),t.applyMatrix4(this.actor.object.matrixWorld),t}updateCameraPosition(){this.fixedBehind?(this.actor.object.updateWorldMatrix(!0,!1),this.camera.position.set(this.offset.x,this.offset.y,this.offset.z),this.camera.rotation.set(0,0,0),this.camera.scale.set(1,1,1),this.camera.applyMatrix4(this.actor.object.matrix)):this.camera.position.copy(this.actor.position).add(this.offset);const t=this.getLookAtPosition();this.camera.lookAt(t)}};t([l(),e("design:type",Number)],w.prototype,"near",void 0),t([l(),e("design:type",Number)],w.prototype,"far",void 0),t([l(),e("design:type",Number)],w.prototype,"viewAngle",void 0),w=t([s(),e("design:paramtypes",[r,d])],w);export{w as ThirdPersonCameraComponent};const v=new o,y=new o,k=(new o,new o),g=new o;export class ThirdPartyCameraComponent extends w{}
 /*
  * Copyright (©) 2023. All rights reserved.
  * See the LICENSE.md file for details.

package/dist/gameplay/services/physics/abstract-physics-system.d.ts

@@ -0,0 +1,201 @@
+import { Subject, Observable } from "rxjs";
+import { Vector3, Object3D } from "three";
+import { BaseActor } from "../../actors/actor";
+import { AbstractType } from "../../../utils/type";
+import { CollisionShape } from "../../../index.js";
+import { PhysicsBodyType } from "./physics-system";
+import * as RAPIER from "@dimforge/rapier3d-compat";
+export type ActorPhysicsOptions = {
+    isTrigger: boolean;
+    mass: number;
+    friction: number;
+    continousCollisionDetection: boolean;
+    density: number;
+    restitution: number;
+    type: PhysicsBodyType;
+    ignoreForNavMesh: boolean;
+};
+/**
+ * Abstract base class defining the interface for physics systems.
+ * This allows for different physics engine implementations while maintaining
+ * a consistent interface for game logic.
+ */
+export declare abstract class AbstractPhysicsSystem {
+    /**
+     * Promise that resolves when the physics system is ready
+     */
+    abstract readonly ready: Promise<void>;
+    /**
+     * Event emitted before physics step
+     */
+    abstract readonly beforeStep: Subject<number>;
+    /**
+     * Event emitted after physics step
+     */
+    abstract readonly afterStep: Subject<number>;
+    /**
+     * Controls debug visualization of physics bodies
+     */
+    abstract get showDebug(): boolean;
+    abstract set showDebug(value: boolean);
+    /**
+     * Initializes and starts the physics system
+     */
+    abstract start(): Promise<void>;
+    /**
+     * Renders debug visualization of physics bodies and colliders
+     */
+    abstract renderDebug(): void;
+    /**
+     * Sets the gravity vector for the physics world
+     */
+    abstract setGravity(x: number, y: number, z: number): void;
+    /**
+     * Gets the current gravity vector of the physics world
+     */
+    abstract getGravity(): Vector3;
+    /**
+     * Adds static collision bodies to the physics world based on an existing scene hierarchy
+     */
+    abstract addFromScene(object: Object3D): void;
+    /**
+     * Creates a character controller for physics-based character movement
+     */
+    abstract getCharacterController(offset?: number): RAPIER.KinematicCharacterController;
+    /**
+     * Computes the corrected movement vector for an actor using a character controller
+     */
+    abstract getActorComputedMovement(actor: BaseActor, cc: RAPIER.KinematicCharacterController, desiredTranslation: Vector3, collisionGroup?: number): Vector3;
+    /**
+     * Sets the next kinematic translation for an actor
+     */
+    abstract setNextKinematicTranslation(actor: BaseActor, vel: Vector3): void;
+    /**
+     * Sets the angular velocity of an actor's physics body
+     */
+    abstract setAngularVelocity(actor: BaseActor, velocity: Vector3): void;
+    /**
+     * Sets the linear velocity of an actor's physics body
+     */
+    abstract setLinearVelocity(actor: BaseActor, velocity: Vector3): void;
+    /**
+     * Gets the current linear velocity of an actor's physics body
+     */
+    abstract getLinearVelocity(actor: BaseActor, target?: Vector3): Vector3;
+    /**
+     * Gets the current angular velocity of an actor's physics body
+     */
+    abstract getAngularVelocity(actor: BaseActor, target?: Vector3): Vector3;
+    /**
+     * Sets the linear damping factor for an actor's physics body
+     */
+    abstract setLinearDamping(actor: BaseActor, factor: number): void;
+    /**
+     * Sets the angular damping factor for an actor's physics body
+     */
+    abstract setAngularDamping(actor: BaseActor, factor: number): void;
+    /**
+     * Creates a new character collision object
+     */
+    abstract createCharacterCollision(): RAPIER.CharacterCollision;
+    /**
+     * Adds an actor to the physics world with the specified collision shapes and options
+     */
+    abstract addActor<A extends BaseActor>(actor: A, collisionShapes: CollisionShape[], options?: Partial<ActorPhysicsOptions>): void;
+    /**
+     * Applies a torque to an actor's physics body
+     */
+    abstract applyTorque(actor: BaseActor, torque: Vector3): void;
+    /**
+     * Applies an instantaneous torque impulse to an actor's physics body
+     */
+    abstract applyTorqueImpulse(actor: BaseActor, torqueImpulse: Vector3): void;
+    /**
+     * Resets all accumulated forces on an actor's physics body
+     */
+    abstract resetForces(actor: BaseActor): void;
+    /**
+     * Resets all accumulated torques on an actor's physics body
+     */
+    abstract resetTorques(actor: BaseActor): void;
+    /**
+     * Applies a continuous force to an actor's physics body
+     */
+    abstract applyForce(actor: BaseActor, force: Vector3): void;
+    /**
+     * Applies an instantaneous force impulse to an actor's physics body
+     */
+    abstract applyImpulse(actor: BaseActor, force: Vector3): void;
+    /**
+     * Applies a force at a specific local point on an actor's physics body
+     */
+    abstract applyLocalForce(actor: BaseActor, force: Vector3, localPoint?: Vector3): void;
+    /**
+     * Applies an instantaneous force impulse at a specific local point on an actor's physics body
+     */
+    abstract applyLocalImpulse(actor: BaseActor, force: Vector3, localPoint?: Vector3): void;
+    /**
+     * Removes an actor from the physics world
+     */
+    abstract removeActor(actor: BaseActor): void;
+    /**
+     * Removes physics bodies for objects that have been removed from the scene
+     */
+    abstract removeRemoved(scene: Object3D): void;
+    /**
+     * Removes the physics body for a specific scene object
+     */
+    abstract removeSceneObject(object: Object3D): void;
+    /**
+     * Gets an observable for when an actor begins contact with any object
+     */
+    abstract onBeginContact(self: BaseActor): Observable<number>;
+    /**
+     * Gets an observable for when an actor ends contact with any object
+     */
+    abstract onEndContact(self: BaseActor): Observable<number>;
+    /**
+     * Gets an observable that tracks whether an actor is in contact with any object
+     */
+    abstract onHasContactChanged(self: BaseActor): Observable<boolean>;
+    /**
+     * Gets an observable for when an actor begins overlapping with actors of a specific type
+     */
+    abstract onBeginOverlapWithActorType<T extends BaseActor, A extends BaseActor>(self: T, actorType: AbstractType<A>): Observable<A>;
+    /**
+     * Gets an observable for when an actor ends overlapping with actors of a specific type
+     */
+    abstract onEndOverlapWithActorType<T extends BaseActor, A extends BaseActor>(self: T, actorType: AbstractType<A>): Observable<A>;
+    /**
+     * Gets an observable for when an actor begins overlapping with a specific actor
+     */
+    abstract onBeginOverlapWithActor<T extends BaseActor, A extends BaseActor>(self: T, actor: A): Observable<A>;
+    /**
+     * Gets an observable for when an actor ends overlapping with a specific actor
+     */
+    abstract onEndOverlapWithActor<T extends BaseActor, A extends BaseActor>(self: T, actor: A): Observable<A>;
+    /**
+     * Gets an observable for collision events with a specific actor
+     */
+    abstract onCollisionWithActor<A extends BaseActor, S extends BaseActor>(self: S, actor: A): Observable<A>;
+    /**
+     * Gets an observable for collision events with actors of a specific type
+     */
+    abstract onCollisionWithActorType<A extends BaseActor, S extends BaseActor>(self: S, actorType: AbstractType<A>): Observable<A>;
+    /**
+     * Updates the transform of an actor's physics body to match its visual representation
+     */
+    abstract updateActorTransform(actor: BaseActor): void;
+    /**
+     * Gets the contact points between an actor and other objects in a specific direction
+     */
+    abstract getActorContacts(actor: BaseActor, direction: Vector3): {
+        ri: Vector3;
+        rj: Vector3;
+        ni: Vector3;
+    }[];
+    /**
+     * Stops the physics simulation and cleans up resources
+     */
+    abstract stop(): void;
+}

package/dist/gameplay/services/physics/abstract-physics-system.js

@@ -0,0 +1,5 @@
+export class AbstractPhysicsSystem{}
+/*
+ * Copyright (©) 2023. All rights reserved.
+ * See the LICENSE.md file for details.
+ */

package/dist/gameplay/services/physics/physics-system.d.ts

@@ -1,12 +1,12 @@
 import * as RAPIER from "@dimforge/rapier3d-compat";
 import { Observable, Subject } from "rxjs";
-import * as THREE from "three";
 import { ColorRepresentation, Object3D, Vector3 } from "three";
 import { CollisionShape } from '../../../index.js';
 import { AbstractType } from '../../../utils/type.js';
 import { BaseActor } from '../../actors/actor.js';
 import { ViewController } from '../render.js';
 import { World } from '../world.js';
+import { AbstractPhysicsSystem, ActorPhysicsOptions } from './abstract-physics-system.js';
 export declare class RayTestResult {
     actor?: BaseActor;
     hasHit: boolean;
@@ -27,17 +27,11 @@ export declare enum PhysicsBodyType {
     kinematic = 4,
     kinematicVelocityBased = 8
 }
-export type ActorPhysicsOptions = {
-    isTrigger: boolean;
-    mass: number;
-    friction: number;
-    continousCollisionDetection: boolean;
-    density: number;
-    restitution: number;
-    type: PhysicsBodyType;
-    ignoreForNavMesh: boolean;
-};
-export declare class PhysicsSystem {
+/**
+ * A physics system implementation using the Rapier physics engine.
+ * Handles rigid body physics, collisions, and physics-based character movement.
+ */
+export declare class PhysicsSystem extends AbstractPhysicsSystem {
     viewController: ViewController;
     private gameWorld;
     readonly ready: Promise<void>;
@@ -58,51 +52,209 @@ export declare class PhysicsSystem {
     constructor(viewController: ViewController, gameWorld: World);
     private debugMesh;
     private createDebugMesh;
+    /**
+     * Initializes and starts the physics system.
+     * @returns A promise that resolves when the physics system is ready
+     */
     start(): Promise<void>;
+    /**
+     * Renders debug visualization of physics bodies and colliders.
+     * Only active when showDebug is true.
+     */
     renderDebug(): void;
+    /**
+     * Sets up the physics world and initializes Rapier.
+     * @private
+     */
     private setup;
+    /**
+     * Handles the physics update tick, synchronizing physics bodies with their visual representations.
+     * @private
+     */
     private handleTick;
     /**
-     * Trigger a single step of the physics animation.
-     * This should only be needed if physics is not running but you need
-     * to update the physical bodies.
+     * Updates the physics world state without advancing time.
+     * Used when physics simulation is paused but physics state needs updating.
+     * @private
      */
     private _updateWorld;
+    /**
+     * Updates the physics simulation for the current frame.
+     * @param deltaTime - Time elapsed since last update in seconds
+     * @private
+     */
     private updatePhysics;
+    /**
+     * Performs a raycast test from the camera's perspective.
+     * @param distance - Maximum distance of the raycast
+     * @param result - Optional RayTestResult to store the result
+     * @param options - Optional configuration for the raycast
+     * @returns The result of the raycast test
+     */
     private _raycaster;
     rayTestFromCamera(distance: number, result?: RayTestResult, options?: RayTestOptions): RayTestResult;
     private _reusableResult;
     private _raytestDiff;
     private _raytestDirection;
+    /**
+     * Performs a raycast test between two points in world space.
+     * @param from - Starting point of the ray
+     * @param to - End point of the ray
+     * @param result - Optional RayTestResult to store the result
+     * @param options - Optional configuration for the raycast
+     * @returns The result of the raycast test
+     */
     rayTest(from: Vector3, to: Vector3, result?: RayTestResult, options?: RayTestOptions): RayTestResult;
+    /**
+     * Sets the gravity vector for the physics world.
+     * @param x - Gravity force along X axis
+     * @param y - Gravity force along Y axis
+     * @param z - Gravity force along Z axis
+     */
     setGravity(x: number, y: number, z: number): void;
+    /**
+     * Gets the current gravity vector of the physics world.
+     * @returns The gravity vector
+     */
     getGravity(): Vector3;
     /**
-     * Add static bodies for collision to the world based on an existing scene and contained objects' collision shapes.
+     * Adds static collision bodies to the physics world based on an existing scene hierarchy.
+     * @param object - The root object of the scene to add physics bodies for
      */
     addFromScene(object: Object3D): void;
+    /**
+     * Recursively processes scene objects to add physics bodies.
+     * @param object - The object to process
+     * @private
+     */
     private addRecursively;
+    /**
+     * Creates physics bodies for each instance in an instanced mesh.
+     * @param instancedMesh - The instanced mesh to create bodies for
+     * @param collisionShapes - The collision shapes to use for each instance
+     * @private
+     */
     private createForInstancedMesh;
     private readonly controlledActors;
+    /**
+     * Creates a character controller for physics-based character movement.
+     * @param offset - The skin offset for the character controller
+     * @returns A new kinematic character controller
+     */
     getCharacterController(offset?: number): RAPIER.KinematicCharacterController;
+    /**
+     * Computes the corrected movement vector for an actor using a character controller.
+     * @param actor - The actor to compute movement for
+     * @param cc - The character controller to use
+     * @param desiredTranslation - The desired movement vector
+     * @param collisionGroup - Optional collision group filter
+     * @returns The corrected movement vector accounting for collisions
+     */
     getActorComputedMovement(actor: BaseActor, cc: RAPIER.KinematicCharacterController, desiredTranslation: Vector3, collisionGroup?: number): Vector3;
+    /**
+     * Sets the next kinematic translation for an actor.
+     * @param actor - The actor to update
+     * @param vel - The velocity vector to apply
+     */
     setNextKinematicTranslation(actor: BaseActor, vel: Vector3): void;
+    /**
+     * Sets the angular velocity of an actor's physics body.
+     * @param actor - The actor to update
+     * @param velocity - The angular velocity vector to apply
+     */
     setAngularVelocity(actor: BaseActor, velocity: Vector3): void;
+    /**
+     * Sets the linear velocity of an actor's physics body.
+     * @param actor - The actor to update
+     * @param velocity - The linear velocity vector to apply
+     */
     setLinearVelocity(actor: BaseActor, velocity: Vector3): void;
-    getLinearVelocity(actor: BaseActor, target?: Vector3): THREE.Vector3;
-    getAngularVelocity(actor: BaseActor, target?: Vector3): THREE.Vector3;
+    /**
+     * Gets the current linear velocity of an actor's physics body.
+     * @param actor - The actor to query
+     * @param target - Optional vector to store the result in
+     * @returns The linear velocity vector
+     */
+    getLinearVelocity(actor: BaseActor, target?: Vector3): Vector3;
+    /**
+     * Gets the current angular velocity of an actor's physics body.
+     * @param actor - The actor to query
+     * @param target - Optional vector to store the result in
+     * @returns The angular velocity vector
+     */
+    getAngularVelocity(actor: BaseActor, target?: Vector3): Vector3;
+    /**
+     * Sets the linear damping factor for an actor's physics body.
+     * @param actor - The actor to update
+     * @param factor - The damping factor to apply
+     */
     setLinearDamping(actor: BaseActor, factor: number): void;
+    /**
+     * Sets the angular damping factor for an actor's physics body.
+     * @param actor - The actor to update
+     * @param factor - The damping factor to apply
+     */
     setAngularDamping(actor: BaseActor, factor: number): void;
-    createCharacterCollision(): RAPIER.CharacterCollision;
+    /**
+     * Adds physics bodies for a landscape group.
+     * @param object - The landscape group to add physics for
+     * @private
+     */
     private addLandscapeGroup;
+    /**
+     * Adds an actor to the physics world with the specified collision shapes and options.
+     * @param actor - The actor to add
+     * @param collisionShapes - Array of collision shapes for the actor
+     * @param options - Physics options for the actor
+     */
     addActor<A extends BaseActor>(actor: A, collisionShapes: CollisionShape[], options?: Partial<ActorPhysicsOptions>): void;
+    /**
+     * Applies a torque to an actor's physics body.
+     * @param actor - The actor to apply torque to
+     * @param torque - The torque vector to apply
+     */
     applyTorque(actor: BaseActor, torque: Vector3): void;
+    /**
+     * Applies an instantaneous torque impulse to an actor's physics body.
+     * @param actor - The actor to apply the impulse to
+     * @param torqueImpulse - The torque impulse vector to apply
+     */
     applyTorqueImpulse(actor: BaseActor, torqueImpulse: Vector3): void;
+    /**
+     * Resets all accumulated forces on an actor's physics body.
+     * @param actor - The actor to reset forces for
+     */
     resetForces(actor: BaseActor): void;
+    /**
+     * Resets all accumulated torques on an actor's physics body.
+     * @param actor - The actor to reset torques for
+     */
     resetTorques(actor: BaseActor): void;
+    /**
+     * Applies a continuous force to an actor's physics body.
+     * @param actor - The actor to apply force to
+     * @param force - The force vector to apply
+     */
     applyForce(actor: BaseActor, force: Vector3): void;
+    /**
+     * Applies an instantaneous force impulse to an actor's physics body.
+     * @param actor - The actor to apply the impulse to
+     * @param force - The force impulse vector to apply
+     */
     applyImpulse(actor: BaseActor, force: Vector3): void;
+    /**
+     * Applies a force at a specific local point on an actor's physics body.
+     * @param actor - The actor to apply force to
+     * @param force - The force vector to apply
+     * @param localPoint - The local point at which to apply the force
+     */
     applyLocalForce(actor: BaseActor, force: Vector3, localPoint?: Vector3): void;
+    /**
+     * Applies an instantaneous force impulse at a specific local point on an actor's physics body.
+     * @param actor - The actor to apply the impulse to
+     * @param force - The force impulse vector to apply
+     * @param localPoint - The local point at which to apply the impulse
+     */
     applyLocalImpulse(actor: BaseActor, force: Vector3, localPoint?: Vector3): void;
     /**
      * Apply an impulse on all dynamic physics bodies in the direction away from the given
@@ -112,40 +264,146 @@ export declare class PhysicsSystem {
      * @param forceAmount
      */
     private applyRadiusImpulse;
+    /**
+     * Removes an actor from the physics world.
+     * @param actor - The actor to remove
+     */
     removeActor(actor: BaseActor): void;
+    /**
+     * Removes the physics body for a specific scene object.
+     * @param object - The object to remove physics for
+     */
     removeSceneObject(object: Object3D): void;
+    /**
+     * Activates collision event handling for an actor.
+     * @param actor - The actor to activate events for
+     * @private
+     */
     private activateActorEvents;
+    /**
+     * Gets an observable for collision events between actors.
+     * @param self - The actor to observe collisions for
+     * @param predicate - Function to filter collision events
+     * @param whenStarted - Whether to emit on collision start or end
+     * @returns Observable of colliding actors
+     * @private
+     */
     private _onCollisionWithActorEvent;
     /**
-     * Get a subscription to contact started events where the value of the subscription
-     * is some unique number identifying the object in which the actor is in contact.
+     * Gets an observable for when an actor begins contact with any object.
+     * @param self - The actor to observe contacts for
+     * @returns Observable of contact events
      */
     onBeginContact(self: BaseActor): Observable<number>;
     /**
-     * Get a subscription to contact ended events where the value of the subscription
-     * is some unique number identifying the object in which the actor is in contact.
+     * Gets an observable for when an actor ends contact with any object.
+     * @param self - The actor to observe contacts for
+     * @returns Observable of contact events
      */
     onEndContact(self: BaseActor): Observable<number>;
+    /**
+     * Gets an observable that tracks whether an actor is in contact with any object.
+     * @param self - The actor to track contacts for
+     * @returns Observable boolean indicating contact state
+     */
     onHasContactChanged(self: BaseActor): Observable<boolean>;
+    /**
+     * Gets an observable for when an actor begins overlapping with actors of a specific type.
+     * @param self - The actor to observe overlaps for
+     * @param actorType - The type of actors to detect overlaps with
+     * @returns Observable of overlapping actors
+     */
     onBeginOverlapWithActorType<T extends BaseActor, A extends BaseActor>(self: T, actorType: AbstractType<A>): Observable<A>;
+    /**
+     * Gets an observable for when an actor ends overlapping with actors of a specific type.
+     * @param self - The actor to observe overlaps for
+     * @param actorType - The type of actors to detect overlaps with
+     * @returns Observable of overlapping actors
+     */
     onEndOverlapWithActorType<T extends BaseActor, A extends BaseActor>(self: T, actorType: AbstractType<A>): Observable<A>;
+    /**
+     * Gets an observable for when an actor begins overlapping with a specific actor.
+     * @param self - The actor to observe overlaps for
+     * @param actor - The specific actor to detect overlaps with
+     * @returns Observable of overlap events
+     */
     onBeginOverlapWithActor<T extends BaseActor, A extends BaseActor>(self: T, actor: A): Observable<A>;
+    /**
+     * Gets an observable for when an actor ends overlapping with a specific actor.
+     * @param self - The actor to observe overlaps for
+     * @param actor - The specific actor to detect overlaps with
+     * @returns Observable of overlap events
+     */
     onEndOverlapWithActor<T extends BaseActor, A extends BaseActor>(self: T, actor: A): Observable<A>;
+    /**
+     * Gets an observable for collision events with a specific actor.
+     * @param self - The actor to observe collisions for
+     * @param actor - The specific actor to detect collisions with
+     * @returns Observable of collision events
+     */
     onCollisionWithActor<A extends BaseActor, S extends BaseActor>(self: S, actor: A): Observable<A>;
+    /**
+     * Gets an observable for collision events with actors of a specific type.
+     * @param self - The actor to observe collisions for
+     * @param actorType - The type of actors to detect collisions with
+     * @returns Observable of collision events
+     */
     onCollisionWithActorType<A extends BaseActor, S extends BaseActor>(self: S, actorType: AbstractType<A>): Observable<A>;
+    /**
+     * Updates the transform of an actor's physics body to match its visual representation.
+     * @param actor - The actor to update
+     */
     updateActorTransform(actor: BaseActor): void;
+    /**
+     * Sets up the physics world with default gravity.
+     * @private
+     */
     private setupWorld;
+    /**
+     * Gets the contact points between an actor and other objects in a specific direction.
+     * @param actor - The actor to check contacts for
+     * @param direction - The direction to check in
+     * @returns Array of contact points with position and normal information
+     */
     getActorContacts(actor: BaseActor, direction: Vector3): {
         ri: Vector3;
         rj: Vector3;
         ni: Vector3;
     }[];
+    /**
+     * Stops the physics simulation and cleans up resources.
+     */
     stop(): void;
     /**
-     * Simple body for static scene objects.
+     * Creates a static physics body for a scene object.
+     * @param object - The object to create a body for
+     * @param collisionShapes - The collision shapes to use
+     * @param options - Optional physics settings
+     * @returns The created rigid body
+     * @private
      */
     private createStaticBody;
+    /**
+     * Adds a collision shape to a rigid body.
+     * @param body - The rigid body to add the shape to
+     * @param shapeInfo - The collision shape information
+     * @param object - The object the shape is based on
+     * @returns The created collider
+     * @private
+     */
     private addShape;
+    /**
+     * Creates a Rapier collision shape from shape information and scale.
+     * @param shapeInfo - The collision shape information
+     * @param scale - The scale to apply to the shape
+     * @returns The created collider description
+     * @private
+     */
     private createShape;
+    /**
+     * Creates a new character collision object
+     * @returns A new RAPIER.CharacterCollision instance
+     */
+    createCharacterCollision(): RAPIER.CharacterCollision;
 }
 export {};