# RigidBodyComponent

Class · extends [`Component`](https://api.playcanvas.com/engine/classes/Component.md) · category: Physics

Source: https://github.com/playcanvas/engine/blob/f059dc005842f76e052cdf44d8370c8c7ec475ac/src/framework/components/rigid-body/component.js#L76

The RigidBodyComponent, when combined with a [CollisionComponent](https://api.playcanvas.com/engine/classes/CollisionComponent.md), allows your entities
to be simulated using realistic physics. A RigidBodyComponent will fall under gravity and
collide with other rigid bodies. Using scripts, you can apply forces and impulses to rigid
bodies.

You should never need to use the RigidBodyComponent constructor directly. To add a
RigidBodyComponent to an [Entity](https://api.playcanvas.com/engine/classes/Entity.md), use [Entity#addComponent](https://api.playcanvas.com/engine/classes/Entity.md#addcomponent):

```javascript
// Create a static 1x1x1 box-shaped rigid body
const entity = new Entity();
entity.addComponent('collision'); // Without options, this defaults to a 1x1x1 box shape
entity.addComponent('rigidbody'); // Without options, this defaults to a 'static' body
```

To create a dynamic sphere with mass of 10, do:

```javascript
const entity = new Entity();
entity.addComponent('collision', {
    type: 'sphere'
});
entity.addComponent('rigidbody', {
    type: 'dynamic',
    mass: 10
});
```

Once the RigidBodyComponent is added to the entity, you can access it via the
[Entity#rigidbody](https://api.playcanvas.com/engine/classes/Entity.md#rigidbody) property:

```javascript
entity.rigidbody.mass = 10;
console.log(entity.rigidbody.mass);
```

For player movement, `playcanvas/scripts/esm/first-person-controller.mjs` and
`playcanvas/scripts/esm/third-person-controller.mjs` ship complete rigidbody character
controllers with capsule collision, damped ground and air movement, sprinting, jumping and
camera control. Attach one instead of driving the body by hand.

Relevant Engine API examples:

- [Falling shapes](https://playcanvas.github.io/#/physics/falling-shapes)
- [Vehicle physics](https://playcanvas.github.io/#/physics/vehicle)

## Accessors

### angularDamping

```ts
get angularDamping(): number
set angularDamping(damping: number)
```

Gets the rate at which a body loses angular velocity over time.

### angularFactor

```ts
get angularFactor(): Readonly<Vec3>
set angularFactor(factor: Readonly<Vec3>)
```

Gets the scaling factor for angular movement of the body in each axis. Use the setter to
update the physics body.

### angularVelocity

```ts
get angularVelocity(): Readonly<Vec3>
set angularVelocity(velocity: Readonly<Vec3>)
```

Gets the rotational speed of the body around each world axis. Use the setter to update the
physics body.

### friction

```ts
get friction(): number
set friction(friction: number)
```

Gets the friction value used when contacts occur between two bodies.

### gravityScale

```ts
get gravityScale(): number
set gravityScale(scale: number)
```

Gets the scale applied to the world gravity for this body.

### group

```ts
get group(): number
set group(group: number)
```

Gets the collision group this body belongs to.

### linearDamping

```ts
get linearDamping(): number
set linearDamping(damping: number)
```

Gets the rate at which a body loses linear velocity over time.

### linearFactor

```ts
get linearFactor(): Readonly<Vec3>
set linearFactor(factor: Readonly<Vec3>)
```

Gets the scaling factor for linear movement of the body in each axis. Use the setter to
update the physics body.

### linearVelocity

```ts
get linearVelocity(): Readonly<Vec3>
set linearVelocity(velocity: Readonly<Vec3>)
```

Gets the speed of the body in a given direction. Use the setter to update the physics body.

### mask

```ts
get mask(): number
set mask(mask: number)
```

Gets the collision mask sets which groups this body collides with.

### mass

```ts
get mass(): number
set mass(mass: number)
```

Gets the mass of the body.

### restitution

```ts
get restitution(): number
set restitution(restitution: number)
```

Gets the value that controls the amount of energy lost when two rigid bodies collide.

### rollingFriction

```ts
get rollingFriction(): number
set rollingFriction(friction: number)
```

Gets the torsional friction orthogonal to the contact point.

### type

```ts
get type(): "static" | "dynamic" | "kinematic"
set type(type: "static" | "dynamic" | "kinematic")
```

Gets the rigid body type determines how the body is simulated.

## Methods

### activate

```ts
activate(): void
```

Forcibly activate the rigid body simulation. Only affects rigid bodies of type
[BODYTYPE_DYNAMIC](https://api.playcanvas.com/engine/variables/BODYTYPE_DYNAMIC.md).

### applyForce

```ts
applyForce(x: number, y: number, z: number, px?: number, py?: number, pz?: number): void
```

Apply a force to the body at a point. By default, the force is applied at the origin of the
body. However, the force can be applied at an offset from this point by specifying a world
space vector from the body's origin to the point of application. The body's origin is the
entity's world position, shifted by the collision component's
[CollisionComponent#linearOffset](https://api.playcanvas.com/engine/classes/CollisionComponent.md#linearoffset).

**Parameters**

- `x` (`number`): X-component of the force in world space.
- `y` (`number`): Y-component of the force in world space.
- `z` (`number`): Z-component of the force in world space.
- `px` (`number`, optional): X-component of the relative point at which to apply the force in
  world space.
- `py` (`number`, optional): Y-component of the relative point at which to apply the force in
  world space.
- `pz` (`number`, optional): Z-component of the relative point at which to apply the force in
  world space.

**Returns** `void`

**Example**

```ts
// Apply an approximation of gravity at the body's center
this.entity.rigidbody.applyForce(0, -10, 0);
```

**Example**

```ts
// Apply an approximation of gravity at 1 unit down the world Z from the center of the body
this.entity.rigidbody.applyForce(0, -10, 0, 0, 0, 1);
```

```ts
applyForce(force: Vec3, relativePoint?: Vec3): void
```

Apply a force to the body at a point. By default, the force is applied at the origin of the
body. However, the force can be applied at an offset from this point by specifying a world
space vector from the body's origin to the point of application. The body's origin is the
entity's world position, shifted by the collision component's
[CollisionComponent#linearOffset](https://api.playcanvas.com/engine/classes/CollisionComponent.md#linearoffset).

**Parameters**

- `force` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): Vector representing the force in world space.
- `relativePoint` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md), optional): Optional vector representing the relative point at which to
  apply the force in world space.

**Returns** `void`

**Example**

```ts
// Calculate a force vector pointing in the world space direction of the entity
const force = this.entity.forward.clone().mulScalar(100);

// Apply the force at the body's center
this.entity.rigidbody.applyForce(force);
```

**Example**

```ts
// Apply a force at some relative offset from the body's center
// Calculate a force vector pointing in the world space direction of the entity
const force = this.entity.forward.clone().mulScalar(100);

// Calculate the world space relative offset
const relativePoint = new Vec3();
const childEntity = this.entity.findByName('Engine');
relativePoint.sub2(childEntity.getPosition(), this.entity.getPosition());

// Apply the force
this.entity.rigidbody.applyForce(force, relativePoint);
```

### applyImpulse

```ts
applyImpulse(x: number, y: number, z: number, px?: number, py?: number, pz?: number): void
```

Apply an impulse (instantaneous change of velocity) to the body at a point. By default, the
impulse is applied at the origin of the body. However, the impulse can be applied at an
offset from this point by specifying a world space vector from the body's origin to the
point of application. The body's origin is the entity's world position, shifted by the
collision component's [CollisionComponent#linearOffset](https://api.playcanvas.com/engine/classes/CollisionComponent.md#linearoffset).

**Parameters**

- `x` (`number`): X-component of the impulse in world space.
- `y` (`number`): Y-component of the impulse in world space.
- `z` (`number`): Z-component of the impulse in world space.
- `px` (`number`, optional): X-component of the relative point at which to apply the impulse in
  world space.
- `py` (`number`, optional): Y-component of the relative point at which to apply the impulse in
  world space.
- `pz` (`number`, optional): Z-component of the relative point at which to apply the impulse in
  world space.

**Returns** `void`

**Example**

```ts
// Apply an impulse along the world space positive y-axis at the body's origin
entity.rigidbody.applyImpulse(0, 10, 0);
```

**Example**

```ts
// Apply an impulse along the world space positive y-axis at 1 unit along the world space
// positive z-axis from the body's origin
entity.rigidbody.applyImpulse(0, 10, 0, 0, 0, 1);
```

```ts
applyImpulse(impulse: Vec3, relativePoint?: Vec3): void
```

Apply an impulse (instantaneous change of velocity) to the body at a point. By default, the
impulse is applied at the origin of the body. However, the impulse can be applied at an
offset from this point by specifying a world space vector from the body's origin to the
point of application. The body's origin is the entity's world position, shifted by the
collision component's [CollisionComponent#linearOffset](https://api.playcanvas.com/engine/classes/CollisionComponent.md#linearoffset).

**Parameters**

- `impulse` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): Vector representing the impulse in world space.
- `relativePoint` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md), optional): Optional vector representing the relative point at which to
  apply the impulse in world space.

**Returns** `void`

**Example**

```ts
// Apply an impulse along the world space positive y-axis at the body's origin
const impulse = new Vec3(0, 10, 0);
entity.rigidbody.applyImpulse(impulse);
```

**Example**

```ts
// Apply an impulse along the world space positive y-axis at 1 unit along the world space
// positive z-axis from the body's origin
const impulse = new Vec3(0, 10, 0);
const relativePoint = new Vec3(0, 0, 1);
entity.rigidbody.applyImpulse(impulse, relativePoint);
```

**Example**

```ts
// Apply an impulse at an offset given in the entity's local space, by first rotating the
// offset into world space
const impulse = new Vec3(0, 10, 0);
const relativePoint = entity.getRotation().transformVector(new Vec3(0, 0, 1));
entity.rigidbody.applyImpulse(impulse, relativePoint);
```

### applyTorque

```ts
applyTorque(x: number, y: number, z: number): void
```

Apply torque (rotational force) to the body.

**Parameters**

- `x` (`number`): The x-component of the torque force in world space.
- `y` (`number`): The y-component of the torque force in world space.
- `z` (`number`): The z-component of the torque force in world space.

**Returns** `void`

**Example**

```ts
entity.rigidbody.applyTorque(0, 10, 0);
```

```ts
applyTorque(torque: Vec3): void
```

Apply torque (rotational force) to the body.

**Parameters**

- `torque` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): Vector representing the torque force in world space.

**Returns** `void`

**Example**

```ts
const torque = new Vec3(0, 10, 0);
entity.rigidbody.applyTorque(torque);
```

### applyTorqueImpulse

```ts
applyTorqueImpulse(x: number, y: number, z: number): void
```

Apply a torque impulse (rotational force applied instantaneously) to the body.

**Parameters**

- `x` (`number`): X-component of the torque impulse in world space.
- `y` (`number`): Y-component of the torque impulse in world space.
- `z` (`number`): Z-component of the torque impulse in world space.

**Returns** `void`

**Example**

```ts
entity.rigidbody.applyTorqueImpulse(0, 10, 0);
```

```ts
applyTorqueImpulse(torque: Vec3): void
```

Apply a torque impulse (rotational force applied instantaneously) to the body.

**Parameters**

- `torque` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): Vector representing the torque impulse in world space.

**Returns** `void`

**Example**

```ts
const torque = new Vec3(0, 10, 0);
entity.rigidbody.applyTorqueImpulse(torque);
```

### isActive

```ts
isActive(): boolean
```

Returns true if the rigid body is currently actively being simulated. I.e. Not 'sleeping'.

**Returns** `boolean`: True if the body is active.

### isKinematic

```ts
isKinematic(): boolean
```

Returns true if the rigid body is of type [BODYTYPE_KINEMATIC](https://api.playcanvas.com/engine/variables/BODYTYPE_KINEMATIC.md).

**Returns** `boolean`: True if kinematic.

### isStatic

```ts
isStatic(): boolean
```

Returns true if the rigid body is of type [BODYTYPE_STATIC](https://api.playcanvas.com/engine/variables/BODYTYPE_STATIC.md).

**Returns** `boolean`: True if static.

### isStaticOrKinematic

```ts
isStaticOrKinematic(): boolean
```

Returns true if the rigid body is of type [BODYTYPE_STATIC](https://api.playcanvas.com/engine/variables/BODYTYPE_STATIC.md) or [BODYTYPE_KINEMATIC](https://api.playcanvas.com/engine/variables/BODYTYPE_KINEMATIC.md).

**Returns** `boolean`: True if static or kinematic.

### teleport

```ts
teleport(x: number, y: number, z: number, rx?: number, ry?: number, rz?: number): void
```

Teleport an entity to a new world space position, optionally setting orientation. This
function should only be called for rigid bodies that are dynamic.

**Parameters**

- `x` (`number`): X-coordinate of the new world space position.
- `y` (`number`): Y-coordinate of the new world space position.
- `z` (`number`): Z-coordinate of the new world space position.
- `rx` (`number`, optional): X-rotation of the world space Euler angles in degrees.
- `ry` (`number`, optional): Y-rotation of the world space Euler angles in degrees.
- `rz` (`number`, optional): Z-rotation of the world space Euler angles in degrees.

**Returns** `void`

**Example**

```ts
// Teleport the entity to the origin
entity.rigidbody.teleport(0, 0, 0);
```

**Example**

```ts
// Teleport the entity to world space coordinate [1, 2, 3] and reset orientation
entity.rigidbody.teleport(1, 2, 3, 0, 0, 0);
```

```ts
teleport(position: Vec3, angles?: Vec3): void
```

Teleport an entity to a new world space position, optionally setting orientation. This
function should only be called for rigid bodies that are dynamic.

**Parameters**

- `position` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): Vector holding the new world space position.
- `angles` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md), optional): Vector holding the new world space Euler angles in degrees.

**Returns** `void`

**Example**

```ts
// Teleport the entity to the origin
entity.rigidbody.teleport(Vec3.ZERO);
```

**Example**

```ts
// Teleport the entity to world space coordinate [1, 2, 3] and reset orientation
const position = new Vec3(1, 2, 3);
entity.rigidbody.teleport(position, Vec3.ZERO);
```

```ts
teleport(position: Vec3, rotation?: Quat): void
```

Teleport an entity to a new world space position, optionally setting orientation. This
function should only be called for rigid bodies that are dynamic.

**Parameters**

- `position` ([`Vec3`](https://api.playcanvas.com/engine/classes/Vec3.md)): Vector holding the new world space position.
- `rotation` ([`Quat`](https://api.playcanvas.com/engine/classes/Quat.md), optional): Quaternion holding the new world space rotation.

**Returns** `void`

**Example**

```ts
// Teleport the entity to the origin
entity.rigidbody.teleport(Vec3.ZERO);
```

**Example**

```ts
// Teleport the entity to world space coordinate [1, 2, 3] and reset orientation
const position = new Vec3(1, 2, 3);
entity.rigidbody.teleport(position, Quat.IDENTITY);
```

## Events

### EVENT_COLLISIONEND

```ts
static EVENT_COLLISIONEND: string = 'collisionend'
```

Fired when two rigid bodies stop touching. The handler is passed an [Entity](https://api.playcanvas.com/engine/classes/Entity.md) that
represents the other rigid body involved in the collision.

**Example**

```ts
entity.rigidbody.on('collisionend', (other) => {
    console.log(`${entity.name} stopped touching ${other.name}`);
});
```

### EVENT_COLLISIONSTART

```ts
static EVENT_COLLISIONSTART: string = 'collisionstart'
```

Fired when two rigid bodies start touching. The handler is passed a [ContactResult](https://api.playcanvas.com/engine/classes/ContactResult.md)
object containing details of the contact between the two rigid bodies.

**Example**

```ts
entity.rigidbody.on('collisionstart', (result) => {
    console.log(`Collision started between ${entity.name} and ${result.other.name}`);
});
```

### EVENT_CONTACT

```ts
static EVENT_CONTACT: string = 'contact'
```

Fired when a contact occurs between two rigid bodies. The handler is passed a
[ContactResult](https://api.playcanvas.com/engine/classes/ContactResult.md) object containing details of the contact between the two rigid bodies.

**Example**

```ts
entity.rigidbody.on('contact', (result) => {
   console.log(`Contact between ${entity.name} and ${result.other.name}`);
});
```

### EVENT_TRIGGERENTER

```ts
static EVENT_TRIGGERENTER: string = 'triggerenter'
```

Fired when a rigid body enters a trigger volume. The handler is passed an [Entity](https://api.playcanvas.com/engine/classes/Entity.md)
representing the trigger volume that this rigid body entered.

**Example**

```ts
entity.rigidbody.on('triggerenter', (trigger) => {
    console.log(`Entity ${entity.name} entered trigger volume ${trigger.name}`);
});
```

### EVENT_TRIGGERLEAVE

```ts
static EVENT_TRIGGERLEAVE: string = 'triggerleave'
```

Fired when a rigid body exits a trigger volume. The handler is passed an [Entity](https://api.playcanvas.com/engine/classes/Entity.md)
representing the trigger volume that this rigid body exited.

**Example**

```ts
entity.rigidbody.on('triggerleave', (trigger) => {
    console.log(`Entity ${entity.name} exited trigger volume ${trigger.name}`);
});
```

## Inherited from [Component](https://api.playcanvas.com/engine/classes/Component.md)

- `entity: Entity`
- `system: ComponentSystem`
- `get enabled(): boolean` · `set enabled(value: boolean)`
- `fire(name: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any, arg5?: any, arg6?: any, arg7?: any, arg8?: any): EventHandler`
- `hasEvent(name: string): boolean`
- `off(name?: string, callback?: HandleEventCallback, scope?: any): EventHandler`
- `on(name: string, callback: HandleEventCallback, scope?: any): EventHandle`
- `once(name: string, callback: HandleEventCallback, scope?: any): EventHandle`