How To

Class: CollisionComponent

A collision volume. Use this in conjunction with a RigidBodyComponent to make a collision volume that can be simulated using the physics engine.

If the Entity does not have a RigidBodyComponent then this collision volume will act as a trigger volume. When an entity with a dynamic or kinematic body enters or leaves an entity with a trigger volume, both entities will receive trigger events.

The following table shows all the events that can be fired between two Entities:

	Rigid Body		Rigid Body (Static)
Rigid Body (Static)		contact collisionstart collisionend
Rigid Body (Dynamic or Kinematic)	contact collisionstart collisionend	contact collisionstart collisionend	triggerenter triggerleave
Trigger Volume		triggerenter triggerleave

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

angularOffset

Get Signature

get angularOffset(): Quat

Gets the rotational offset of the collision shape from the Entity rotation in local space.

Returns

Quat

Set Signature

set angularOffset(arg: Quat): void

Sets the rotational offset of the collision shape from the Entity rotation in local space. Defaults to identity.

Parameters

arg

Quat

Returns

void

asset

Get Signature

get asset(): null | number | Asset

Gets the asset or asset id for the model of the mesh collision volume.

Returns

null | number | Asset

Set Signature

set asset(arg: null | number | Asset): void

Sets the asset or asset id for the model of the mesh collision volume. Defaults to null.

Parameters

arg

null | number | Asset

Returns

void

axis

Get Signature

get axis(): number

Gets the local space axis with which the capsule, cylinder or cone-shaped collision volume's length is aligned.

Returns

number

Set Signature

set axis(arg: number): void

Sets the local space axis with which the capsule, cylinder or cone-shaped collision volume's length is aligned. 0 for X, 1 for Y and 2 for Z. Defaults to 1 (Y-axis).

Parameters

arg

number

Returns

void

checkVertexDuplicates

Get Signature

get checkVertexDuplicates(): boolean

Gets whether checking for duplicate vertices should be enabled when creating collision meshes.

Returns

boolean

Set Signature

set checkVertexDuplicates(arg: boolean): void

Sets whether checking for duplicate vertices should be enabled when creating collision meshes.

Parameters

arg

boolean

Returns

void

convexHull

Get Signature

get convexHull(): boolean

Gets whether the collision mesh should be treated as a convex hull.

Returns

boolean

Set Signature

set convexHull(arg: boolean): void

Sets whether the collision mesh should be treated as a convex hull. When false, the mesh can only be used with a static body. When true, the mesh can be used with a static, dynamic or kinematic body. Defaults to false.

Parameters

arg

boolean

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

Overrides

Component.enabled

halfExtents

Get Signature

get halfExtents(): Vec3

Gets the half-extents of the box-shaped collision volume in the x, y and z axes.

Returns

Vec3

Set Signature

set halfExtents(arg: Vec3): void

Sets the half-extents of the box-shaped collision volume in the x, y and z axes. Defaults to [0.5, 0.5, 0.5].

Parameters

arg

Vec3

Returns

void

height

Get Signature

get height(): number

Gets the total height of the capsule, cylinder or cone-shaped collision volume from tip to tip.

Returns

number

Set Signature

set height(arg: number): void

Sets the total height of the capsule, cylinder or cone-shaped collision volume from tip to tip. Defaults to 2.

Parameters

arg

number

Returns

void

linearOffset

Get Signature

get linearOffset(): Vec3

Gets the positional offset of the collision shape from the Entity position along the local axes.

Returns

Vec3

Set Signature

set linearOffset(arg: Vec3): void

Sets the positional offset of the collision shape from the Entity position along the local axes. Defaults to [0, 0, 0].

Parameters

arg

Vec3

Returns

void

model

Get Signature

get model(): null | Model

Gets the model that is added to the scene graph for the mesh collision volume.

Returns

null | Model

Set Signature

set model(arg: null | Model): void

Sets the model that is added to the scene graph for the mesh collision volume.

Parameters

arg

null | Model

Returns

void

radius

Get Signature

get radius(): number

Gets the radius of the sphere, capsule, cylinder or cone-shaped collision volumes.

Returns

number

Set Signature

set radius(arg: number): void

Sets the radius of the sphere, capsule, cylinder or cone-shaped collision volumes. Defaults to 0.5.

Parameters

arg

number

Returns

void

renderAsset

Get Signature

get renderAsset(): null | number | Asset

Gets the render asset id of the mesh collision volume.

Returns

null | number | Asset

Set Signature

set renderAsset(arg: null | number | Asset): void

Sets the render asset or asset id of the mesh collision volume. Defaults to null. If not set then the asset property will be checked instead.

Parameters

arg

null | number | Asset

Returns

void

type

Get Signature

get type(): string

Gets the type of the collision volume.

Returns

string

Set Signature

set type(arg: string): void

Sets the type of the collision volume. Can be:

"box": A box-shaped collision volume.
"capsule": A capsule-shaped collision volume.
"compound": A compound shape. Any descendant entities with a collision component of type box, capsule, cone, cylinder or sphere will be combined into a single, rigid shape.
"cone": A cone-shaped collision volume.
"cylinder": A cylinder-shaped collision volume.
"mesh": A collision volume that uses a model asset as its shape.
"sphere": A sphere-shaped collision volume.

Defaults to "box".

Parameters

arg

string

Returns

void

Methods

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

getShapePosition()

getShapePosition(): Vec3

Returns the world position for the collision shape, taking into account of any offsets.

Returns

Vec3

The world position for the collision shape.

getShapeRotation()

getShapeRotation(): Quat

Returns the world rotation for the collision shape, taking into account of any offsets.

Returns

Quat

The world rotation for the collision.

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

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

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.collision.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 the ContactResult object which contains details of the contact between the two rigid bodies.

Example

entity.collision.on('collisionstart', (result) => {
  console.log(`${'${entity.name}'} started touching ${'${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 which contains details of the contact between the two rigid bodies.

Example

entity.collision.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 rigid body that entered this collision volume.

Example

entity.collision.on('triggerenter', (other) => {
  console.log(`${'${other.name}'} entered trigger volume ${'${entity.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 rigid body that exited this collision volume.

Example

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