Class RenderComponent

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

The MeshInstances managed by this component are positioned, rotated, and scaled in world space by the world transformation matrix of the owner Entity. This world matrix is derived by combining the entity's local transformation (position, rotation, and scale) with the world transformation matrix of its parent entity in the scene hierarchy.

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

const entity = new pc.Entity();
entity.addComponent('render', {
    type: 'box'
});

Once the RenderComponent is added to the entity, you can access it via the render property:

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

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

Relevant Engine API examples:

Hierarchy (View Summary)

Component
- RenderComponent

Index

Constructors

constructor

new RenderComponent(
system: RenderComponentSystem,
entity: Entity,
): RenderComponent
Create a new RenderComponent.
Parameters
- system: RenderComponentSystem
  The ComponentSystem that created this Component.
- entity: Entity
  The Entity that this Component is attached to.
Returns RenderComponent

Properties

entity

entity: Entity

The Entity that this Component is attached to.

isStatic

isStatic: boolean = false

Mark meshes as non-movable (optimization).

system

system: ComponentSystem

The ComponentSystem used to create this Component.

Accessors

asset

get asset(): number
Gets the render asset id for the render component.

Returns number
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 batchGroupId(): number
Gets the batch group for the mesh instances in this component (see BatchGroup).

Returns number
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 castShadows(): boolean
Gets whether attached meshes will cast shadows for lights that have shadow casting enabled.

Returns boolean
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 castShadowsLightmap(): boolean
Gets whether meshes instances will cast shadows when rendering lightmaps.

Returns boolean
set castShadowsLightmap(value: boolean): void
Sets whether meshes instances will cast shadows when rendering lightmaps.
Parameters
- value: boolean
Returns void

customAabb

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 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 enabled(): boolean
Gets the enabled state of the component.

Returns boolean
set enabled(arg: boolean): void
Sets the enabled state of the component.
Parameters
- arg: boolean
Returns void

layers

