Class RigidBodyComponent

The rigidbody component, when combined with a CollisionComponent, allows your entities to be simulated using realistic physics. A rigidbody component 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. To add an RigidBodyComponent to a Entity, use Entity#addComponent:

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

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

const entity = pc.Entity();
entity.addComponent("rigidbody", {
    type: pc.BODYTYPE_DYNAMIC,
    mass: 10
});
entity.addComponent("collision", {
    type: "sphere"
});

Relevant 'Engine-only' examples:

Hierarchy (view full)

Constructors

constructor

Properties

entity system

Accessors

angularDamping angularFactor angularVelocity enabled friction group linearDamping linearFactor linearVelocity mask mass restitution rollingFriction type

Methods

activate applyForce applyImpulse applyTorque applyTorqueImpulse fire hasEvent isActive isKinematic isStatic isStaticOrKinematic off on once teleport

Events

EVENT_COLLISIONEND EVENT_COLLISIONSTART EVENT_CONTACT EVENT_TRIGGERENTER EVENT_TRIGGERLEAVE

Constructors

constructor

Properties

entity

entity: Entity

The Entity that this Component is attached to.

system

system: ComponentSystem

The ComponentSystem used to create this Component.

Accessors

angularDamping

angularFactor

angularVelocity

enabled

friction

group

linearDamping

linearFactor

linearVelocity

mask

mass

restitution

  • get restitution(): number

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

    Returns number

  • set restitution(restitution): void

  • Sets the value that controls the amount of energy lost when two rigid bodies collide. The calculation multiplies the restitution values for both colliding bodies. A multiplied value of 0 means that all energy is lost in the collision while a value of 1 means that no energy is lost. Should be set in the range 0 to 1. Defaults to 0.

    Parameters

    • restitution: number

    Returns void

rollingFriction

type

Methods

activate

applyForce

  • applyForce(x, y?, z?, px?, py?, pz?): void

  • Apply an 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 this point by specifying a world space vector from the body's origin to the point of application. This function has two valid signatures. You can either specify the force (and optional relative point) via 3D-vector or numbers.

    Parameters

    • x: number | Vec3

      A 3-dimensional vector representing the force in world space or the x-component of the force in world space.

    • Optionaly: number | Vec3

      An optional 3-dimensional vector representing the relative point at which to apply the impulse in world space or the y-component of the force in world space.

    • Optionalz: number

      The z-component of the force in world space.

    • Optionalpx: number

      The x-component of a world space offset from the body's position where the force is applied.

    • Optionalpy: number

      The y-component of a world space offset from the body's position where the force is applied.

    • Optionalpz: number

      The z-component of a world space offset from the body's position where the force is applied.

    Returns void

    Example

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

    Example

    // 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);

    Example

    // Apply a force at 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);

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

    Example

    // 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 relativePos = new pc.Vec3();
    const childEntity = this.entity.findByName('Engine');
    relativePos.sub2(childEntity.getPosition(), this.entity.getPosition());

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

applyImpulse

  • applyImpulse(x, y?, z?, px?, py?, pz?): void

  • Apply an impulse (instantaneous change of velocity) to the body at a point. This function has two valid signatures. You can either specify the impulse (and optional relative point) via 3D-vector or numbers.

    Parameters

    • x: number | Vec3

      A 3-dimensional vector representing the impulse in world space or the x-component of the impulse in world space.

    • Optionaly: number | Vec3

      An optional 3-dimensional vector representing the relative point at which to apply the impulse in the local space of the entity or the y-component of the impulse to apply in world space.

    • Optionalz: number

      The z-component of the impulse to apply in world space.

    • Optionalpx: number

      The x-component of the point at which to apply the impulse in the local space of the entity.

    • Optionalpy: number

      The y-component of the point at which to apply the impulse in the local space of the entity.

    • Optionalpz: number

      The z-component of the point at which to apply the impulse in the local space of the entity.

    Returns void

    Example

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

    Example

    // Apply an impulse along the world space positive y-axis at 1 unit down the positive
    // z-axis of the entity's local space.
    const impulse = new pc.Vec3(0, 10, 0);
    const relativePoint = new pc.Vec3(0, 0, 1);
    entity.rigidbody.applyImpulse(impulse, relativePoint);

    Example

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

    Example

    // Apply an impulse along the world space positive y-axis at 1 unit down the positive
    // z-axis of the entity's local space.
    entity.rigidbody.applyImpulse(0, 10, 0, 0, 0, 1);

