424 lines
23 KiB
TypeScript
424 lines
23 KiB
TypeScript
import { RawBroadPhase, RawCCDSolver, RawColliderSet, RawDeserializedWorld, RawIntegrationParameters, RawIslandManager, RawImpulseJointSet, RawMultibodyJointSet, RawNarrowPhase, RawPhysicsPipeline, RawQueryPipeline, RawRigidBodySet, RawSerializationPipeline, RawDebugRenderPipeline } from "../raw";
|
||
import { BroadPhase, Collider, ColliderDesc, ColliderHandle, ColliderSet, InteractionGroups, NarrowPhase, PointColliderProjection, Ray, RayColliderIntersection, RayColliderToi, Shape, ShapeColliderTOI, TempContactManifold } from "../geometry";
|
||
import { CCDSolver, IntegrationParameters, IslandManager, ImpulseJoint, ImpulseJointHandle, MultibodyJoint, MultibodyJointHandle, JointData, ImpulseJointSet, MultibodyJointSet, RigidBody, RigidBodyDesc, RigidBodyHandle, RigidBodySet } from "../dynamics";
|
||
import { Rotation, Vector } from "../math";
|
||
import { PhysicsPipeline } from "./physics_pipeline";
|
||
import { QueryFilterFlags, QueryPipeline } from "./query_pipeline";
|
||
import { SerializationPipeline } from "./serialization_pipeline";
|
||
import { EventQueue } from "./event_queue";
|
||
import { PhysicsHooks } from "./physics_hooks";
|
||
import { DebugRenderBuffers, DebugRenderPipeline } from "./debug_render_pipeline";
|
||
import { KinematicCharacterController } from "../control";
|
||
import { DynamicRayCastVehicleController } from "../control";
|
||
/**
|
||
* The physics world.
|
||
*
|
||
* This contains all the data-structures necessary for creating and simulating
|
||
* bodies with contacts, joints, and external forces.
|
||
*/
|
||
export declare class World {
|
||
gravity: Vector;
|
||
integrationParameters: IntegrationParameters;
|
||
islands: IslandManager;
|
||
broadPhase: BroadPhase;
|
||
narrowPhase: NarrowPhase;
|
||
bodies: RigidBodySet;
|
||
colliders: ColliderSet;
|
||
impulseJoints: ImpulseJointSet;
|
||
multibodyJoints: MultibodyJointSet;
|
||
ccdSolver: CCDSolver;
|
||
queryPipeline: QueryPipeline;
|
||
physicsPipeline: PhysicsPipeline;
|
||
serializationPipeline: SerializationPipeline;
|
||
debugRenderPipeline: DebugRenderPipeline;
|
||
characterControllers: Set<KinematicCharacterController>;
|
||
vehicleControllers: Set<DynamicRayCastVehicleController>;
|
||
/**
|
||
* Release the WASM memory occupied by this physics world.
|
||
*
|
||
* All the fields of this physics world will be freed as well,
|
||
* so there is no need to call their `.free()` methods individually.
|
||
*/
|
||
free(): void;
|
||
constructor(gravity: Vector, rawIntegrationParameters?: RawIntegrationParameters, rawIslands?: RawIslandManager, rawBroadPhase?: RawBroadPhase, rawNarrowPhase?: RawNarrowPhase, rawBodies?: RawRigidBodySet, rawColliders?: RawColliderSet, rawImpulseJoints?: RawImpulseJointSet, rawMultibodyJoints?: RawMultibodyJointSet, rawCCDSolver?: RawCCDSolver, rawQueryPipeline?: RawQueryPipeline, rawPhysicsPipeline?: RawPhysicsPipeline, rawSerializationPipeline?: RawSerializationPipeline, rawDebugRenderPipeline?: RawDebugRenderPipeline);
|
||
static fromRaw(raw: RawDeserializedWorld): World;
|
||
/**
|
||
* Takes a snapshot of this world.
|
||
*
|
||
* Use `World.restoreSnapshot` to create a new physics world with a state identical to
|
||
* the state when `.takeSnapshot()` is called.
|
||
*/
|
||
takeSnapshot(): Uint8Array;
|
||
/**
|
||
* Creates a new physics world from a snapshot.
|
||
*
|
||
* This new physics world will be an identical copy of the snapshoted physics world.
|
||
*/
|
||
static restoreSnapshot(data: Uint8Array): World;
|
||
/**
|
||
* Computes all the lines (and their colors) needed to render the scene.
|
||
*/
|
||
debugRender(): DebugRenderBuffers;
|
||
/**
|
||
* Advance the simulation by one time step.
|
||
*
|
||
* All events generated by the physics engine are ignored.
|
||
*
|
||
* @param EventQueue - (optional) structure responsible for collecting
|
||
* events generated by the physics engine.
|
||
*/
|
||
step(eventQueue?: EventQueue, hooks?: PhysicsHooks): void;
|
||
/**
|
||
* Update colliders positions after rigid-bodies moved.
|
||
*
|
||
* When a rigid-body moves, the positions of the colliders attached to it need to be updated. This update is
|
||
* generally automatically done at the beginning and the end of each simulation step with World.step.
|
||
* If the positions need to be updated without running a simulation step this method can be called manually.
|
||
*/
|
||
propagateModifiedBodyPositionsToColliders(): void;
|
||
/**
|
||
* Ensure subsequent scene queries take into account the collider positions set before this method is called.
|
||
*
|
||
* This does not step the physics simulation forward.
|
||
*/
|
||
updateSceneQueries(): void;
|
||
/**
|
||
* The current simulation timestep.
|
||
*/
|
||
get timestep(): number;
|
||
/**
|
||
* Sets the new simulation timestep.
|
||
*
|
||
* The simulation timestep governs by how much the physics state of the world will
|
||
* be integrated. A simulation timestep should:
|
||
* - be as small as possible. Typical values evolve around 0.016 (assuming the chosen unit is milliseconds,
|
||
* corresponds to the time between two frames of a game running at 60FPS).
|
||
* - not vary too much during the course of the simulation. A timestep with large variations may
|
||
* cause instabilities in the simulation.
|
||
*
|
||
* @param dt - The timestep length, in seconds.
|
||
*/
|
||
set timestep(dt: number);
|
||
/**
|
||
* The number of solver iterations run by the constraints solver for calculating forces (default: `4`).
|
||
*/
|
||
get numSolverIterations(): number;
|
||
/**
|
||
* Sets the number of solver iterations run by the constraints solver for calculating forces (default: `4`).
|
||
*
|
||
* The greater this value is, the most rigid and realistic the physics simulation will be.
|
||
* However a greater number of iterations is more computationally intensive.
|
||
*
|
||
* @param niter - The new number of solver iterations.
|
||
*/
|
||
set numSolverIterations(niter: number);
|
||
/**
|
||
* Number of addition friction resolution iteration run during the last solver sub-step (default: `4`).
|
||
*/
|
||
get numAdditionalFrictionIterations(): number;
|
||
/**
|
||
* Sets the number of addition friction resolution iteration run during the last solver sub-step (default: `4`).
|
||
*
|
||
* The greater this value is, the most realistic friction will be.
|
||
* However a greater number of iterations is more computationally intensive.
|
||
*
|
||
* @param niter - The new number of additional friction iterations.
|
||
*/
|
||
set numAdditionalFrictionIterations(niter: number);
|
||
/**
|
||
* Number of internal Project Gauss Seidel (PGS) iterations run at each solver iteration (default: `1`).
|
||
*/
|
||
get numInternalPgsIterations(): number;
|
||
/**
|
||
* Sets the Number of internal Project Gauss Seidel (PGS) iterations run at each solver iteration (default: `1`).
|
||
*
|
||
* Increasing this parameter will improve stability of the simulation. It will have a lesser effect than
|
||
* increasing `numSolverIterations` but is also less computationally expensive.
|
||
*
|
||
* @param niter - The new number of internal PGS iterations.
|
||
*/
|
||
set numInternalPgsIterations(niter: number);
|
||
switchToStandardPgsSolver(): void;
|
||
switchToSmallStepsPgsSolver(): void;
|
||
/**
|
||
* Creates a new rigid-body from the given rigid-body descriptor.
|
||
*
|
||
* @param body - The description of the rigid-body to create.
|
||
*/
|
||
createRigidBody(body: RigidBodyDesc): RigidBody;
|
||
/**
|
||
* Creates a new character controller.
|
||
*
|
||
* @param offset - The artificial gap added between the character’s chape and its environment.
|
||
*/
|
||
createCharacterController(offset: number): KinematicCharacterController;
|
||
/**
|
||
* Removes a character controller from this world.
|
||
*
|
||
* @param controller - The character controller to remove.
|
||
*/
|
||
removeCharacterController(controller: KinematicCharacterController): void;
|
||
/**
|
||
* Creates a new vehicle controller.
|
||
*
|
||
* @param chassis - The rigid-body used as the chassis of the vehicle controller. When the vehicle
|
||
* controller is updated, it will change directly the rigid-body’s velocity. This
|
||
* rigid-body must be a dynamic or kinematic-velocity-based rigid-body.
|
||
*/
|
||
createVehicleController(chassis: RigidBody): DynamicRayCastVehicleController;
|
||
/**
|
||
* Removes a vehicle controller from this world.
|
||
*
|
||
* @param controller - The vehicle controller to remove.
|
||
*/
|
||
removeVehicleController(controller: DynamicRayCastVehicleController): void;
|
||
/**
|
||
* Creates a new collider.
|
||
*
|
||
* @param desc - The description of the collider.
|
||
* @param parent - The rigid-body this collider is attached to.
|
||
*/
|
||
createCollider(desc: ColliderDesc, parent?: RigidBody): Collider;
|
||
/**
|
||
* Creates a new impulse joint from the given joint descriptor.
|
||
*
|
||
* @param params - The description of the joint to create.
|
||
* @param parent1 - The first rigid-body attached to this joint.
|
||
* @param parent2 - The second rigid-body attached to this joint.
|
||
* @param wakeUp - Should the attached rigid-bodies be awakened?
|
||
*/
|
||
createImpulseJoint(params: JointData, parent1: RigidBody, parent2: RigidBody, wakeUp: boolean): ImpulseJoint;
|
||
/**
|
||
* Creates a new multibody joint from the given joint descriptor.
|
||
*
|
||
* @param params - The description of the joint to create.
|
||
* @param parent1 - The first rigid-body attached to this joint.
|
||
* @param parent2 - The second rigid-body attached to this joint.
|
||
* @param wakeUp - Should the attached rigid-bodies be awakened?
|
||
*/
|
||
createMultibodyJoint(params: JointData, parent1: RigidBody, parent2: RigidBody, wakeUp: boolean): MultibodyJoint;
|
||
/**
|
||
* Retrieves a rigid-body from its handle.
|
||
*
|
||
* @param handle - The integer handle of the rigid-body to retrieve.
|
||
*/
|
||
getRigidBody(handle: RigidBodyHandle): RigidBody;
|
||
/**
|
||
* Retrieves a collider from its handle.
|
||
*
|
||
* @param handle - The integer handle of the collider to retrieve.
|
||
*/
|
||
getCollider(handle: ColliderHandle): Collider;
|
||
/**
|
||
* Retrieves an impulse joint from its handle.
|
||
*
|
||
* @param handle - The integer handle of the impulse joint to retrieve.
|
||
*/
|
||
getImpulseJoint(handle: ImpulseJointHandle): ImpulseJoint;
|
||
/**
|
||
* Retrieves an multibody joint from its handle.
|
||
*
|
||
* @param handle - The integer handle of the multibody joint to retrieve.
|
||
*/
|
||
getMultibodyJoint(handle: MultibodyJointHandle): MultibodyJoint;
|
||
/**
|
||
* Removes the given rigid-body from this physics world.
|
||
*
|
||
* This will remove this rigid-body as well as all its attached colliders and joints.
|
||
* Every other bodies touching or attached by joints to this rigid-body will be woken-up.
|
||
*
|
||
* @param body - The rigid-body to remove.
|
||
*/
|
||
removeRigidBody(body: RigidBody): void;
|
||
/**
|
||
* Removes the given collider from this physics world.
|
||
*
|
||
* @param collider - The collider to remove.
|
||
* @param wakeUp - If set to `true`, the rigid-body this collider is attached to will be awaken.
|
||
*/
|
||
removeCollider(collider: Collider, wakeUp: boolean): void;
|
||
/**
|
||
* Removes the given impulse joint from this physics world.
|
||
*
|
||
* @param joint - The impulse joint to remove.
|
||
* @param wakeUp - If set to `true`, the rigid-bodies attached by this joint will be awaken.
|
||
*/
|
||
removeImpulseJoint(joint: ImpulseJoint, wakeUp: boolean): void;
|
||
/**
|
||
* Removes the given multibody joint from this physics world.
|
||
*
|
||
* @param joint - The multibody joint to remove.
|
||
* @param wakeUp - If set to `true`, the rigid-bodies attached by this joint will be awaken.
|
||
*/
|
||
removeMultibodyJoint(joint: MultibodyJoint, wakeUp: boolean): void;
|
||
/**
|
||
* Applies the given closure to each collider managed by this physics world.
|
||
*
|
||
* @param f(collider) - The function to apply to each collider managed by this physics world. Called as `f(collider)`.
|
||
*/
|
||
forEachCollider(f: (collider: Collider) => void): void;
|
||
/**
|
||
* Applies the given closure to each rigid-body managed by this physics world.
|
||
*
|
||
* @param f(body) - The function to apply to each rigid-body managed by this physics world. Called as `f(collider)`.
|
||
*/
|
||
forEachRigidBody(f: (body: RigidBody) => void): void;
|
||
/**
|
||
* Applies the given closure to each active rigid-body managed by this physics world.
|
||
*
|
||
* After a short time of inactivity, a rigid-body is automatically deactivated ("asleep") by
|
||
* the physics engine in order to save computational power. A sleeping rigid-body never moves
|
||
* unless it is moved manually by the user.
|
||
*
|
||
* @param f - The function to apply to each active rigid-body managed by this physics world. Called as `f(collider)`.
|
||
*/
|
||
forEachActiveRigidBody(f: (body: RigidBody) => void): void;
|
||
/**
|
||
* Find the closest intersection between a ray and the physics world.
|
||
*
|
||
* @param ray - The ray to cast.
|
||
* @param maxToi - The maximum time-of-impact that can be reported by this cast. This effectively
|
||
* limits the length of the ray to `ray.dir.norm() * maxToi`.
|
||
* @param solid - If `false` then the ray will attempt to hit the boundary of a shape, even if its
|
||
* origin already lies inside of a shape. In other terms, `true` implies that all shapes are plain,
|
||
* whereas `false` implies that all shapes are hollow for this ray-cast.
|
||
* @param groups - Used to filter the colliders that can or cannot be hit by the ray.
|
||
* @param filter - The callback to filter out which collider will be hit.
|
||
*/
|
||
castRay(ray: Ray, maxToi: number, solid: boolean, filterFlags?: QueryFilterFlags, filterGroups?: InteractionGroups, filterExcludeCollider?: Collider, filterExcludeRigidBody?: RigidBody, filterPredicate?: (collider: Collider) => boolean): RayColliderToi | null;
|
||
/**
|
||
* Find the closest intersection between a ray and the physics world.
|
||
*
|
||
* This also computes the normal at the hit point.
|
||
* @param ray - The ray to cast.
|
||
* @param maxToi - The maximum time-of-impact that can be reported by this cast. This effectively
|
||
* limits the length of the ray to `ray.dir.norm() * maxToi`.
|
||
* @param solid - If `false` then the ray will attempt to hit the boundary of a shape, even if its
|
||
* origin already lies inside of a shape. In other terms, `true` implies that all shapes are plain,
|
||
* whereas `false` implies that all shapes are hollow for this ray-cast.
|
||
* @param groups - Used to filter the colliders that can or cannot be hit by the ray.
|
||
*/
|
||
castRayAndGetNormal(ray: Ray, maxToi: number, solid: boolean, filterFlags?: QueryFilterFlags, filterGroups?: InteractionGroups, filterExcludeCollider?: Collider, filterExcludeRigidBody?: RigidBody, filterPredicate?: (collider: Collider) => boolean): RayColliderIntersection | null;
|
||
/**
|
||
* Cast a ray and collects all the intersections between a ray and the scene.
|
||
*
|
||
* @param ray - The ray to cast.
|
||
* @param maxToi - The maximum time-of-impact that can be reported by this cast. This effectively
|
||
* limits the length of the ray to `ray.dir.norm() * maxToi`.
|
||
* @param solid - If `false` then the ray will attempt to hit the boundary of a shape, even if its
|
||
* origin already lies inside of a shape. In other terms, `true` implies that all shapes are plain,
|
||
* whereas `false` implies that all shapes are hollow for this ray-cast.
|
||
* @param groups - Used to filter the colliders that can or cannot be hit by the ray.
|
||
* @param callback - The callback called once per hit (in no particular order) between a ray and a collider.
|
||
* If this callback returns `false`, then the cast will stop and no further hits will be detected/reported.
|
||
*/
|
||
intersectionsWithRay(ray: Ray, maxToi: number, solid: boolean, callback: (intersect: RayColliderIntersection) => boolean, filterFlags?: QueryFilterFlags, filterGroups?: InteractionGroups, filterExcludeCollider?: Collider, filterExcludeRigidBody?: RigidBody, filterPredicate?: (collider: Collider) => boolean): void;
|
||
/**
|
||
* Gets the handle of up to one collider intersecting the given shape.
|
||
*
|
||
* @param shapePos - The position of the shape used for the intersection test.
|
||
* @param shapeRot - The orientation of the shape used for the intersection test.
|
||
* @param shape - The shape used for the intersection test.
|
||
* @param groups - The bit groups and filter associated to the ray, in order to only
|
||
* hit the colliders with collision groups compatible with the ray's group.
|
||
*/
|
||
intersectionWithShape(shapePos: Vector, shapeRot: Rotation, shape: Shape, filterFlags?: QueryFilterFlags, filterGroups?: InteractionGroups, filterExcludeCollider?: Collider, filterExcludeRigidBody?: RigidBody, filterPredicate?: (collider: Collider) => boolean): Collider | null;
|
||
/**
|
||
* Find the projection of a point on the closest collider.
|
||
*
|
||
* @param point - The point to project.
|
||
* @param solid - If this is set to `true` then the collider shapes are considered to
|
||
* be plain (if the point is located inside of a plain shape, its projection is the point
|
||
* itself). If it is set to `false` the collider shapes are considered to be hollow
|
||
* (if the point is located inside of an hollow shape, it is projected on the shape's
|
||
* boundary).
|
||
* @param groups - The bit groups and filter associated to the point to project, in order to only
|
||
* project on colliders with collision groups compatible with the ray's group.
|
||
*/
|
||
projectPoint(point: Vector, solid: boolean, filterFlags?: QueryFilterFlags, filterGroups?: InteractionGroups, filterExcludeCollider?: Collider, filterExcludeRigidBody?: RigidBody, filterPredicate?: (collider: Collider) => boolean): PointColliderProjection | null;
|
||
/**
|
||
* Find the projection of a point on the closest collider.
|
||
*
|
||
* @param point - The point to project.
|
||
* @param groups - The bit groups and filter associated to the point to project, in order to only
|
||
* project on colliders with collision groups compatible with the ray's group.
|
||
*/
|
||
projectPointAndGetFeature(point: Vector, filterFlags?: QueryFilterFlags, filterGroups?: InteractionGroups, filterExcludeCollider?: Collider, filterExcludeRigidBody?: RigidBody, filterPredicate?: (collider: Collider) => boolean): PointColliderProjection | null;
|
||
/**
|
||
* Find all the colliders containing the given point.
|
||
*
|
||
* @param point - The point used for the containment test.
|
||
* @param groups - The bit groups and filter associated to the point to test, in order to only
|
||
* test on colliders with collision groups compatible with the ray's group.
|
||
* @param callback - A function called with the handles of each collider with a shape
|
||
* containing the `point`.
|
||
*/
|
||
intersectionsWithPoint(point: Vector, callback: (handle: Collider) => boolean, filterFlags?: QueryFilterFlags, filterGroups?: InteractionGroups, filterExcludeCollider?: Collider, filterExcludeRigidBody?: RigidBody, filterPredicate?: (collider: Collider) => boolean): void;
|
||
/**
|
||
* Casts a shape at a constant linear velocity and retrieve the first collider it hits.
|
||
* This is similar to ray-casting except that we are casting a whole shape instead of
|
||
* just a point (the ray origin).
|
||
*
|
||
* @param shapePos - The initial position of the shape to cast.
|
||
* @param shapeRot - The initial rotation of the shape to cast.
|
||
* @param shapeVel - The constant velocity of the shape to cast (i.e. the cast direction).
|
||
* @param shape - The shape to cast.
|
||
* @param maxToi - The maximum time-of-impact that can be reported by this cast. This effectively
|
||
* limits the distance traveled by the shape to `shapeVel.norm() * maxToi`.
|
||
* @param stopAtPenetration - If set to `false`, the linear shape-cast won’t immediately stop if
|
||
* the shape is penetrating another shape at its starting point **and** its trajectory is such
|
||
* that it’s on a path to exist that penetration state.
|
||
* @param groups - The bit groups and filter associated to the shape to cast, in order to only
|
||
* test on colliders with collision groups compatible with this group.
|
||
*/
|
||
castShape(shapePos: Vector, shapeRot: Rotation, shapeVel: Vector, shape: Shape, maxToi: number, stopAtPenetration: boolean, filterFlags?: QueryFilterFlags, filterGroups?: InteractionGroups, filterExcludeCollider?: Collider, filterExcludeRigidBody?: RigidBody, filterPredicate?: (collider: Collider) => boolean): ShapeColliderTOI | null;
|
||
/**
|
||
* Retrieve all the colliders intersecting the given shape.
|
||
*
|
||
* @param shapePos - The position of the shape to test.
|
||
* @param shapeRot - The orientation of the shape to test.
|
||
* @param shape - The shape to test.
|
||
* @param groups - The bit groups and filter associated to the shape to test, in order to only
|
||
* test on colliders with collision groups compatible with this group.
|
||
* @param callback - A function called with the handles of each collider intersecting the `shape`.
|
||
*/
|
||
intersectionsWithShape(shapePos: Vector, shapeRot: Rotation, shape: Shape, callback: (collider: Collider) => boolean, filterFlags?: QueryFilterFlags, filterGroups?: InteractionGroups, filterExcludeCollider?: Collider, filterExcludeRigidBody?: RigidBody, filterPredicate?: (collider: Collider) => boolean): void;
|
||
/**
|
||
* Finds the handles of all the colliders with an AABB intersecting the given AABB.
|
||
*
|
||
* @param aabbCenter - The center of the AABB to test.
|
||
* @param aabbHalfExtents - The half-extents of the AABB to test.
|
||
* @param callback - The callback that will be called with the handles of all the colliders
|
||
* currently intersecting the given AABB.
|
||
*/
|
||
collidersWithAabbIntersectingAabb(aabbCenter: Vector, aabbHalfExtents: Vector, callback: (handle: Collider) => boolean): void;
|
||
/**
|
||
* Enumerates all the colliders potentially in contact with the given collider.
|
||
*
|
||
* @param collider1 - The second collider involved in the contact.
|
||
* @param f - Closure that will be called on each collider that is in contact with `collider1`.
|
||
*/
|
||
contactPairsWith(collider1: Collider, f: (collider2: Collider) => void): void;
|
||
/**
|
||
* Enumerates all the colliders intersecting the given colliders, assuming one of them
|
||
* is a sensor.
|
||
*/
|
||
intersectionPairsWith(collider1: Collider, f: (collider2: Collider) => void): void;
|
||
/**
|
||
* Iterates through all the contact manifolds between the given pair of colliders.
|
||
*
|
||
* @param collider1 - The first collider involved in the contact.
|
||
* @param collider2 - The second collider involved in the contact.
|
||
* @param f - Closure that will be called on each contact manifold between the two colliders. If the second argument
|
||
* passed to this closure is `true`, then the contact manifold data is flipped, i.e., methods like `localNormal1`
|
||
* actually apply to the `collider2` and fields like `localNormal2` apply to the `collider1`.
|
||
*/
|
||
contactPair(collider1: Collider, collider2: Collider, f: (manifold: TempContactManifold, flipped: boolean) => void): void;
|
||
/**
|
||
* Returns `true` if `collider1` and `collider2` intersect and at least one of them is a sensor.
|
||
* @param collider1 − The first collider involved in the intersection.
|
||
* @param collider2 − The second collider involved in the intersection.
|
||
*/
|
||
intersectionPair(collider1: Collider, collider2: Collider): boolean;
|
||
}
|