get layers(): number[]
Gets the array of layer IDs (Layer#id) to which the mesh instances belong.

Returns number[]
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 lightmapped(): boolean
Gets whether the component is affected by the runtime lightmapper.

Returns boolean
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 lightmapSizeMultiplier(): number
Gets the lightmap resolution multiplier.

Returns number
set lightmapSizeMultiplier(value: number): void
Sets the lightmap resolution multiplier.
Parameters
- value: number
Returns void

material

get material(): Material
Gets the material Material that will be used to render the component.

Returns Material
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: Material
Returns void

materialAssets

get materialAssets(): number[] | Asset[]
Gets the material assets that will be used to render the component.

Returns number[] | Asset[]
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 meshInstances(): MeshInstance[]
Gets the array of meshInstances contained in the component.

Returns MeshInstance[]
set meshInstances(value: MeshInstance[]): void
Sets the array of meshInstances contained in the component.
Parameters
- value: MeshInstance[]
Returns void

receiveShadows

get receiveShadows(): boolean
Gets whether shadows will be cast on attached meshes.

Returns boolean
set receiveShadows(value: boolean): void
Sets whether shadows will be cast on attached meshes.
Parameters
- value: boolean
Returns void

renderStyle

get renderStyle(): number
Gets the render style of this component's MeshInstances.

Returns number
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 rootBone(): null | Entity
Gets the root bone entity for the render component.

Returns null | Entity
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 type(): | "asset"
| "plane"
| "box"
| "sphere"
| "capsule"
| "cylinder"
| "cone"
| "torus"
Gets the type of the component.

Returns "asset" | "plane" | "box" | "sphere" | "capsule" | "cylinder" | "cone" | "torus"
set type(
    value:
        | "asset"
        | "plane"
        | "box"
        | "sphere"
        | "capsule"
        | "cylinder"
        | "cone"
        | "torus",
): void
Sets the type of the component, determining the source of the geometry to be rendered. The geometry, whether it's a primitive shape or originates from an asset, is rendered using the owning entity's final world transform. This world transform is calculated by concatenating (multiplying) the local transforms (position, rotation, scale) of the entity and all its ancestors in the scene hierarchy. This process positions, orientates, and scales the geometry in world space.

Can be one of the following values:
- "asset": Renders geometry defined in an Asset of type render. This asset, assigned to the asset property, contains one or more MeshInstances. Alternatively, meshInstances can be set programmatically.
- "box": A unit cube (sides of length 1) centered at the local space origin.
- "capsule": A shape composed of a cylinder and two hemispherical caps that is aligned with the local Y-axis. It is centered at the local space origin and has an unscaled height of 2 and a radius of 0.5.
- "cone": A cone aligned with the local Y-axis. It is centered at the local space origin, with its base in the local XZ plane at Y = -0.5 and its tip at Y = +0.5. It has an unscaled height of 1 and a base radius of 0.5.
- "cylinder": A cylinder aligned with the local Y-axis. It is centered at the local space origin with an unscaled height of 1 and a radius of 0.5.
- "plane": A flat plane in the local XZ plane at Y = 0 (normal along +Y). It is centered at the local space origin with unscaled dimensions of 1x1 units along local X and Z axes.
- "sphere": A sphere with a radius of 0.5. It is centered at the local space origin and has poles at Y = -0.5 and Y = +0.5.
- "torus": A doughnut shape lying in the local XZ plane at Y = 0. It is centered at the local space origin with a tube radius of 0.2 and a ring radius of 0.3.
Parameters
- value: "asset" | "plane" | "box" | "sphere" | "capsule" | "cylinder" | "cone" | "torus"
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.
- Optionalarg1: any
  First argument that is passed to the event handler.
- Optionalarg2: any
  Second argument that is passed to the event handler.
- Optionalarg3: any
  Third argument that is passed to the event handler.
- Optionalarg4: any
  Fourth argument that is passed to the event handler.
- Optionalarg5: any
  Fifth argument that is passed to the event handler.
- Optionalarg6: any
  Sixth argument that is passed to the event handler.
- Optionalarg7: any
  Seventh argument that is passed to the event handler.
- Optionalarg8: any
  Eighth argument that is passed to the event handler.
Returns EventHandler
Self for chaining.
Example
```
obj.fire('test', 'This is the message');
```

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
```

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
- Optionalname: string
  Name of the event to unbind.
- Optionalcallback: HandleEventCallback
  Function to be unbound.
- Optionalscope: 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
```

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.
- Optionalscope: 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.on('test', (a, b) => {
    console.log(a + b);
});
obj.fire('test', 1, 2); // prints 3 to the console
```
Example
```
const evt = obj.on('test', (a, b) => {
    console.log(a + b);
});
// some time later
evt.off();
```

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.
- Optionalscope: 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
```

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

Class RenderComponent

Hierarchy (View Summary)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns RenderComponent

Properties

entity

isStatic

system

Accessors

asset

Returns number

Parameters

Returns void

batchGroupId

Returns number

Parameters

Returns void

castShadows

Returns boolean

Parameters

Returns void

castShadowsLightmap

Returns boolean

Parameters

Returns void

customAabb

Returns null | BoundingBox

Parameters

Returns void

enabled

Returns boolean

Parameters

Returns void

layers

Returns number[]

Parameters

Returns void

lightmapped

Returns boolean

Parameters

Returns void

lightmapSizeMultiplier

Returns number

Parameters

Returns void

material

Returns Material

Parameters

Returns void

materialAssets

Returns number[] | Asset[]

Parameters

Returns void

meshInstances

Returns MeshInstance[]

Parameters

Returns void

receiveShadows

Returns boolean

Parameters

Returns void

renderStyle

Returns number

Parameters

Returns void

rootBone

Returns null | Entity

Parameters

Returns void

type

Returns "asset" | "plane" | "box" | "sphere" | "capsule" | "cylinder" | "cone" | "torus"

Parameters

Returns void