Create a new RigidBodyComponent instance.
The ComponentSystem that created this component.
The entity this component is attached to.
Private _angularPrivate _angularPrivate _angularPrivate _bodyPrivate _frictionPrivate _groupPrivate _linearPrivate _linearPrivate _linearPrivate _maskPrivate _massPrivate _restitutionPrivate _rollingPrivate _simulationPrivate _typeThe Entity that this Component is attached to.
The ComponentSystem used to create this Component.
Controls the rate at which a body loses angular velocity over time.
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).
Enables or disables the component.
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.
The collision group this body belongs to. Combine the group and the mask to prevent bodies colliding with each other. Defaults to 1.
Controls the rate at which a body loses linear velocity over time. Defaults to 0.
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).
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.
The mass of the body. This is only relevant for BODYTYPE_DYNAMIC bodies, other types have infinite mass. Defaults to 1.
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.
Sets a torsional friction orthogonal to the contact point. Defaults to 0.
The rigid body type determines how the body is simulated. Can be:
Defaults to BODYTYPE_STATIC.
Private _getPrivate _updatePrivate _updateForcibly activate the rigid body simulation. Only affects rigid bodies of type BODYTYPE_DYNAMIC.
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.
A 3-dimensional vector representing the force in world-space or the x-component of the force in world-space.
Optional y: number | Vec3An 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.
Optional z: numberThe z-component of the force in world-space.
Optional px: numberThe x-component of a world-space offset from the body's position where the force is applied.
Optional py: numberThe y-component of a world-space offset from the body's position where the force is applied.
Optional pz: numberThe z-component of a world-space offset from the body's position where the force is applied.
// 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
const force = this.entity.forward.clone().mulScalar(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
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);
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.
A 3-dimensional vector representing the impulse in world-space or the x-component of the impulse in world-space.
Optional y: number | Vec3An 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.
Optional z: numberThe z-component of the impulse to apply in world-space.
Optional px: numberThe x-component of the point at which to apply the impulse in the local-space of the entity.
Optional py: numberThe y-component of the point at which to apply the impulse in the local-space of the entity.
Optional pz: numberThe z-component of the point at which to apply the impulse in the local-space of the entity.
// 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 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 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.
A 3-dimensional vector representing the torque force in world-space or the x-component of the torque force in world-space.
Optional y: numberThe y-component of the torque force in world-space.
Optional z: numberThe z-component of the torque force in world-space.
// Apply via vector
const torque = new pc.Vec3(0, 10, 0);
entity.rigidbody.applyTorque(torque);
// Apply via numbers
entity.rigidbody.applyTorque(0, 10, 0);
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.
A 3-dimensional vector representing the torque impulse in world-space or the x-component of the torque impulse in world-space.
Optional y: numberThe y-component of the torque impulse in world-space.
Optional z: numberThe z-component of the torque impulse in world-space.
// Apply via vector
const torque = new pc.Vec3(0, 10, 0);
entity.rigidbody.applyTorqueImpulse(torque);
// Apply via numbers
entity.rigidbody.applyTorqueImpulse(0, 10, 0);
Private createFire an event, all additional arguments are passed on to the event listener.
Name of event to fire.
Optional arg1: anyFirst argument that is passed to the event handler.
Optional arg2: anySecond argument that is passed to the event handler.
Optional arg3: anyThird argument that is passed to the event handler.
Optional arg4: anyFourth argument that is passed to the event handler.
Optional arg5: anyFifth argument that is passed to the event handler.
Optional arg6: anySixth argument that is passed to the event handler.
Optional arg7: anySeventh argument that is passed to the event handler.
Optional arg8: anyEighth argument that is passed to the event handler.
Self for chaining.
obj.fire('test', 'This is the message');
Test if there are any handlers bound to an event name.
The name of the event to test.
True if the object has handlers bound to the specified event name.
obj.on('test', function () { }); // bind an event to 'test'
obj.hasEvent('test'); // returns true
obj.hasEvent('hello'); // returns false
Returns true if the rigid body is of type BODYTYPE_KINEMATIC.
True if kinematic.
Returns true if the rigid body is of type BODYTYPE_STATIC.
True if static.
Returns true if the rigid body is of type BODYTYPE_STATIC or BODYTYPE_KINEMATIC.
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.
Optional name: stringName of the event to unbind.
Optional callback: HandleEventCallbackFunction to be unbound.
Optional scope: objectScope that was used as the this when the event is fired.
Self for chaining.
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
Attach an event handler to an event.
Name of the event to bind the callback to.
Function that is called when event is fired. Note the callback is limited to 8 arguments.
Optional scope: object = ...Object to use as 'this' when the event is fired, defaults to current this.
Can be used for removing event in the future.
obj.on('test', function (a, b) {
console.log(a + b);
});
obj.fire('test', 1, 2); // prints 3 to the console
const evt = obj.on('test', function (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.
Name of the event to bind the callback to.
Function that is called when event is fired. Note the callback is limited to 8 arguments.
Optional scope: object = ...Object to use as 'this' when the event is fired, defaults to current this.
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
Private syncPrivate Set the rigid body transform to be the same as the Entity transform. This must be called after any Entity transformation functions (e.g. Entity#setPosition) are called in order to update the rigid body to match the Entity.
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.
A 3-dimensional vector holding the new position or the new position x-coordinate.
Optional y: number | Vec3 | QuatA 3-dimensional vector or quaternion holding the new rotation or the new position y-coordinate.
Optional z: numberThe new position z-coordinate.
Optional rx: numberThe new Euler x-angle value.
Optional ry: numberThe new Euler y-angle value.
Optional rz: numberThe new Euler z-angle value.
// 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
const 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);
Static EVENT_Fired when two rigid bodies stop touching. The handler is passed a ContactResult object containing details of the contact between the two rigid bodies.
entity.rigidbody.on('collisionend', (result) => {
console.log(`Collision ended between ${entity.name} and ${result.other.name}`);
});
Static EVENT_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}`);
});
Static EVENT_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}`);
});
Static EVENT_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}`);
});
Static EVENT_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}`);
});
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:
To create a dynamic sphere with mass of 10, do:
Relevant 'Engine-only' examples: