Mirror Engine
V5
How To
Mirror Engine Logo

Mirror Engine API


Mirror Engine API / RigidBodyComponent

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 = 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 = Entity()
entity.addComponent('rigidbody', {
  type: BODYTYPE_DYNAMIC,
  mass: 10
})
entity.addComponent('collision', {
  type: 'sphere'
})

Extends

  • Component

Properties

entity

entity: Entity

The Entity that this Component is attached to.

Inherited from

Component.entity

system

system: ComponentSystem

The ComponentSystem used to create this Component.

Inherited from

Component.system

angularDamping

Get Signature

get angularDamping(): number

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

Returns

number

Set Signature

set angularDamping(damping: number): void

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

Parameters
damping

number

Returns

void


angularFactor

Get Signature

get angularFactor(): Vec3

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

Returns

Vec3

Set Signature

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
factor

Vec3

Returns

void


angularVelocity

Get Signature

get angularVelocity(): Vec3

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

Returns

Vec3

Set Signature

set angularVelocity(velocity: Vec3): void

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

Parameters
velocity

Vec3

Returns

void


enabled

Get Signature

get enabled(): boolean

Gets the enabled state of the component.

Returns

boolean

Set Signature

set enabled(arg: boolean): void

Sets the enabled state of the component.

Parameters
arg

boolean

Returns

void

Inherited from

Component.enabled

friction

Get Signature

get friction(): number

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

Returns

number

Set Signature

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


group

Get Signature

get group(): number

Gets the collision group this body belongs to.

Returns

number

Set Signature

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


linearDamping

Get Signature

get linearDamping(): number

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

Returns

number

Set Signature

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


linearFactor

Get Signature

get linearFactor(): Vec3

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

Returns

Vec3

Set Signature

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
factor

Vec3

Returns

void


linearVelocity

Get Signature

get linearVelocity(): Vec3

Gets the speed of the body in a given direction.

Returns

Vec3

Set Signature

set linearVelocity(velocity: Vec3): void

Sets the speed of the body in a given direction.

Parameters
velocity

Vec3

Returns

void


mask

Get Signature

get mask(): number

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

Returns

number

Set Signature

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


mass

Get Signature

get mass(): number

Gets the mass of the body.

Returns

number

Set Signature

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


restitution

Get Signature

get restitution(): number

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

Returns

number

Set Signature

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


rollingFriction

Get Signature

get rollingFriction(): number

Gets the torsional friction orthogonal to the contact point.

Returns

number

Set Signature

set rollingFriction(friction: number): void

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

Parameters
friction

number

Returns

void


type

Get Signature

get type(): string

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

Returns

string

Set Signature

set type(type: string): void

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

Defaults to BODYTYPE_STATIC.

Parameters
type

string

Returns

void

Methods

activate()

activate(): void

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

Returns

void


applyForce()

applyForce(
   x: number | Vec3,
   y?: number | Vec3,
   z?: number,
   px?: number,
   py?: number,
   pz?: number): 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

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

number | Vec3

y?

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.

number | Vec3

z?

number

The z-component of the force in world space.

px?

number

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

py?

number

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

pz?

number

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

Returns

void

Examples

// 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 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: number | Vec3,
   y?: number | Vec3,
   z?: number,
   px?: number,
   py?: number,
   pz?: number): 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

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

number | Vec3

y?

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.

number | Vec3

z?

number

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

px?

number

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

py?

number

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

pz?

number

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

Returns

void

Examples

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

applyTorque()

applyTorque(
   x: number | Vec3,
   y?: number,
   z?: number): 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

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

number | Vec3

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

Examples

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

applyTorqueImpulse()

applyTorqueImpulse(
   x: number | Vec3,
   y?: number,
   z?: number): 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

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

number | Vec3

y?

number

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

z?

number

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

Returns

void

Examples

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

fire()

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

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

Parameters

name

string

Name of event to fire.

arg1?

any

First argument that is passed to the event handler.

arg2?

any

Second argument that is passed to the event handler.

arg3?

any

Third argument that is passed to the event handler.

arg4?

any

Fourth argument that is passed to the event handler.

arg5?

any

Fifth argument that is passed to the event handler.

arg6?

any

Sixth argument that is passed to the event handler.

arg7?

any

Seventh argument that is passed to the event handler.

arg8?

any

Eighth argument that is passed to the event handler.

Returns

EventHandler

Self for chaining.

Example

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

Inherited from

Component.fire

hasEvent()

hasEvent(name: string): 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', () => {}) // bind an event to 'test'
obj.hasEvent('test') // returns true
obj.hasEvent('hello') // returns false

Inherited from

Component.hasEvent

isActive()

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()

isKinematic(): boolean

Returns true if the rigid body is of type BODYTYPE_KINEMATIC.

Returns

boolean

True if kinematic.


isStatic()

isStatic(): boolean

Returns true if the rigid body is of type BODYTYPE_STATIC.

Returns

boolean

True if static.


isStaticOrKinematic()

isStaticOrKinematic(): boolean

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

Returns

boolean

True if static or kinematic.


off()

off(
   name?: string,
   callback?: HandleEventCallback,
   scope?: any): 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

name?

string

Name of the event to unbind.

callback?

HandleEventCallback

Function to be unbound.

scope?

any

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

Returns

EventHandler

Self for chaining.

Example

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

Inherited from

Component.off

on()

on(
   name: string,
   callback: HandleEventCallback,
   scope?: any): 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.

scope?

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.

Examples

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()

Inherited from

Component.on

once()

once(
   name: string,
   callback: HandleEventCallback,
   scope?: any): 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.

scope?

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.

Example

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

Inherited from

Component.once

teleport()

teleport(
   x: number | Vec3,
   y?: number | Vec3 | Quat,
   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. 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

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

number | Vec3

y?

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

number | Vec3 | Quat

z?

number

The new position z-coordinate.

rx?

number

The new Euler x-angle value.

ry?

number

The new Euler y-angle value.

rz?

number

The new Euler z-angle value.

Returns

void

Examples

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

Events

EVENT_COLLISIONEND

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

Example

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

EVENT_COLLISIONSTART

static 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}'}`
  )
})

EVENT_CONTACT

static 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}'}`
  )
})

EVENT_TRIGGERENTER

static 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}'}`
  )
})

EVENT_TRIGGERLEAVE

static 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}'}`
  )
})
Mirror Engine Logo