Physics

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.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.

Physics.getMass

Gets the mass of a rigid body.

Physics.getMass(entity: entity): number

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity with the rigid body.

Returns

Name	Type	Description
mass	number	The mass of the rigid body.

Physics.setMass

Sets the mass of a rigid body.

Physics.setMass(entity: entity, mass: number)

Parameters

Name	Type	Default Value	Description
entity	entity	Required	The entity with the rigid body.
mass	number	Required	The mass to set.

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.

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.

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.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.

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

Physics.setControllerFootPosition

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

Physics.getControllerFootPosition

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

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

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.

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

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.

Value
Box
Capsule

ClimbingMode

Climbing mode to use for capsule character controllers (PhysX Docs)

Value
Easy
Constrained

NonWalkableMode

How the character controller should handle non-walkable surfaces (e.g. steep slopes)

Value
PreventClimbing
PreventClimbingAndForceSliding

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).