Engine API Reference - v2.20.0-beta.0
    Preparing search index...

    Class RigidBodyComponent

    The RigidBodyComponent, when combined with a CollisionComponent, 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, use Entity#addComponent:

    // Create a static 1x1x1 box-shaped rigid body
    const entity = new pc.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:

    const entity = new pc.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 property:

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

    Relevant Engine API examples:

    Hierarchy (View Summary)

    Index

    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

    Properties

    entity: Entity

    The Entity that this Component is attached to.

    system: ComponentSystem

    The ComponentSystem used to create this Component.

    Accessors

    • get angularDamping(): number

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

      Returns number

    • set angularDamping(damping: number): void

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

      Parameters

      • damping: number

      Returns void

    • get angularFactor(): Vec3

      Gets the scaling factor for angular movement of the body in each axis.

      Returns Vec3

    • set angularFactor(factor: Vec3): void

      Sets the scaling factor for angular movement of the body in each axis. Only valid for rigid bodies of type BODYTYPE_DYNAMIC. Defaults to 1 in all axes (body can freely rotate).

      Parameters

      Returns void

    • get angularVelocity(): Vec3

      Gets the rotational speed of the body around each world axis.

      Returns Vec3

    • set angularVelocity(velocity: Vec3): void

      Sets the rotational speed of the body around each world axis.

      Parameters

      Returns void

    • get enabled(): boolean

      Gets the enabled state of the component.

      Returns boolean

    • set enabled(arg: boolean): void

      Sets the enabled state of the component.

      Parameters

      • arg: boolean

      Returns void

    • get friction(): number

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

      Returns number

    • set friction(friction: number): void

      Sets the friction value used when contacts occur between two bodies. A higher value indicates more friction. Should be set in the range 0 to 1. Defaults to 0.5.

      Parameters

      • friction: number

      Returns void

    • get group(): number

      Gets the collision group this body belongs to.

      Returns number

    • set group(group: number): void

      Sets the collision group this body belongs to. Combine the group and the mask to prevent bodies colliding with each other. Defaults to 1.

      Parameters

      • group: number

      Returns void

    • get linearDamping(): number

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

      Returns number

    • set linearDamping(damping: number): void

      Sets the rate at which a body loses linear velocity over time. Defaults to 0.

      Parameters

      • damping: number

      Returns void

    • get linearFactor(): Vec3

      Gets the scaling factor for linear movement of the body in each axis.

      Returns Vec3

    • set linearFactor(factor: Vec3): void

      Sets the scaling factor for linear movement of the body in each axis. Only valid for rigid bodies of type BODYTYPE_DYNAMIC. Defaults to 1 in all axes (body can freely move).

      Parameters

      Returns void

    • get linearVelocity(): Vec3

      Gets the speed of the body in a given direction.

      Returns Vec3

    • set linearVelocity(velocity: Vec3): void

      Sets the speed of the body in a given direction.

      Parameters

      Returns void

    • get mask(): number

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

      Returns number

    • set mask(mask: number): void

      Sets the collision mask sets which groups this body collides with. It is a bit field of 16 bits, the first 8 bits are reserved for engine use. Defaults to 65535.

      Parameters

      • mask: number

      Returns void

    • get mass(): number

      Gets the mass of the body.

      Returns number

    • set mass(mass: number): void

      Sets the mass of the body. This is only relevant for BODYTYPE_DYNAMIC bodies, other types have infinite mass. Defaults to 1.

      Parameters

      • mass: number

      Returns void

    • get restitution(): number

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

      Returns number

    • set restitution(restitution: number): 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

    • get rollingFriction(): number

      Gets the torsional friction orthogonal to the contact point.

      Returns number

    • set rollingFriction(friction: number): void

      Sets the torsional friction orthogonal to the contact point. Defaults to 0.

      Parameters

      • friction: number

      Returns void

    • get type(): "static" | "dynamic" | "kinematic"

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

      Returns "static" | "dynamic" | "kinematic"

    • set type(type: "static" | "dynamic" | "kinematic"): void

      Sets the rigid body type determines how the body is simulated. Can be:

      Defaults to BODYTYPE_STATIC.

      Parameters

      • type: "static" | "dynamic" | "kinematic"

      Returns void

    Methods

    • Forcibly activate the rigid body simulation. Only affects rigid bodies of type BODYTYPE_DYNAMIC.

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

      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.

      • Optionalpx: number

        X-component of the relative point at which to apply the force in world space.

      • Optionalpy: number

        Y-component of the relative point at which to apply the force in world space.

      • Optionalpz: number

        Z-component of the relative point at which to apply the force in world space.

      Returns void

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

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

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

      Parameters

      • force: Vec3

        Vector representing the force in world space.

      • OptionalrelativePoint: Vec3

        Optional vector representing the relative point at which to apply the force in world space.

      Returns void

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

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

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

    • Apply an impulse (instantaneous change of velocity) to the body at a point.

      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.

      • Optionalpx: number

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

      • Optionalpy: number

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

      • Optionalpz: number

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

      Returns void

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

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

    • Apply an impulse (instantaneous change of velocity) to the body at a point.

      Parameters

      • impulse: Vec3

        Vector representing the impulse in world space.

      • OptionalrelativePoint: Vec3

        Optional vector representing the relative point at which to apply the impulse in the local space of the entity.

      Returns void

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

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

    • 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

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

    • Apply torque (rotational force) to the body.

      Parameters

      • torque: Vec3

        Vector representing the torque force in world space.

      Returns void

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

    • 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

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

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

      Parameters

      • torque: Vec3

        Vector representing the torque impulse in world space.

      Returns void

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

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

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

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

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

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

      Returns boolean

      True if the body is active.

    • Returns true if the rigid body is of type BODYTYPE_KINEMATIC.

      Returns boolean

      True if kinematic.

    • Returns true if the rigid body is of type BODYTYPE_STATIC.

      Returns boolean

      True if static.

    • Returns true if the rigid body is of type BODYTYPE_STATIC or BODYTYPE_KINEMATIC.

      Returns boolean

      True if static or kinematic.

    • 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: any

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

      Returns EventHandler

      Self for chaining.

      const handler = () => {};
      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

    • 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: any = ...

        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.

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

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

    • 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: any = ...

        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.

      obj.once('test', (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 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.

      • Optionalrx: number

        X-rotation of the world space Euler angles in degrees.

      • Optionalry: number

        Y-rotation of the world space Euler angles in degrees.

      • Optionalrz: number

        Z-rotation of the world space Euler angles in degrees.

      Returns void

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

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

    • 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

        Vector holding the new world space position.

      • Optionalangles: Vec3

        Vector holding the new world space Euler angles in degrees.

      Returns void

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

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

    • 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

        Vector holding the new world space position.

      • Optionalrotation: Quat

        Quaternion holding the new world space rotation.

      Returns void

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

      // 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.Quat.IDENTITY);

    Events

    EVENT_COLLISIONEND: string = 'collisionend'

    Fired when two rigid bodies stop touching. The handler is passed an Entity that represents the other rigid body involved in the collision.

    entity.rigidbody.on('collisionend', (other) => {
        console.log(`${entity.name} stopped touching ${other.name}`);
    });
    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.

    entity.rigidbody.on('collisionstart', (result) => {
        console.log(`Collision started between ${entity.name} and ${result.other.name}`);
    });
    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.

    entity.rigidbody.on('contact', (result) => {
       console.log(`Contact between ${entity.name} and ${result.other.name}`);
    });
    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.

    entity.rigidbody.on('triggerenter', (trigger) => {
        console.log(`Entity ${entity.name} entered trigger volume ${trigger.name}`);
    });
    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.

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

    Settings

    Member Visibility

    On This Page

    Properties
    Accessors
    Methods
    Events