V7

How To

Mirror Engine API

Mirror Engine API / RenderComponent

Class: RenderComponent

The RenderComponent enables an Entity to render 3D meshes. The RenderComponent#type property can be set to one of several predefined shape types (such as box, sphere, cone and so on). Alternatively, the component can be configured to manage an arbitrary array of MeshInstance objects. These can either be created programmatically or loaded from an Asset.

You should never need to use the RenderComponent constructor directly. To add a RenderComponent to an Entity, use Entity#addComponent:

// Add a render component to an entity with the default options
const entity = new Entity()
entity.addComponent('render') // This defaults to a 1x1x1 box

To create an entity with a specific primitive shape:

entity.addComponent('render', {
  type: 'cone',
  castShadows: false,
  receiveShadows: false
})

Once the RenderComponent is added to the entity, you can set and get any of its properties:

entity.render.type = 'capsule' // Set the render component's type

console.log(entity.render.type) // Get the render component's type and print it

Extends

Component

Properties

entity

entity: Entity

The Entity that this Component is attached to.

Inherited from

Component.entity

isStatic

isStatic: boolean = false

Mark meshes as non-movable (optimization).

system

system: ComponentSystem

The ComponentSystem used to create this Component.

Inherited from

Component.system

asset

Get Signature

get asset(): number

Gets the render asset id for the render component.

Returns

number

Set Signature

set asset(value: number): void

Sets the render asset (or asset id) for the render component. This only applies to render components with type 'asset'.

Parameters

value

number

Returns

void

batchGroupId

Get Signature

get batchGroupId(): number

Gets the batch group for the mesh instances in this component (see BatchGroup).

Returns

number

Set Signature

set batchGroupId(value: number): void

Sets the batch group for the mesh instances in this component (see BatchGroup). Default is -1 (no group).

Parameters

value

number

Returns

void

castShadows

Get Signature

get castShadows(): boolean

Gets whether attached meshes will cast shadows for lights that have shadow casting enabled.

Returns

boolean

Set Signature

set castShadows(value: boolean): void

Sets whether attached meshes will cast shadows for lights that have shadow casting enabled.

Parameters

value

boolean

Returns

void

castShadowsLightmap

Get Signature

get castShadowsLightmap(): boolean

Gets whether meshes instances will cast shadows when rendering lightmaps.

Returns

boolean

Set Signature

set castShadowsLightmap(value: boolean): void

Sets whether meshes instances will cast shadows when rendering lightmaps.

Parameters

value

boolean

Returns

void

customAabb

Get Signature

get customAabb(): null | BoundingBox

Gets the custom object space bounding box that is used for visibility culling of attached mesh instances.

Returns

null | BoundingBox

Set Signature

set customAabb(value: null | BoundingBox): void

Sets the custom object space bounding box that is used for visibility culling of attached mesh instances. This is an optimization, allowing an oversized bounding box to be specified for skinned characters in order to avoid per frame bounding box computations based on bone positions.

Parameters

value

null | BoundingBox

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

layers

Get Signature

get layers(): number[]

Gets the array of layer IDs (Layer#id) to which the mesh instances belong.

Returns

number[]

Set Signature

set layers(value: number[]): void

Sets the array of layer IDs (Layer#id) to which the mesh instances belong. Don't push, pop, splice or modify this array. If you want to change it, set a new one instead.

Parameters

value

number[]

Returns

void

lightmapped

Get Signature

get lightmapped(): boolean

Gets whether the component is affected by the runtime lightmapper.

Returns

boolean

Set Signature

set lightmapped(value: boolean): void

Sets whether the component is affected by the runtime lightmapper. If true, the meshes will be lightmapped after using lightmapper.bake().

Parameters

value

boolean

Returns

void

lightmapSizeMultiplier

Get Signature

get lightmapSizeMultiplier(): number

Gets the lightmap resolution multiplier.

Returns

number

Set Signature

set lightmapSizeMultiplier(value: number): void

Sets the lightmap resolution multiplier.

Parameters

value

number

Returns

void

material

Get Signature

get material(): Material

Gets the material Material that will be used to render the component.

Returns

Set Signature

set material(value: Material): void

Sets the material Material that will be used to render the component. The material is ignored for renders of type 'asset'.

Parameters

value

Returns

void

materialAssets

Get Signature

get materialAssets(): number[] | Asset[]

Gets the material assets that will be used to render the component.

Returns

number[] | Asset[]

Set Signature

set materialAssets(value: number[] | Asset[]): void

Sets the material assets that will be used to render the component. Each material corresponds to the respective mesh instance.

Parameters

value

number[] | Asset[]

Returns

void

meshInstances

Get Signature

get meshInstances(): MeshInstance[]

Gets the array of meshInstances contained in the component.

Returns

MeshInstance[]

Set Signature

set meshInstances(value: MeshInstance[]): void

Sets the array of meshInstances contained in the component.

Parameters

value

MeshInstance[]

Returns

void

receiveShadows

Get Signature

get receiveShadows(): boolean

Gets whether shadows will be cast on attached meshes.

Returns

boolean

Set Signature

set receiveShadows(value: boolean): void

Sets whether shadows will be cast on attached meshes.

Parameters

value

boolean

Returns

void

renderStyle

Get Signature

get renderStyle(): number

Gets the render style of this component's MeshInstances.

Returns

number

Set Signature

set renderStyle(renderStyle: number): void

Sets the render style of this component's MeshInstances. Can be:

Defaults to RENDERSTYLE_SOLID.

Parameters

renderStyle

number

Returns

void

rootBone

Get Signature

get rootBone(): null | Entity

Gets the root bone entity for the render component.

Returns

null | Entity

Set Signature

set rootBone(value: null | Entity): void

Sets the root bone entity (or entity guid) for the render component.

Parameters

value

null | Entity

Returns

void

type

Get Signature

get type(): string

Gets the type of the component.

Returns

string

Set Signature

set type(value: string): void

Sets the type of the component. Can be one of the following:

"asset": The component will render a render asset
"box": The component will render a box (1 unit in each dimension)
"capsule": The component will render a capsule (radius 0.5, height 2)
"cone": The component will render a cone (radius 0.5, height 1)
"cylinder": The component will render a cylinder (radius 0.5, height 1)
"plane": The component will render a plane (1 unit in each dimension)
"sphere": The component will render a sphere (radius 0.5)
"torus": The component will render a torus (tubeRadius: 0.2, ringRadius: 0.3)

Parameters

value

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

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

hide()

hide(): void

Stop rendering MeshInstances without removing them from the scene hierarchy. This method sets the MeshInstance#visible property of every MeshInstance to false. Note, this does not remove the mesh instances from the scene hierarchy or draw call list. So the render component still incurs some CPU overhead.

Returns

void

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

show()

show(): void

Enable rendering of the component's MeshInstances if hidden using RenderComponent#hide. This method sets the MeshInstance#visible property on all mesh instances to true.

Returns

void