applyTorque

  • applyTorque(x, y?, z?): void

  • Apply torque (rotational force) to the body. This function has two valid signatures. You can either specify the torque force with a 3D-vector or with 3 numbers.

    Parameters

    • x: number | Vec3

      A 3-dimensional vector representing the torque force in world space or the x-component of the torque force in world space.

    • Optionaly: number

      The y-component of the torque force in world space.

    • Optionalz: number

      The z-component of the torque force in world space.

    Returns void

    Example

    // Apply via vector
    const torque = new pc.Vec3(0, 10, 0);
    entity.rigidbody.applyTorque(torque);

    Example

    // Apply via numbers
    entity.rigidbody.applyTorque(0, 10, 0);

applyTorqueImpulse

  • applyTorqueImpulse(x, y?, z?): void

  • Apply a torque impulse (rotational force applied instantaneously) to the body. This function has two valid signatures. You can either specify the torque force with a 3D-vector or with 3 numbers.

    Parameters

    • x: number | Vec3

      A 3-dimensional vector representing the torque impulse in world space or the x-component of the torque impulse in world space.

    • Optionaly: number

      The y-component of the torque impulse in world space.

    • Optionalz: number

      The z-component of the torque impulse in world space.

    Returns void

    Example

    // Apply via vector
    const torque = new pc.Vec3(0, 10, 0);
    entity.rigidbody.applyTorqueImpulse(torque);

    Example

    // Apply via numbers
    entity.rigidbody.applyTorqueImpulse(0, 10, 0);

fire

  • fire(name, arg1?, arg2?, arg3?, arg4?, arg5?, arg6?, arg7?, arg8?): EventHandler

  • Fire an event, all additional arguments are passed on to the event listener.

    Parameters

    • name: string

      Name of event to fire.

    • Optionalarg1: any

      First argument that is passed to the event handler.

    • Optionalarg2: any

      Second argument that is passed to the event handler.

    • Optionalarg3: any

      Third argument that is passed to the event handler.

    • Optionalarg4: any

      Fourth argument that is passed to the event handler.

    • Optionalarg5: any

      Fifth argument that is passed to the event handler.

    • Optionalarg6: any

      Sixth argument that is passed to the event handler.

    • Optionalarg7: any

      Seventh argument that is passed to the event handler.

    • Optionalarg8: any

      Eighth argument that is passed to the event handler.

    Returns EventHandler

    Self for chaining.

    Example

    obj.fire('test', 'This is the message');

hasEvent

  • hasEvent(name): boolean

  • Test if there are any handlers bound to an event name.

    Parameters

    • name: string

      The name of the event to test.

    Returns boolean

    True if the object has handlers bound to the specified event name.

    Example

    obj.on('test', function () { }); // bind an event to 'test'
    obj.hasEvent('test'); // returns true
    obj.hasEvent('hello'); // returns false

isActive

isKinematic

isStatic

isStaticOrKinematic

