API Reference

Class List

pc.RigidBodyComponent

Extends: pc.Component

The rigidbody component, when combined with a pc.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.

Summary

Properties

angularDamping

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

angularFactor

Scaling factor for angular movement of the body in each axis.

angularVelocity

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

friction

The friction value used when contacts occur between two bodies.

group

The collision group this body belongs to.

linearDamping

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

linearFactor

Scaling factor for linear movement of the body in each axis.

linearVelocity

Defines the speed of the body in a given direction.

mask

The collision mask sets which groups this body collides with.

mass

The mass of the body.

restitution

Influences the amount of energy lost when two rigid bodies collide.

type

The rigid body type determines how the body is simulated.

Methods

activate

Forcibly activate the rigid body simulation.

applyForce

Apply an force to the body at a point.

applyImpulse

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

applyTorque

Apply torque (rotational force) to the body.

applyTorqueImpulse

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

isActive

Returns true if the rigid body is currently actively being simulated.

isKinematic

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

isStatic

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

isStaticOrKinematic

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

teleport

Teleport an entity to a new world-space position, optionally setting orientation.

Events

collisionend

The 'collisionend' event is fired two rigid-bodies stop touching.

collisionstart

The 'collisionstart' event is fired when two rigid bodies start touching.

contact

The 'contact' event is fired when a contact occurs between two rigid bodies.

triggerenter

The 'triggerenter' event is fired when a rigid body enters a trigger volume.

triggerleave

The 'triggerleave' event is fired when a rigid body exits a trigger volume.

Inherited

Properties

enabled

Enables or disables the component.

entity

The Entity that this Component is attached to.

system

The ComponentSystem used to create this Component.

Methods

fire

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

hasEvent

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

off

Detach an event handler from an event.

on

Attach an event handler to an event.

once

Attach an event handler to an event.

Details

Constructor

RigidBodyComponent(system, entity)

Create a new RigidBodyComponent.

Parameters

systempc.RigidBodyComponentSystem

The ComponentSystem that created this component.

entitypc.Entity

The entity this component is attached to.

Properties

numberangularDamping

Controls the rate at which a body loses angular velocity over time. Defaults to 0.

pc.Vec3angularFactor

Scaling factor for angular movement of the body in each axis. Defaults to 1 in all axes.

pc.Vec3angularVelocity

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

numberfriction

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.

numbergroup

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

numberlinearDamping

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

pc.Vec3linearFactor

Scaling factor for linear movement of the body in each axis. Defaults to 1 in all axes.

pc.Vec3linearVelocity

Defines the speed of the body in a given direction.

numbermask

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

numbermass

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

numberrestitution

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

stringtype

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

Defaults to pc.BODYTYPE_STATIC.

Methods

activate()

Forcibly activate the rigid body simulation.

applyForce(x, [y], [z], [px], [py], [pz])

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.

// 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 at the body's center
// Calculate a force vector pointing in the world space direction of the entity
var force = this.entity.forward.clone().scale(100);

// Apply the force
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
var force = this.entity.forward.clone().scale(100);

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

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

Parameters

xpc.Vec3, number

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

ypc.Vec3, number

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.

znumber

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

pxnumber

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

pynumber

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

pznumber

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

applyImpulse(x, [y], [z], [px], [py], [pz])

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.

// Apply an impulse along the world-space positive y-axis at the entity's position.
var 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.
var impulse = new pc.Vec3(0, 10, 0);
var relativePoint = new pc.Vec3(0, 0, 1);
entity.rigidbody.applyImpulse(impulse, relativePoint);
// 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);

Parameters

xpc.Vec3, number

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

ypc.Vec3, number

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.

znumber

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

pxnumber

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

pynumber

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

pznumber

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

applyTorque(x, [y], [z])

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.

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

Parameters

xpc.Vec3, number

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

ynumber

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

znumber

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

applyTorqueImpulse(x, [y], [z])

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.

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

Parameters

xpc.Vec3, number

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

ynumber

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

znumber

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

isActive()

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

Returns

boolean

True if the body is active.

isKinematic()

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

Returns

boolean

True if kinematic.

isStatic()

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

Returns

boolean

True if static.

isStaticOrKinematic()

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

Returns

boolean

True if static or kinematic.

teleport(x, y, [z], [rx], [ry], [rz])

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.

// Teleport the entity to the origin
entity.rigidbody.teleport(pc.Vec3.ZERO);
// 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
var position = new pc.Vec3(1, 2, 3);
entity.rigidbody.teleport(position, pc.Vec3.ZERO);
// Teleport the entity to world-space coordinate [1, 2, 3] and reset orientation
entity.rigidbody.teleport(1, 2, 3, 0, 0, 0);

Parameters

xpc.Vec3, number

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

ypc.Vec3, pc.Quat, number

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

znumber

The new position z-coordinate.

rxnumber

The new Euler x-angle value.

rynumber

The new Euler y-angle value.

rznumber

The new Euler z-angle value.

Events

collisionend

The 'collisionend' event is fired two rigid-bodies stop touching.

Parameters

otherpc.Entity

The pc.Entity that stopped touching this rigid body.

collisionstart

The 'collisionstart' event is fired when two rigid bodies start touching.

Parameters

resultpc.ContactResult

Details of the contact between the two rigid bodies.

contact

The 'contact' event is fired when a contact occurs between two rigid bodies.

Parameters

resultpc.ContactResult

Details of the contact between the two rigid bodies.

triggerenter

The 'triggerenter' event is fired when a rigid body enters a trigger volume.

Parameters

otherpc.Entity

The pc.Entity with trigger volume that this rigidbody entered.

triggerleave

The 'triggerleave' event is fired when a rigid body exits a trigger volume.

Parameters

otherpc.Entity

The pc.Entity with trigger volume that this rigidbody exited.

Inherited

Properties

booleanenabled

Enables or disables the component.

pc.Entityentity

The Entity that this Component is attached to.

pc.ComponentSystemsystem

The ComponentSystem used to create this Component.

Methods

fire(name, [arg1], [arg2], [arg3], [arg4], [arg5], [arg6], [arg7], [arg8])

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

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

Parameters

nameobject

Name of event to fire.

arg1*

First argument that is passed to the event handler.

arg2*

Second argument that is passed to the event handler.

arg3*

Third argument that is passed to the event handler.

arg4*

Fourth argument that is passed to the event handler.

arg5*

Fifth argument that is passed to the event handler.

arg6*

Sixth argument that is passed to the event handler.

arg7*

Seventh argument that is passed to the event handler.

arg8*

Eighth argument that is passed to the event handler.

Returns

pc.EventHandler

Self for chaining.

hasEvent(name)

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

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

Parameters

namestring

The name of the event to test.

Returns

boolean

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

off([name], [callback], [scope])

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.

var 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 hander functions, called 'test' with scope this

Parameters

namestring

Name of the event to unbind.

callbackpc.callbacks.HandleEvent

Function to be unbound.

scopeobject

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

Returns

pc.EventHandler

Self for chaining.

on(name, callback, [scope])

Attach an event handler to an event.

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

Parameters

namestring

Name of the event to bind the callback to.

callbackpc.callbacks.HandleEvent

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

scopeobject

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

Returns

pc.EventHandler

Self for chaining.

once(name, callback, [scope])

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

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

Parameters

namestring

Name of the event to bind the callback to.

callbackpc.callbacks.HandleEvent

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

scopeobject

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

Returns

pc.EventHandler

Self for chaining.