
Mirror Engine API / CollisionComponent
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 (Dynamic or Kinematic) | Trigger Volume | ||
---|---|---|---|---|---|
Rigid Body (Static) |
| ||||
Rigid Body (Dynamic or Kinematic) |
|
|
| ||
Trigger Volume |
|
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
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
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
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
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
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
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
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
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
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
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
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
- 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}'}`)
})