Class ModelComponent

The ModelComponent enables an Entity to render 3D models. 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 Model. This can either be created programmatically or loaded from an Asset.

The Model managed by this component is 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 ModelComponent constructor directly. To add a ModelComponent to an Entity, use Entity#addComponent:

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

Once the ModelComponent is added to the entity, you can access it via the model property:

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

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

Hierarchy (View Summary)

Component
- ModelComponent

Index

Constructors

constructor

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

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(): null | number | Asset
Gets the model asset id for the component.

Returns null | number | Asset
set asset(value: null | number | Asset): void
Sets the model asset (or asset id) for the component. This only applies to model components with type 'asset'.
Parameters
- value: null | number | Asset
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

mapping

get mapping(): {}
Gets the dictionary that holds material overrides for each mesh instance.

Returns {}
set mapping(value: {}): void
Sets the dictionary that holds material overrides for each mesh instance. Only applies to model components of type 'asset'. The mapping contains pairs of mesh instance index to material asset id.
Parameters
- value: {}
Returns void

material

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

Returns Material
set material(value: Material): void
Sets the Material that will be used to render the model. The material is ignored for renders of type 'asset'.
Parameters
- value: Material
Returns void

materialAsset

get materialAsset(): null | number | Asset
Gets the material Asset that will be used to render the component.

Returns null | number | Asset
set materialAsset(value: null | number | Asset): void
Sets the material Asset that will be used to render the component. The material is ignored for renders of type 'asset'.
Parameters
- value: null | number | Asset
Returns void

meshInstances

get meshInstances(): null | MeshInstance[]
Gets the array of mesh instances contained in the component's model.

Returns null | MeshInstance[]
set meshInstances(value: null | MeshInstance[]): void
Sets the array of mesh instances contained in the component's model.
Parameters
- value: null | MeshInstance[]
Returns void

model

get model(): Model
Gets the model owned by this component. In this case a model is not set or loaded, this will return null.

Returns Model
set model(value: Model): void
Sets the model owned by this component.
Parameters
- value: Model
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

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 model. This asset, assigned to the asset property, contains a Model. Alternatively, model 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 model without removing it from the scene hierarchy. This method sets the MeshInstance#visible property of every MeshInstance in the model to false Note, this does not remove the model or mesh instances from the scene hierarchy or draw call list. So the model component still incurs some CPU overhead.

Returns void

Example

this.timer = 0;
this.visible = true;
// ...
// blink model every 0.1 seconds
this.timer += dt;
if (this.timer > 0.1) {
    if (!this.visible) {
        this.entity.model.show();
        this.visible = true;
    } else {
        this.entity.model.hide();
        this.visible = false;
    }
    this.timer = 0;
}

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 model if hidden using ModelComponent#hide. This method sets all the MeshInstance#visible property on all mesh instances to true.

Returns void

Class ModelComponent

Hierarchy (View Summary)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns ModelComponent

Properties

entity

isStatic

system

Accessors

asset

Returns null | number | Asset

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

mapping

Returns {}

Parameters

Returns void

material

Returns Material

Parameters

Returns void

materialAsset

Returns null | number | Asset

Parameters

Returns void

meshInstances

Returns null | MeshInstance[]

Parameters

Returns void

model

Returns Model

Parameters

Returns void

receiveShadows

Returns boolean

Parameters

Returns void

type

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

Parameters

Returns void