off

  • off(name?, callback?, scope?): EventHandler

  • Detach an event handler from an event. If callback is not provided then all callbacks are unbound from the event, if scope is not provided then all events with the callback will be unbound.

    Parameters

    • Optionalname: string

      Name of the event to unbind.

    • Optionalcallback: HandleEventCallback

      Function to be unbound.

    • Optionalscope: object

      Scope that was used as the this when the event is fired.

    Returns EventHandler

    Self for chaining.

    Example

    const handler = function () {
    };
    obj.on('test', handler);

    obj.off(); // Removes all events
    obj.off('test'); // Removes all events called 'test'
    obj.off('test', handler); // Removes all handler functions, called 'test'
    obj.off('test', handler, this); // Removes all handler functions, called 'test' with scope this

on

  • on(name, callback, scope?): EventHandle

  • Attach an event handler to an event.

    Parameters

    • name: string

      Name of the event to bind the callback to.

    • callback: HandleEventCallback

      Function that is called when event is fired. Note the callback is limited to 8 arguments.

    • Optionalscope: object = ...

      Object to use as 'this' when the event is fired, defaults to current this.

    Returns EventHandle

    Can be used for removing event in the future.

    Example

    obj.on('test', function (a, b) {
        console.log(a + b);
    });
    obj.fire('test', 1, 2); // prints 3 to the console

    Example

    const evt = obj.on('test', function (a, b) {
        console.log(a + b);
    });
    // some time later
    evt.off();

once

  • once(name, callback, scope?): EventHandle

  • Attach an event handler to an event. This handler will be removed after being fired once.

    Parameters

    • name: string

      Name of the event to bind the callback to.

    • callback: HandleEventCallback

      Function that is called when event is fired. Note the callback is limited to 8 arguments.

    • Optionalscope: object = ...

      Object to use as 'this' when the event is fired, defaults to current this.

    Returns EventHandle

    • can be used for removing event in the future.

    Example

    obj.once('test', function (a, b) {
        console.log(a + b);
    });
    obj.fire('test', 1, 2); // prints 3 to the console
    obj.fire('test', 1, 2); // not going to get handled

teleport

  • teleport(x, y?, z?, rx?, ry?, rz?): 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. This function has three valid signatures. The first takes a 3-dimensional vector for the position and an optional 3-dimensional vector for Euler rotation. The second takes a 3-dimensional vector for the position and an optional quaternion for rotation. The third takes 3 numbers for the position and an optional 3 numbers for Euler rotation.

    Parameters

    • x: number | Vec3

      A 3-dimensional vector holding the new position or the new position x-coordinate.

    • Optionaly: number | Vec3 | Quat

      A 3-dimensional vector or quaternion holding the new rotation or the new position y-coordinate.

    • Optionalz: number

      The new position z-coordinate.

    • Optionalrx: number

      The new Euler x-angle value.

    • Optionalry: number

      The new Euler y-angle value.

    • Optionalrz: number

      The new Euler z-angle value.

    Returns void

    Example

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

    Example

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

    Example

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

    Example

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

Events

StaticEVENT_COLLISIONEND

EVENT_COLLISIONEND: string = 'collisionend'

Fired when two rigid bodies stop touching. The handler is passed a ContactResult object containing details of the contact between the two rigid bodies.

Example

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

StaticEVENT_COLLISIONSTART

EVENT_COLLISIONSTART: string = 'collisionstart'

Fired when two rigid bodies start touching. The handler is passed a ContactResult object containing details of the contact between the two rigid bodies.

Example

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

StaticEVENT_CONTACT

EVENT_CONTACT: string = 'contact'

Fired when a contact occurs between two rigid bodies. The handler is passed a ContactResult object containing details of the contact between the two rigid bodies.

Example

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

StaticEVENT_TRIGGERENTER

EVENT_TRIGGERENTER: string = 'triggerenter'

Fired when a rigid body enters a trigger volume. The handler is passed an Entity representing the trigger volume that this rigid body entered.

Example

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

StaticEVENT_TRIGGERLEAVE

EVENT_TRIGGERLEAVE: string = 'triggerleave'

Fired when a rigid body exits a trigger volume. The handler is passed an Entity representing the trigger volume that this rigid body exited.

Example

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

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods
Events