@babylonjs/core
Version:
Getting started? Play directly with the Babylon.js API using our [playground](https://playground.babylonjs.com/). It also contains a lot of samples to learn how to use it.
424 lines (423 loc) • 22.3 kB
TypeScript
import type { IBasePhysicsCollisionEvent, IPhysicsCollisionEvent, PhysicsMassProperties } from "./IPhysicsEnginePlugin.js";
import { PhysicsMotionType, PhysicsPrestepType } from "./IPhysicsEnginePlugin.js";
import type { PhysicsShape } from "./physicsShape.js";
import { Vector3, Quaternion } from "../../Maths/math.vector.js";
import type { Scene } from "../../scene.js";
import type { Nullable } from "../../types.js";
import type { PhysicsConstraint } from "./physicsConstraint.js";
import type { Bone } from "../../Bones/bone.js";
import type { Observable } from "../../Misc/observable.js";
import type { AbstractMesh } from "../../Meshes/abstractMesh.js";
import type { TransformNode } from "../../Meshes/transformNode.js";
import type { BoundingBox } from "../../Culling/boundingBox.js";
/**
* PhysicsBody is useful for creating a physics body that can be used in a physics engine. It allows
* the user to set the mass and velocity of the body, which can then be used to calculate the
* motion of the body in the physics engine.
*/
export declare class PhysicsBody {
/**
* V2 Physics plugin private data for single Transform
*/
_pluginData: any;
/**
* V2 Physics plugin private data for instances
*/
_pluginDataInstances: Array<any>;
/**
* The V2 plugin used to create and manage this Physics Body
*/
private _physicsPlugin;
/**
* The engine used to create and manage this Physics Body
*/
private _physicsEngine;
/**
* If the collision callback is enabled
*/
private _collisionCBEnabled;
/**
* If the collision ended callback is enabled
*/
private _collisionEndedCBEnabled;
/**
* The transform node associated with this Physics Body
*/
transformNode: TransformNode;
/**
* Disable pre-step that consists in updating Physics Body from Transform Node Translation/Orientation.
* True by default for maximum performance.
*/
get disablePreStep(): boolean;
set disablePreStep(value: boolean);
/**
* Disable sync from physics to transformNode. This value is set to true at body creation or at motionType setting when the body is not dynamic.
*/
disableSync: boolean;
/**
* Physics engine will try to make this body sleeping and not active
*/
startAsleep: boolean;
private _nodeDisposeObserver;
private _isDisposed;
private _shape;
private _prestepType;
/**
* Constructs a new physics body for the given node.
* @param transformNode - The Transform Node to construct the physics body for. For better performance, it is advised that this node does not have a parent.
* @param motionType - The motion type of the physics body. The options are:
* - PhysicsMotionType.STATIC - Static bodies are not moving and unaffected by forces or collisions. They are good for level boundaries or terrain.
* - PhysicsMotionType.DYNAMIC - Dynamic bodies are fully simulated. They can move and collide with other objects.
* - PhysicsMotionType.ANIMATED - They behave like dynamic bodies, but they won't be affected by other bodies, but still push other bodies out of the way.
* @param startsAsleep - Whether the physics body should start in a sleeping state (not a guarantee). Defaults to false.
* @param scene - The scene containing the physics engine.
*
* This code is useful for creating a physics body for a given Transform Node in a scene.
* It checks the version of the physics engine and the physics plugin, and initializes the body accordingly.
* It also sets the node's rotation quaternion if it is not already set. Finally, it adds the body to the physics engine.
*/
constructor(transformNode: TransformNode, motionType: PhysicsMotionType, startsAsleep: boolean, scene: Scene);
/**
* Returns the string "PhysicsBody".
* @returns "PhysicsBody"
*/
getClassName(): string;
/**
* Clone the PhysicsBody to a new body and assign it to the transformNode parameter
* @param transformNode transformNode that will be used for the cloned PhysicsBody
* @returns the newly cloned PhysicsBody
*/
clone(transformNode: TransformNode): PhysicsBody;
/**
* If a physics body is connected to an instanced node, update the number physic instances to match the number of node instances.
*/
updateBodyInstances(): void;
/**
* This returns the number of internal instances of the physics body
*/
get numInstances(): number;
/**
* Get the motion type of the physics body. Can be STATIC, DYNAMIC, or ANIMATED.
*/
get motionType(): PhysicsMotionType;
/**
* Sets the shape of the physics body.
* @param shape - The shape of the physics body.
*
* This method is useful for setting the shape of the physics body, which is necessary for the physics engine to accurately simulate the body's behavior.
* The shape is used to calculate the body's mass, inertia, and other properties.
*/
set shape(shape: Nullable<PhysicsShape>);
/**
* Retrieves the physics shape associated with this object.
*
* @returns The physics shape associated with this object, or `undefined` if no
* shape is associated.
*
* This method is useful for retrieving the physics shape associated with this object,
* which can be used to apply physical forces to the object or to detect collisions.
*/
get shape(): Nullable<PhysicsShape>;
/**
* Returns the bounding box of the physics body.
* @returns The bounding box of the physics body.
*/
getBoundingBox(): BoundingBox;
/**
* Sets the event mask for the physics engine.
*
* @param eventMask - A bitmask that determines which events will be sent to the physics engine.
* @param instanceIndex - If this body is instanced, the index of the instance to set the event mask for.
*
* This method is useful for setting the event mask for the physics engine, which determines which events
* will be sent to the physics engine. This allows the user to control which events the physics engine will respond to.
*/
setEventMask(eventMask: number, instanceIndex?: number): void;
/**
* Gets the event mask of the physics engine.
* @param instanceIndex - If this body is instanced, the index of the instance to get the event mask for.
* @returns The event mask of the physics engine.
*
* This method is useful for getting the event mask of the physics engine,
* which is used to determine which events the engine will respond to.
* This is important for ensuring that the engine is responding to the correct events and not
* wasting resources on unnecessary events.
*/
getEventMask(instanceIndex?: number): number;
/**
* Sets the motion type of the physics body. Can be STATIC, DYNAMIC, or ANIMATED.
* @param motionType - The motion type to set.
* @param instanceIndex - If this body is instanced, the index of the instance to set the motion type for. If body is instanced but instanceIndex is undefined, the motion type will be set for all instances.
*/
setMotionType(motionType: PhysicsMotionType, instanceIndex?: number): void;
/**
* Gets the motion type of the physics body. Can be STATIC, DYNAMIC, or ANIMATED.
* @param instanceIndex - If this body is instanced, the index of the instance to get the motion type for.
* @returns The motion type of the physics body.
*/
getMotionType(instanceIndex?: number): PhysicsMotionType;
/**
* Set the prestep type of the body
* @param prestepType prestep type provided by PhysicsPrestepType
*/
setPrestepType(prestepType: PhysicsPrestepType): void;
/**
* Get the current prestep type of the body
* @returns the type of prestep associated with the body and its instance index
*/
getPrestepType(): PhysicsPrestepType;
/**
* Computes the mass properties of the physics object, based on the set of physics shapes this body uses.
* This method is useful for computing the initial mass properties of a physics object, such as its mass,
* inertia, and center of mass; these values are important for accurately simulating the physics of the
* object in the physics engine, and computing values based on the shape will provide you with reasonable
* initial values, which you can then customize.
* @param instanceIndex - The index of the instance to compute the mass properties for.
* @returns The mass properties of the object.
*/
computeMassProperties(instanceIndex?: number): PhysicsMassProperties;
/**
* Sets the mass properties of the physics object.
*
* @param massProps - The mass properties to set.
* @param instanceIndex - The index of the instance to set the mass properties for. If not defined, the mass properties will be set for all instances.
*
* This method is useful for setting the mass properties of a physics object, such as its mass,
* inertia, and center of mass. This is important for accurately simulating the physics of the object in the physics engine.
*/
setMassProperties(massProps: PhysicsMassProperties, instanceIndex?: number): void;
/**
* Retrieves the mass properties of the object.
* @param instanceIndex - If this body is instanced, the index of the instance to get the mass properties for.
* @returns The mass properties of the object.
*
* This method is useful for physics simulations, as it allows the user to
* retrieve the mass properties of the object, such as its mass, center of mass,
* and moment of inertia. This information is necessary for accurate physics
* simulations.
*/
getMassProperties(instanceIndex?: number): PhysicsMassProperties;
/**
* Sets the linear damping of the physics body.
*
* @param damping - The linear damping value.
* @param instanceIndex - If this body is instanced, the index of the instance to set the linear damping for.
*
* This method is useful for controlling the linear damping of the physics body,
* which is the rate at which the body's velocity decreases over time. This is useful for simulating
* the effects of air resistance or other forms of friction.
*/
setLinearDamping(damping: number, instanceIndex?: number): void;
/**
* Gets the linear damping of the physics body.
* @param instanceIndex - If this body is instanced, the index of the instance to get the linear damping for.
* @returns The linear damping of the physics body.
*
* This method is useful for retrieving the linear damping of the physics body, which is the amount of
* resistance the body has to linear motion. This is useful for simulating realistic physics behavior
* in a game.
*/
getLinearDamping(instanceIndex?: number): number;
/**
* Sets the angular damping of the physics body.
* @param damping The angular damping of the body.
* @param instanceIndex - If this body is instanced, the index of the instance to set the angular damping for.
*
* This method is useful for controlling the angular velocity of a physics body.
* By setting the damping, the body's angular velocity will be reduced over time, simulating the effect of friction.
* This can be used to create realistic physical behavior in a physics engine.
*/
setAngularDamping(damping: number, instanceIndex?: number): void;
/**
* Gets the angular damping of the physics body.
* @param instanceIndex - If this body is instanced, the index of the instance to get the angular damping for.
*
* @returns The angular damping of the physics body.
*
* This method is useful for getting the angular damping of the physics body,
* which is the rate of reduction of the angular velocity over time.
* This is important for simulating realistic physics behavior in a game.
*/
getAngularDamping(instanceIndex?: number): number;
/**
* Sets the linear velocity of the physics object.
* @param linVel - The linear velocity to set.
* @param instanceIndex - If this body is instanced, the index of the instance to set the linear velocity for.
*
* This method is useful for setting the linear velocity of a physics object,
* which is necessary for simulating realistic physics in a game engine.
* By setting the linear velocity, the physics object will move in the direction and speed specified by the vector.
* This allows for realistic physics simulations, such as simulating the motion of a ball rolling down a hill.
*/
setLinearVelocity(linVel: Vector3, instanceIndex?: number): void;
/**
* Gets the linear velocity of the physics body and stores it in the given vector3.
* @param linVel - The vector3 to store the linear velocity in.
* @param instanceIndex - If this body is instanced, the index of the instance to get the linear velocity for.
*
* This method is useful for getting the linear velocity of a physics body in a physics engine.
* This can be used to determine the speed and direction of the body, which can be used to calculate the motion of the body.
*/
getLinearVelocityToRef(linVel: Vector3, instanceIndex?: number): void;
/**
* Gets the linear velocity of the physics body as a new vector3.
* @param instanceIndex - If this body is instanced, the index of the instance to get the linear velocity for.
* @returns The linear velocity of the physics body.
*
* This method is useful for getting the linear velocity of a physics body in a physics engine.
* This can be used to determine the speed and direction of the body, which can be used to calculate the motion of the body.
*/
getLinearVelocity(instanceIndex?: number): Vector3;
/**
* Sets the angular velocity of the physics object.
* @param angVel - The angular velocity to set.
* @param instanceIndex - If this body is instanced, the index of the instance to set the angular velocity for.
*
* This method is useful for setting the angular velocity of a physics object, which is necessary for
* simulating realistic physics behavior. The angular velocity is used to determine the rate of rotation of the object,
* which is important for simulating realistic motion.
*/
setAngularVelocity(angVel: Vector3, instanceIndex?: number): void;
/**
* Gets the angular velocity of the physics body and stores it in the given vector3.
* @param angVel - The vector3 to store the angular velocity in.
* @param instanceIndex - If this body is instanced, the index of the instance to get the angular velocity for.
*
* This method is useful for getting the angular velocity of a physics body, which can be used to determine the body's
* rotational speed. This information can be used to create realistic physics simulations.
*/
getAngularVelocityToRef(angVel: Vector3, instanceIndex?: number): void;
/**
* Gets the angular velocity of the physics body as a new vector3.
* @param instanceIndex - If this body is instanced, the index of the instance to get the angular velocity for.
* @returns The angular velocity of the physics body.
*
* This method is useful for getting the angular velocity of a physics body, which can be used to determine the body's
* rotational speed. This information can be used to create realistic physics simulations.
*/
getAngularVelocity(instanceIndex?: number): Vector3;
/**
* Applies an impulse to the physics object.
*
* @param impulse The impulse vector.
* @param location The location of the impulse.
* @param instanceIndex For a instanced body, the instance to where the impulse should be applied. If not specified, the impulse is applied to all instances.
*
* This method is useful for applying an impulse to a physics object, which can be used to simulate physical forces such as gravity,
* collisions, and explosions. This can be used to create realistic physics simulations in a game or other application.
*/
applyImpulse(impulse: Vector3, location: Vector3, instanceIndex?: number): void;
/**
* Add torque to a physics body
* @param angularImpulse The angular impulse vector.
* @param instanceIndex For a instanced body, the instance to where the impulse should be applied. If not specified, the impulse is applied to all instances.
*/
applyAngularImpulse(angularImpulse: Vector3, instanceIndex?: number): void;
/**
* Applies a force to the physics object.
*
* @param force The force vector.
* @param location The location of the force.
* @param instanceIndex For a instanced body, the instance to where the force should be applied. If not specified, the force is applied to all instances.
*
* This method is useful for applying a force to a physics object, which can be used to simulate physical forces such as gravity,
* collisions, and explosions. This can be used to create realistic physics simulations in a game or other application.
*/
applyForce(force: Vector3, location: Vector3, instanceIndex?: number): void;
/**
* Retrieves the geometry of the body from the physics plugin.
*
* @returns The geometry of the body.
*
* This method is useful for retrieving the geometry of the body from the physics plugin, which can be used for various physics calculations.
*/
getGeometry(): object;
/**
* Returns an observable that will be notified for when a collision starts or continues for this PhysicsBody
* @returns Observable
*/
getCollisionObservable(): Observable<IPhysicsCollisionEvent>;
/**
* Returns an observable that will be notified when the body has finished colliding with another body
* @returns
*/
getCollisionEndedObservable(): Observable<IBasePhysicsCollisionEvent>;
/**
* Enable or disable collision callback for this PhysicsBody.
* @param enabled true if PhysicsBody's collision will rise a collision event and notifies the observable
*/
setCollisionCallbackEnabled(enabled: boolean): void;
/**
* Enable or disable collision ended callback for this PhysicsBody.
* @param enabled true if PhysicsBody's collision ended will rise a collision event and notifies the observable
*/
setCollisionEndedCallbackEnabled(enabled: boolean): void;
/**
* Get the center of the object in world space.
* @param instanceIndex - If this body is instanced, the index of the instance to get the center for.
* @returns geometric center of the associated mesh
*/
getObjectCenterWorld(instanceIndex?: number): Vector3;
/**
* Get the center of the object in world space.
* @param ref - The vector3 to store the result in.
* @param instanceIndex - If this body is instanced, the index of the instance to get the center for.
* @returns geometric center of the associated mesh
*/
getObjectCenterWorldToRef(ref: Vector3, instanceIndex?: number): Vector3;
/**
* Adds a constraint to the physics engine.
*
* @param childBody - The body to which the constraint will be applied.
* @param constraint - The constraint to be applied.
* @param instanceIndex - If this body is instanced, the index of the instance to which the constraint will be applied. If not specified, no constraint will be applied.
* @param childInstanceIndex - If the child body is instanced, the index of the instance to which the constraint will be applied. If not specified, no constraint will be applied.
*
*/
addConstraint(childBody: PhysicsBody, constraint: PhysicsConstraint, instanceIndex?: number, childInstanceIndex?: number): void;
/**
* Sync with a bone
* @param bone The bone that the impostor will be synced to.
* @param boneMesh The mesh that the bone is influencing.
* @param jointPivot The pivot of the joint / bone in local space.
* @param distToJoint Optional distance from the impostor to the joint.
* @param adjustRotation Optional quaternion for adjusting the local rotation of the bone.
* @param boneAxis Optional vector3 axis the bone is aligned with
*/
syncWithBone(bone: Bone, boneMesh: AbstractMesh, jointPivot: Vector3, distToJoint?: number, adjustRotation?: Quaternion, boneAxis?: Vector3): void;
/**
* Executes a callback on the body or all of the instances of a body
* @param callback the callback to execute
*/
iterateOverAllInstances(callback: (body: PhysicsBody, instanceIndex?: number) => void): void;
/**
* Sets the gravity factor of the physics body
* @param factor the gravity factor to set
* @param instanceIndex the instance of the body to set, if undefined all instances will be set
*/
setGravityFactor(factor: number, instanceIndex?: number): void;
/**
* Gets the gravity factor of the physics body
* @param instanceIndex the instance of the body to get, if undefined the value of first instance will be returned
* @returns the gravity factor
*/
getGravityFactor(instanceIndex?: number): number;
/**
* Set the target transformation (position and rotation) of the body, such that the body will set its velocity to reach that target
* @param position The target position
* @param rotation The target rotation
* @param instanceIndex The index of the instance in an instanced body
*/
setTargetTransform(position: Vector3, rotation: Quaternion, instanceIndex?: number): void;
/**
* Returns if the body has been disposed.
* @returns true if disposed, false otherwise.
*/
get isDisposed(): boolean;
/**
* Disposes the body from the physics engine.
*
* This method is useful for cleaning up the physics engine when a body is no longer needed. Disposing the body will free up resources and prevent memory leaks.
*/
dispose(): void;
}