API for physics-related functions.
Constants
Physics.IS_DEBUGGER_AVAILABLE
Whether the physics debugger is available. True on debug builds, false otherwise.
Physics.IS_DEBUGGER_AVAILABLE: boolean
Functions
Physics.removePhysics
Removes the static or dynamic rigid-body attached to an entity.
Physics.removePhysics(entity: entity)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity to remove physics from. |
Physics.addEventListener
Adds an event listener. A list of events can be found here.
Physics.addEventListener(eventType: string, callback: function): function
Parameters
| Name | Type | Default Value | Description |
|---|
| eventType | string | Required | The event to listen for. |
| callback | function | Required | The callback to use. |
Returns
| Name | Type | Description |
|---|
| callback | function | The callback that was registered. |
Physics.removeEventListener
Removes an event listener.
Physics.removeEventListener(eventType: string, callback: function)
Parameters
| Name | Type | Default Value | Description |
|---|
| eventType | string | Required | The event to remove the listener from. |
| callback | function | Required | The callback to remove. |
Functions - Articulations
Physics.makeArticulationRoot
Physics.makeArticulationRoot(entity: entity, options?: table)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity to make an articulation. |
| options | table? | "{ fixedBase = false, disableSelfCollision = false }" | Optional configuration for the articulation. Set the whole table or individual properties to nil to use defaults. |
Physics.makeArticulationLink
Adds an articulation link rigid-body to an entity.
Physics.makeArticulationLink(entity: entity, parent: entity)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity to make an articulation link. |
| parent | entity | Required | The parent entity. Must have an articulation link already. |
Physics.isArticulationRoot
Checks whether the entity is the root of an articulation.
Physics.isArticulationRoot(entity: entity): boolean
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity to check. |
Returns
| Name | Type | Description |
|---|
| isArticulationRoot | boolean | Whether the entity is an articulation root. |
Physics.isArticulationLink
Checks whether the entity is a link of an articulation.
Physics.isArticulationLink(entity: entity): boolean
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity to check. |
Returns
| Name | Type | Description |
|---|
| isArticulationLink | boolean | Whether the entity is an articulation link. |
Physics.getArticulationRoot
Returns the root of the articulation which this entity is a part of.
Throws if the entity is not part of an articulation.
Physics.getArticulationRoot(entity: entity): entity
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity to get the articulation root of. |
Returns
| Name | Type | Description |
|---|
| articulationRoot | entity | The entity at the root of the articulation. |
Physics.getArticulationParent
Returns the parent of an entity's articulation link.
Throws if the entity is not part of an articulation.
Physics.getArticulationParent(entity: entity): entity?
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity to get the parent link of. |
Returns
| Name | Type | Description |
|---|
| parent | entity? | Parent articulation link, or nil if this entity was the root link. |
Physics.getArticulationChildren
Returns the child links of an entity's articulation link.
Throws if the entity is not part of an articulation.
Physics.getArticulationChildren(entity: entity): entity[]
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity to get the child links of. |
Returns
| Name | Type | Description |
|---|
| children | entity[] | Child articulation links. |
Functions - Character Controllers
Physics.createController
Creates a new PhysX character controller with the given options.
This is a very low level API which requires you to determine the displacement for the controller each frame
(including applying gravity and tracking whether the controller is grounded).
In most cases you'll want to use one of the provided character controllers in the /character-controllers folder.
If you do need to implement your own character controller from scratch,
you should read through https://nvidia-omniverse.github.io/PhysX/physx/5.4.2/docs/CharacterControllers.html first.
Physics.createController(options: ControllerCreateOptions): BoxController | CapsuleController
Parameters
| Name | Type | Default Value | Description |
|---|
| options | ControllerCreateOptions | Required | No description |
Returns
| Name | Type | Description |
|---|
| controller | BoxController | CapsuleController | Box or capsule controller depending on options.shape. |
Physics.moveController
Apply a displacement vector to the given character controller, performing collision checks on surrounding geometry.
The displacement should be premultiplied by the time between this and the previous moveController call if the rate of movement should be framerate independent.
Physics.moveController(controller: BoxController | CapsuleController, displacement: vector, minDistance: number, deltaTime: number): ControllerMoveResult
Parameters
| Name | Type | Default Value | Description |
|---|
| controller | BoxController | CapsuleController | Required | No description |
| displacement | vector | Required | Displacement relative to the controller's centre |
| minDistance | number | Required | Minimum distance below which the displacement (after applying collision) will be considered as no movement. |
| deltaTime | number | Required | Time (in seconds) between this and the previous moveController call. |
Returns
| Name | Type | Description |
|---|
| result | ControllerMoveResult | No description |
Physics.setControllerHeight
Sets the controller's height, not including the contact offset (aka skin) or the radius (for capsule controllers).
Physics.setControllerHeight(controller: BoxController | CapsuleController, height: number)
Parameters
| Name | Type | Default Value | Description |
|---|
| controller | BoxController | CapsuleController | Required | No description |
| height | number | Required | No description |
Physics.setControllerSideExtent
Sets the size of the box controller's collider on the left/right axis.
Physics.setControllerSideExtent(controller: BoxController, sideExtent: number)
Parameters
| Name | Type | Default Value | Description |
|---|
| controller | BoxController | Required | No description |
| sideExtent | number | Required | No description |
Physics.setControllerForwardExtent
Sets the size of the box controller's collider on the forward/backward axis.
Physics.setControllerForwardExtent(controller: BoxController, forwardExtent: number)
Parameters
| Name | Type | Default Value | Description |
|---|
| controller | BoxController | Required | No description |
| forwardExtent | number | Required | No description |
Physics.setControllerRadius
Sets the cylinder and end cap radius of the capsule controller's collider
Physics.setControllerRadius(controller: CapsuleController, radius: number)
Parameters
| Name | Type | Default Value | Description |
|---|
| controller | CapsuleController | Required | No description |
| radius | number | Required | No description |
Physics.setControllerPosition
Sets the controller's position without performing any collision or overlap tests.
You should ensure that the position has sufficient space for the controller's collider.
Physics.setControllerPosition(controller: BoxController | CapsuleController, position: vector)
Parameters
| Name | Type | Default Value | Description |
|---|
| controller | BoxController | CapsuleController | Required | No description |
| position | vector | Required | No description |
Sets the controller's position without performing any collision or overlap tests.
You should ensure that the position has sufficient space for the controller's collider.
Similar to Physics.setControllerPosition, except the vector positions the bottom extent of the collider (including contact offset)
as opposed to the centre.
Physics.setControllerFootPosition(controller: BoxController | CapsuleController, position: vector)
Parameters
| Name | Type | Default Value | Description |
|---|
| controller | BoxController | CapsuleController | Required | No description |
| position | vector | Required | No description |
Physics.setControllerUpDirection
Sets the up direction of the controller, adjusting the collider rotation and auto-stepping.
TODO: Check if this transforms the displacement vector passed to Physics.moveController and document either way.
Physics.setControllerUpDirection(controller: BoxController | CapsuleController, upDirection: vector)
Parameters
| Name | Type | Default Value | Description |
|---|
| controller | BoxController | CapsuleController | Required | No description |
| upDirection | vector | Required | No description |
Physics.setControllerStepOffset
Sets the step offset of the controller.
Physics.setControllerStepOffset(controller: BoxController | CapsuleController, stepOffset: number)
Parameters
| Name | Type | Default Value | Description |
|---|
| controller | BoxController | CapsuleController | Required | No description |
| stepOffset | number | Required | No description |
Physics.getControllerPosition
Gets the position of the controller's centre.
Physics.getControllerPosition(controller: BoxController | CapsuleController): vector
Parameters
| Name | Type | Default Value | Description |
|---|
| controller | BoxController | CapsuleController | Required | No description |
Returns
| Name | Type | Description |
|---|
| position | vector | No description |
Gets the position of the bottom extent of the controller's collider (including contact offset).
Physics.getControllerFootPosition(controller: BoxController | CapsuleController): vector
Parameters
| Name | Type | Default Value | Description |
|---|
| controller | BoxController | CapsuleController | Required | No description |
Returns
| Name | Type | Description |
|---|
| footPosition | vector | No description |
Physics.getControllerUpDirection
Gets the up direction of the controller.
Physics.getControllerUpDirection(controller: BoxController | CapsuleController): vector
Parameters
| Name | Type | Default Value | Description |
|---|
| controller | BoxController | CapsuleController | Required | No description |
Returns
| Name | Type | Description |
|---|
| upDirection | vector | No description |
Physics.getControllerStepOffset
Gets the step offset of the controller.
Physics.getControllerStepOffset(controller: BoxController | CapsuleController): number
Parameters
| Name | Type | Default Value | Description |
|---|
| controller | BoxController | CapsuleController | Required | No description |
Returns
| Name | Type | Description |
|---|
| stepOffset | number | No description |
Functions - Colliders
Physics.createCollider
Creates a new collider with geometry and mass properties.
Physics.createCollider(geometry: PhysicsGeometry): Collider
Parameters
| Name | Type | Default Value | Description |
|---|
| geometry | PhysicsGeometry | Required | Geometry to use. |
Returns
| Name | Type | Description |
|---|
| collider | Collider | The created collider. |
Physics.attachCollider
Attaches the collider to an entity's rigid-body.
Colliders may only be attached to one rigid-body at a time.
Physics.attachCollider(entity: entity, collider: Collider)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity to attach to. |
| collider | Collider | Required | Collider to attach. |
Physics.detachCollider
Detaches the collider from its rigid-body.
Throws if not attached to a rigid-body (check with getColliderEntity).
Physics.detachCollider(collider: Collider)
Parameters
| Name | Type | Default Value | Description |
|---|
| collider | Collider | Required | Collider to detach. |
Physics.getColliders
Gets all colliders attached to the entity's rigid-body.
Physics.getColliders(entity: entity): Collider[]
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity to get the colliders of. |
Returns
| Name | Type | Description |
|---|
| colliders | Collider[] | List of attached colliders. |
Physics.getColliderEntity
Gets the entity this collider is attached to.
Physics.getColliderEntity(collider: Collider): entity?
Parameters
| Name | Type | Default Value | Description |
|---|
| collider | Collider | Required | Collider to get the entity of. |
Returns
| Name | Type | Description |
|---|
| entity | entity? | Entity this collider is attached to, or nil if not attached. |
Functions - Damping
Physics.getLinearDamping
Gets the linear damping of a rigid body.
Physics.getLinearDamping(entity: entity): number
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity with the rigid body. |
Returns
| Name | Type | Description |
|---|
| damping | number | The linear damping of the rigid body. |
Physics.setLinearDamping
Sets the linear damping of a rigid body.
Physics.setLinearDamping(entity: entity, damping: number)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity with the rigid body. |
| damping | number | Required | The linear damping to set. |
Physics.getAngularDamping
Gets the angular damping of a rigid body.
Physics.getAngularDamping(entity: entity): number
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity with the rigid body. |
Returns
| Name | Type | Description |
|---|
| damping | number | The angular damping of the rigid body. |
Physics.setAngularDamping
Sets the angular damping of a rigid body.
Physics.setAngularDamping(entity: entity, damping: number)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity with the rigid body. |
| damping | number | Required | The angular damping to set. |
Functions - Debugging
Physics.connectDebugger
Connects the PhysX Visual Debugger.
This function is only available on debug builds.
Physics.connectDebugger(host: string, port: number, timeout: number)
Parameters
| Name | Type | Default Value | Description |
|---|
| host | string | Required | The host to connect to. |
| port | number | Required | The port to connect to. |
| timeout | number | Required | The timeout in milliseconds. |
Physics.disconnectDebugger
Disconnects the PhysX Visual Debugger.
This function is only available on debug builds.
Physics.disconnectDebugger()
Physics.isDebuggerConnected
Checks if the PhysX Visual Debugger is connected.
This function is only available on debug builds.
Physics.isDebuggerConnected(): boolean
Returns
| Name | Type | Description |
|---|
| connected | boolean | Whether the debugger is connected. |
Functions - Force & Torque
Physics.addForce
Adds a force to a rigid body.
Force accumulation
Forces are accumulated until the next physics step.
To clear the accumulated forces, call clearForce.
Physics.addForce(entity: entity, force: vector, mode?: ForceMode)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity with the rigid body. |
| force | vector | Required | The force to add. |
| mode | ForceMode? | "ForceMode.Force" | The force mode. |
Physics.addTorque
Adds a torque to a rigid body.
Torque accumulation
Torques are accumulated until the next physics step.
To clear the accumulated torques, call clearTorque.
Physics.addTorque(entity: entity, torque: vector, mode?: ForceMode)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity with the rigid body. |
| torque | vector | Required | The torque to add. |
| mode | ForceMode? | "ForceMode.Force" | The force mode. |
Physics.addForceAtPosition
Adds a force to a rigid-body at the given position in world space, affecting both its linear and angular velocity.
Force accumulation
Forces are accumulated until the next physics step.
To clear the accumulated forces, call clearForce.
Physics.addForceAtPosition(entity: entity, force: number, globalPosition: vector, mode?: ForceMode)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity to add the force to. |
| force | number | Required | Force to add. |
| globalPosition | vector | Required | Global position to add the force to. |
| mode | ForceMode? | "ForceMode.Force" | The force mode. |
Physics.clearForce
Clears the currently accumulated forces of a rigid body.
Physics.clearForce(entity: entity, mode?: ForceMode)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity with the rigid body. |
| mode | ForceMode? | "ForceMode.Force" | The force mode of the forces to clear. |
Physics.clearTorque
Clears the currently accumulated torques of a rigid body.
Physics.clearTorque(entity: entity, mode?: ForceMode)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity with the rigid body. |
| mode | ForceMode? | "ForceMode.Force" | The force mode of the torques to clear. |
Functions - Geometry
Physics.createSphere
Creates a sphere geometry with the given radius.
Physics.createSphere(radius: number): PhysicsGeometry
Parameters
| Name | Type | Default Value | Description |
|---|
| radius | number | Required | No description |
Returns
| Name | Type | Description |
|---|
| sphere | PhysicsGeometry | No description |
Physics.createCapsule
Creates a capsule geometry with the given radius and half height.
The total height can be calculated as 2 * (radius + halfHeight).
The capsule is oriented along the X-axis in the geometry's local coordinate space.
To orient it vertically when creating a shape, set the shape's local orientation to a 90 degree rotation about the Z-axis.
Physics.createCapsule(radius: number, halfHeight: number): PhysicsGeometry
Parameters
| Name | Type | Default Value | Description |
|---|
| radius | number | Required | No description |
| halfHeight | number | Required | Distance from the origin to the centre of the end caps. |
Returns
| Name | Type | Description |
|---|
| capsule | PhysicsGeometry | No description |
Physics.createBox
Creates a box geometry with the given half extents along the geometry's local axes.
Physics.createBox(halfExtents: vector): PhysicsGeometry
Parameters
| Name | Type | Default Value | Description |
|---|
| halfExtents | vector | Required | Distance from the origin to the sides of the box on each axis. |
Returns
| Name | Type | Description |
|---|
| box | PhysicsGeometry | No description |
Physics.createPlane
Creates a plane geometry at the origin of the geometry's local coordinate space.
Everything below the plane (-X in the local coordinate space) is considered as colliding with it.
Physics.createPlane(): PhysicsGeometry
Returns
| Name | Type | Description |
|---|
| plane | PhysicsGeometry | No description |
Functions - Joints
Physics.setJointParentFrame
Sets the position and orientation of the joint in the parent's local space.
Physics.setJointParentFrame(entity: entity, position: vector, orientation: Quaternion)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity with the joint. |
| position | vector | Required | Position relative to the parent. |
| orientation | Quaternion | Required | Orientation relative to the parent. |
Physics.setJointChildFrame
Sets the position and orientation of the joint in the child's local space.
Physics.setJointChildFrame(entity: entity, position: vector, orientation: Quaternion)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity with the joint. |
| position | vector | Required | Position relative to the child. |
| orientation | Quaternion | Required | Orientation relative to the child. |
Physics.setJointType
Sets the type of the joint, governing its degrees of freedom.
Physics.setJointType(entity: entity, type: JointType)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity with the joint. |
| type | JointType | Required | Type to set. |
Physics.setJointMotion
Sets the motion of the joint along or about the degree of freedom.
Physics.setJointMotion(entity: entity, degreeOfFreedom: DegreeOfFreedom, motion: JointMotion)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity with the joint. |
| degreeOfFreedom | DegreeOfFreedom | Required | Linear or angular degree of freedom to modify. |
| motion | JointMotion | Required | Type of motion. |
Physics.setJointLimits
Sets the limits of the joint's motion along or about the degree of freedom.
Does nothing unless the joint motion is set to Limited.
Physics.setJointLimits(entity: entity, degreeOfFreedom: DegreeOfFreedom, min: number, max: number)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity with the joint. |
| degreeOfFreedom | DegreeOfFreedom | Required | Linear or angular degree of freedom to modify. |
| min | number | Required | Minimum translation along or rotation about the degree of freedom. |
| max | number | Required | Maximum translation along or rotation about the degree of freedom. |
Functions - Mass & Inertia
Physics.getMass
Gets the mass of a rigid-body entity or collider.
Physics.getMass(entityOrCollider: entity | Collider): number
Parameters
| Name | Type | Default Value | Description |
|---|
| entityOrCollider | entity | Collider | Required | The entity or collider to get the mass of. |
Returns
| Name | Type | Description |
|---|
| mass | number | The mass of the object. |
Physics.setMass
Sets the mass of a rigid-body entity or collider.
You should update the inertia tensor when modifying the mass of a rigid-body.
You can either calculate this by hand, or use the helper methods setMassAndUpdateInertia and updateMassAndInertiaFromColliders.
Physics.setMass(entityOrCollider: entity | Collider, mass: number)
Parameters
| Name | Type | Default Value | Description |
|---|
| entityOrCollider | entity | Collider | Required | The entity or collider to set the mass of. |
| mass | number | Required | The mass to set. |
Physics.getCentreOfMass
Gets the centre of mass of a rigid-body entity or collider, in local space.
Physics.getCentreOfMass(entityOrCollider: entity | Collider): vector
Parameters
| Name | Type | Default Value | Description |
|---|
| entityOrCollider | entity | Collider | Required | The entity or collider to get the centre of mass of. |
Returns
| Name | Type | Description |
|---|
| centreOfMass | vector | The centre of mass of the object. |
Physics.setCentreOfMass
Sets the mass of a rigid-body entity or collider.
You should update the inertia tensor when modifying the centre of mass of a rigid-body.
You can either calculate this by hand, or use the helper methods setMassAndUpdateInertia and updateMassAndInertiaFromColliders.
Physics.setCentreOfMass(entityOrCollider: entity | Collider, centreOfMass: vector)
Parameters
| Name | Type | Default Value | Description |
|---|
| entityOrCollider | entity | Collider | Required | The entity or collider to set the centre of mass of. |
| centreOfMass | vector | Required | The centre of mass to set. |
Physics.getInertiaDiagonal
Gets the diagonal inertia tensor of an entity's rigid-body
Physics.getInertiaDiagonal(entity: entity): vector
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity to get the inertia diagonal of. |
Returns
| Name | Type | Description |
|---|
| inertiaDiagonal | vector | The diagonal inertia tensor. |
Physics.setInertiaDiagonal
Sets the diagonal inertia tensor of an entity's rigid-body.
In most cases you should use the setMassAndUpdateInertia and updateMassAndInertiaFromColliders methods instead.
Physics.setInertiaDiagonal(entity: entity, inertiaDiagonal: vector)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity to set the inertia diagonal of. |
| inertiaDiagonal | vector | Required | The diagonal inertia tensor. |
Physics.getInertiaOrientation
Gets the orientation in which the diagonal inertia tensor of an entity's rigid-body applies.
Physics.getInertiaOrientation(entity: entity): Quaternion
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity to get the inertia orientation of. |
Returns
| Name | Type | Description |
|---|
| inertiaOrientation | Quaternion | The orientation of the inertia tensor. |
Physics.setInertiaOrientation
Sets the orientation in which the diagonal inertia tensor of an entity's rigid-body applies.
In most cases you should use the setMassAndUpdateInertia and updateMassAndInertiaFromColliders methods instead.
Physics.setInertiaOrientation(entity: entity, inertiaOrientation: Quaternion)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity to set the inertia orientation of. |
| inertiaOrientation | Quaternion | Required | The orientation of the inertia tensor. |
Physics.setMassAndUpdateInertia
Sets the mass properties of an entity's rigid-body and updates the inertia tensor to match.
This method assumes a uniform density of 1 for all attached colliders.
For rigid-bodies of mixed density, use updateMassAndInertiaFromColliders or calculate the inertia tensor by hand.
Physics.setMassAndUpdateInertia(entity: entity, mass: number, centreOfMass: vector)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity to set the mass properties of. |
| mass | number | Required | Total mass of the rigid-body across all colliders. |
| centreOfMass | vector | Required | Overall centre of mass of the rigid-body, in local space. |
Physics.updateMassAndInertiaFromColliders
Updates the mass and inertia of an entity's rigid-body to match its attached colliders.
Physics.updateMassAndInertiaFromColliders(entity: entity)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity to update the mass and inertia of. |
Functions - Rigid-Bodies
Physics.makeRigidStatic
Adds a static rigid-body to an entity.
Physics.makeRigidStatic(entity: entity)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity to make a static rigid-body. |
Physics.makeRigidDynamic
Adds a dynamic rigid-body to an entity.
Physics.makeRigidDynamic(entity: entity)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity to make a dynamic rigid-body. |
Physics.isRigidStatic
Checks whether the entity is a static rigid-body.
Physics.isRigidStatic(entity: entity): boolean
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity to check. |
Returns
| Name | Type | Description |
|---|
| isRigidStatic | boolean | Whether the entity is a static rigid-body. |
Physics.isRigidDynamic
Checks whether the entity is a dynamic rigid-body. This includes articulation links.
Physics.isRigidDynamic(entity: entity): boolean
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity to check. |
Returns
| Name | Type | Description |
|---|
| isRigidDynamic | boolean | Whether the entity is a dynamic rigid-body. |
Functions - Scene Queries
Physics.raycast
Traces a ray along a given direction up to an (optional) max distance.
Physics.raycast(origin: vector, direction: vector, maxDistance?: number, options?: RaycastOptions): RaycastResult
Parameters
| Name | Type | Default Value | Description |
|---|
| origin | vector | Required | Starting point of the ray. |
| direction | vector | Required | Direction along which to trace the ray. |
| maxDistance | number? | nil | Optional maximum distance to trace before returning a miss. |
| options | RaycastOptions? | nil | See documentation for RaycastOptions. Pass nil to use all defaults. |
Returns
| Name | Type | Description |
|---|
| result | RaycastResult | See documentation for RaycastResult. |
Physics.sweep
Sweeps a geometry along a given direction up to an (optional) max distance.
An optional 'skin' or contact offset can be defined around the geometry to avoid issues resulting from floating point imprecision.
Contacts will be generated if any part of the geometry or skin hit another object.
Physics.sweep(geometry: PhysicsGeometry, origin: vector, orientation: Quaternion, direction: vector, maxDistance?: number, skin?: number, options?: RaycastOptions): RaycastResult
Parameters
| Name | Type | Default Value | Description |
|---|
| geometry | PhysicsGeometry | Required | Geometry to sweep. |
| origin | vector | Required | Starting point of the geometry. |
| orientation | Quaternion | Required | Orientation of the geometry in world space. |
| direction | vector | Required | Direction along which to sweep the geometry. |
| maxDistance | number? | nil | Optional maximum distance to sweep before returning a miss. |
| skin | number? | "0" | Optional 'skin' around the geometry to start generating intersections in. |
| options | RaycastOptions? | nil | See documentation for RaycastOptions. Pass nil to use all defaults. |
Returns
| Name | Type | Description |
|---|
| result | RaycastResult | See documentation for RaycastResult. |
Physics.overlap
Finds all objects overlapping a geometry.
Physics.overlap(geometry: PhysicsGeometry, origin: vector, orientation: Quaternion, options?: OverlapOptions): entity[]
Parameters
| Name | Type | Default Value | Description |
|---|
| geometry | PhysicsGeometry | Required | Geometry to test with. |
| origin | vector | Required | Position of the geometry. |
| orientation | Quaternion | Required | Orientation of the geometry. |
| options | OverlapOptions? | nil | See documentation for OverlapOptions. Pass nil to use all defaults. |
Returns
| Name | Type | Description |
|---|
| entities | entity[] | Entities overlapping the geometry. |
Functions - Scene
Physics.addToScene
Adds the entity's rigid-body to the physics scene, making it active in collision detection and scene queries.
Note that articulations cannot be modified after being added to the scene.
Physics.addToScene(entity: entity)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity to add. |
Physics.removeFromScene
Removes the entity's rigid-body from the physics scene, making it inactive in collision detection and scene queries.
Physics.removeFromScene(entity: entity)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity to remove. |
Physics.isInScene
Checks whether the entity's rigid-body has been added to the physics scene.
Physics.isInScene(entity: entity): boolean
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity to check. |
Returns
| Name | Type | Description |
|---|
| isInScene | boolean | Whether the entity is in the scene. |
Functions - Sleep & Wake
Physics.wake
Forces the entity's rigid-body to wake up.
The physics engine will pause the simulation of rigid-bodies which have not significantly changed their state for a period of time,
and will wake them automatically if another object interacts with them.
Physics.wake(entity: entity)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity to wake. |
Physics.sleep
Forces the entity's rigid-body to sleep, pausing its simulation until awoken manually or by another object.
Physics.sleep(entity: entity)
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity to sleep. |
Physics.isSleeping
Checks whether the entity's rigid-body has its simulation paused.
Physics.isSleeping(entity: entity): boolean
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | Entity to check. |
Returns
| Name | Type | Description |
|---|
| isSleeping | boolean | Whether the entity is sleeping. |
Functions - Velocity & Acceleration
Physics.getLinearVelocity
Gets the linear velocity of a rigid body.
Physics.getLinearVelocity(entity: entity): vector
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity with the rigid body. |
Returns
| Name | Type | Description |
|---|
| velocity | vector | The linear velocity of the rigid body. |
Physics.getVelocityAtPosition
Gets the velocity of a point in world space if it were attached to the rigid body,
taking into account both the linear and angular velocity.
Physics.getVelocityAtPosition(entity: entity, position: vector): vector
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity with the rigid body. |
| position | vector | Required | World space position to read the velocity of. |
Returns
| Name | Type | Description |
|---|
| velocity | vector | The velocity of the world space position. |
Physics.getAngularVelocity
Gets the angular velocity of a rigid body.
Physics.getAngularVelocity(entity: entity): vector
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity with the rigid body. |
Returns
| Name | Type | Description |
|---|
| velocity | vector | The angular velocity of the rigid body. |
Physics.getLinearAcceleration
Gets the linear acceleration of a rigid body.
Physics.getLinearAcceleration(entity: entity): vector
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity with the rigid body. |
Returns
| Name | Type | Description |
|---|
| acceleration | vector | The linear acceleration of the rigid body. |
Physics.getAngularAcceleration
Gets the angular acceleration of a rigid body.
Physics.getAngularAcceleration(entity: entity): vector
Parameters
| Name | Type | Default Value | Description |
|---|
| entity | entity | Required | The entity with the rigid body. |
Returns
| Name | Type | Description |
|---|
| acceleration | vector | The angular acceleration of the rigid body. |
Types
ControllerCreateOptions
No description provided.
type ControllerCreateOptions = { shape: Physics.ControllerShape, height: number?, radius: number?, climbingMode: Physics.ClimbingMode?, sideExtent: number?, forwardExtent: number?, position: vector?, upDirection: vector?, slopeLimit: number?, nonWalkableMode: Physics.NonWalkableMode?, invisibleWallHeight: number?, maxJumpHeight: number?, contactOffset: number?, stepOffset: number?, density: number?, scaleCoefficient: number?, volumeGrowth: number? }
Properties
| Field | Type | Description |
|---|
| shape | Physics.ControllerShape | Which collider to use. |
| height | number? | Height of the collider. For capsules this excludes the radius of the end caps. |
| radius | number? | Radius of the collider. Ignored when shape is Box. |
| climbingMode | Physics.ClimbingMode? | How the capsule interacts with obstacles taller than stepOffset. |
| sideExtent | number? | Size of the collider on the left/right axis. Ignored when shape is Capsule. |
| forwardExtent | number? | Size of the collider on the forward/backward axis. Ignored when shape is Capsule. |
| position | vector? | Initial position of the controller's centre. |
| upDirection | vector? | Up direction of the collider. |
| slopeLimit | number? | Maximum slope angle before the controller is unable to move up it (as the cosine of the angle). |
| nonWalkableMode | Physics.NonWalkableMode? | How the controller reacts to non-walkable surfaces (defined by slopeLimit). |
| invisibleWallHeight | number? | Set greater than 0 to automatically generate wall colliders around non-walkable surfaces. |
| maxJumpHeight | number? | If invisibleWallHeight is greater than 0, extends the detection range for nearby surfaces. |
| contactOffset | number? | Size of the skin around the collider used to handle precision issues when detecting collisions. |
| stepOffset | number? | Maximum height of an obstacle that can be walked over. Capsule controllers can still slide over obstacles taller than this, unless nonWalkableMode is Constrained. |
| density | number? | Density of the underlying kinematic PhysX actor. |
| scaleCoefficient | number? | Scale factor of the underlying kinematic PhysX actor. Should be < 1 to avoid pushing objects through walls. |
| volumeGrowth | number? | Size of the region around the controller to cache. Must be between 1 and 2. |
ControllerMoveResult
Contains information about what happened during Physics.moveController.
type ControllerMoveResult = { hasSideCollisions: boolean, hasTopCollisions: boolean, hasBottomCollisions: boolean }
Properties
| Field | Type | Description |
|---|
| hasSideCollisions | boolean | True if any collision events occurred this move to the controller's sides |
| hasTopCollisions | boolean | True if any collision events occurred this move to the top of the controller |
| hasBottomCollisions | boolean | True if any collision events occurred this move to the bottom of the controller |
RaycastOptions
Configures raycast and sweep queries for the desired behaviour and performance.
All properties can be left defaulted to sensible values, maintaining expected behaviour while minimising performance impact from the more specialised features.
type RaycastOptions = { anyHit: boolean?, dontBlock: boolean?, includeStatic: boolean?, includeDynamic: boolean?, includeTouching: boolean?, includePosition: boolean?, includeNormal: boolean?, includeUv: boolean?, includeMtd: boolean?, mask: number[]? }
Properties
| Field | Type | Description |
|---|
| anyHit | boolean? | True to end the trace early on any blocking hit, not just closest. |
| dontBlock | boolean? | Causes all intersected objects to be considered 'touching' hits, allowing the query to move through objects. |
| includeStatic | boolean? | Toggles inclusion of static rigid-bodies in the query. |
| includeDynamic | boolean? | Toggles inclusion of dynamic rigid-bodies in the query. |
| includeTouching | boolean? | Collects hits for non-blocking objects, or all objects if dontBlock is true. |
| includePosition | boolean? | Toggles calculation of hit position on all results. |
| includeNormal | boolean? | Toggles calculation of hit normal on all results. |
| includeUv | boolean? | Toggles inclusion of face UV on results which hit a triangle mesh or height field. |
| includeMtd | boolean? | Toggles calculation of Minimum Translational Distance for initial overlaps. |
| mask | number[]? | Four 2-byte bitwise filter masks following the PhysX convention. |
RaycastResultHit
A blocking or touching hit returned from a ray or sweep scene query. The contents will depend on the RaycastOptions passed to the query method.
type RaycastResultHit = { entity: entity?, distance: vector, position: vector?, normal: vector?, uv: number[]?, hadInitialOverlap: boolean }
Properties
| Field | Type | Description |
|---|
| entity | entity? | Entity that was hit, or nil if object isn't linked to an entity. |
| distance | vector | Distance travelled along the query's direction. MTD if includeMtd was true and the query had initial overlap. |
| position | vector? | Hit position, or nil if includePosition was false. |
| normal | vector? | Hit normal, or nil if includeNormal was false. |
| uv | number[]? | Hit UV, or nil if includeUv was false or the hit object isn't a mesh. |
| hadInitialOverlap | boolean | True if the query had initial overlap with an object at the origin. |
RaycastResult
Result of a ray or sweep scene query.
type RaycastResult = { blockingHit: RaycastResultHit?, touchingHits: RaycastResultHit[] }
Properties
| Field | Type | Description |
|---|
| blockingHit | RaycastResultHit? | Closest blocking hit if the query generated one. |
| touchingHits | RaycastResultHit[] | List of touching hits the query generated. Empty if no touching hits or includeTouching was false. |
OverlapOptions
Configures overlap queries for the desired behaviour and performance.
All properties can be left defaulted to sensible values, maintaining expected behaviour while minimising performance impact from the more specialised features.
type OverlapOptions = { includeStatic: boolean?, includeDynamic: boolean?, mask: number[]? }
Properties
| Field | Type | Description |
|---|
| includeStatic | boolean? | Toggles inclusion of static rigid-bodies in the query. |
| includeDynamic | boolean? | Toggles inclusion of dynamic rigid-bodies in the query. |
| mask | number[]? | Four 2-byte bitwise filter masks following the PhysX convention. |
Enums
ForceMode
Force modes which describe the unit of the force or torque given to addForce and addTorque.
| Value |
|---|
| Force |
| Impulse |
| VelocityChange |
| Acceleration |
ControllerShape
Collider shape to use for character controllers.
ClimbingMode
Climbing mode to use for capsule character controllers (PhysX Docs)
NonWalkableMode
How the character controller should handle non-walkable surfaces (e.g. steep slopes)
| Value |
|---|
| PreventClimbing |
| PreventClimbingAndForceSliding |
JointType
Joint types governing which limits and drives are supported for the joint.
| Value |
|---|
| Fixed |
| Linear |
| Hinge |
| HingeUnwrapped |
| BallSocket |
JointMotion
Allowed motion of the joint along or about a degree of freedom.
DegreeOfFreedom
Degrees of freedom along or about which a joint can move.
| Value |
|---|
| LinearX |
| LinearY |
| LinearZ |
| AngularX |
| AngularY |
| AngularZ |
Events
"tick"
Fires every time the physics engine is ticked (at the fixed physics timestep).
Physics.addEventListener("tick", function(deltaTime) end)
Parameters
| Name | Type | Description |
|---|
| deltaTime | number | The time in seconds since the last physics tick (the fixed timestep). |