Component

A component adds functionality to an Object3D. An object can have multiple components but an instance of a component can be directly related to only one Object3D.

The Component class defines the behavior of a component. We need to extend from this class to create our own components. We should never call the Component's methods ourselves. These are to be called exclusively within the Engine.

When creating a component through the editor's interface (Assets -> Component) a component will be created with the standard template, so you shouldn't have to create a component by hand but, in any case, let's see how hey are built.

In the following example, we have a component MyComponent which extends the class Component. After defining it, we register it. If we don't register it, the component won't be accessible from anywhere. This is the way to let the Engine acknowledge it.


import * as RE from 'rogue-engine';

export class MyComponent extends RE.Component {
...
}

RE.registerComponent(MyComponent);

Constructor


constructor(name: string, object3d: THREE.Object3D)

The Component class constructor takes a name string and an Object3D as parameters. The Object3D will be assigned to the Component.object3d property. Normally, after instantiating a component you would need to add it with the engine's addComponent() function, otherwise, the component will be there on standby doing nothing.

In the following example, we import our component MyComponent and use the getObjectByName method in the App.currentScene object which is the current Three.js Scene. Then we instantiate the component and add it to the engine's component map with addComponent. That's the cue for the engine to start executing its behavior methods in the next cycle.


import { addComponent, App } from 'rogue-engine';
import { MyComponent } from './MyComponent'
...
const object3d = App.currentScene.getObjectByName(MyObject);
const component = new MyComponent(MyComponentName, object3d);

addComponent(component);
...

Properties

.name

name: string

The name of the component. This can be used as an identifier to retrieve it with the getComponentByName function.

Component.interface


static interface: ComponentInterface

The static interface object defines the graphic interface of our component.

This property has a ComponentInterface type which, maps a property name with a specific string describing the type of the property:

type ComponentInterface = {
  [propName: string]:
    | "String"
    | "Number"
    | "Boolean"
    | "Object3D"
    | "Prefab"
    | "Texture"
    | "Material"
    | "Component"
    | "Audio"
    | "PositionalAudio";
}

Each of these options will display a different type of property controller interface in the Component inspector.

Keep in mind that poropName must be a valid public property within the component.

Example


import * as RE from 'rogue-engine';

export class MyComponent extends RE.Component {
  speed: number;

  interface: RE.ComponentInterface = {
    speed: 'Number'
  }
...

.object3d

readonly object3d: THREE.Object3D

This is the Object3D to which this component belongs.

.isReady

readonly isReady: boolean

This property returns the ready state of the component. A component is considered ready when all of the assets declared in its interface property are loaded.

A component that is not ready will only execute the awake method. As soon as the component is ready its start method will be executed and it will join the next update cycle.

When using the component from another script, you should check this property to make sure the assets declared in its interface property are loaded before using them. you can safely use them in all methods of the component they belong to, with exception of its awake method.

If all the assets declared in its interface property are set to preload in the AssetManager or have been kept loaded from previous scenes, the component will be immediately ready.

Methods

All of the following methods are meant to be overridden. This means that they should be declared within your component class if you need them. But that's all you should do with them. They will be called internally by the engine and you should never call them in your code.

.awake

awake(): void

If the scene is not running, the awake methods of all components in that scene are called by the engine right before the first render.

If the scene is running, this method is called by the engine immediately after the component is initialized.

.start

start(): void

If the scene is not running, the start methods of all components in that scene are called by the engine right after the first render.

If the scene is running, this method is called by the engine as soon as the isReady property of the component returns true, which means that all of the assets referenced in its interface are loaded.

.beforeUpdate

beforeUpdate(): void

This method is called by the engine just before the update method. It defines the very beginning of every frame for a component. It should be used exclusively for things that need to be available before all the update methods are executed.

.update

update(): void

This method is called by the engine just after beforeUpdate and right before afterUpdate. Here's where you, for example, move objects in your scene. Be mindful that this will be called every frame and will stack up with the rest of the components in your scene. Remember: keep your code tight and your frame rate high.

.afterUpdate

afterUpdate(): void

This method is called by the engine just after update and it marks the end of every cycle of the animation loop. Here's where you add things that need to happen after all the update methods have been called.

.onBeforeRemoved

onBeforeRemoved(): void

This method will be executed when the removeComponent method is called with this component as a parameter, just before removing it from the components map.

.onRemoved

onRemoved(): void

This method will be executed when the removeComponent method is called with this component as a parameter, right after it has been effectively removed from the components map and the scene.

.onBeforeObjetRemoved

onBeforeObjetRemoved(): void

This method will be executed just before the remove method for the Object3D to which this object belongs is called.

.onObjectRemoved

onObjectRemoved(): void

This method will be executed right after the remove method for the Object3D to which this object belongs is called.