Class Entity<TEventMap, TUserData>`Abstract`

Abstract base class for all entities in Giro3D. The Entity is the core component of Giro3D and represent an updatable object that is added to an Instance.

The class inherits three.js' EventDispatcher.

The `userData` property

The userData property can be used to attach custom data to the entity, in a type safe manner. It is recommended to use this property instead of attaching arbitrary properties to the object:

type MyCustomUserData = {
  creationDate: Date;
  owner: string;
};
const entity: Entity<MyCustomUserData> = ...;

entity.userData.creationDate = Date.now();
entity.userData.owner = 'John Doe';

Lifetime

The lifetime of an entity follows this pattern: when the entity is added to an instance, its preprocess method is called. When the promise returned by this method resolves, the entity can be used in the main loop, where the update methods (see below) will be used to update the entity over time. Finally, when the entity is removed from the instance, its dispose method is called to cleanup memory.

The update methods

This class exposes three methods to update the object:

Entity.preUpdate to determine which parts of the object should actually be updated.
Entity.update called for each part returned by preUpdate()
Entity.postUpdate to finalize the update step.

A note on "parts"

The notion of "part to be updated" is entity-specific. For example, if the entity is a tiled map, the parts may be map tiles. If the entity is a point cloud, it may be point clusters, and so on. On the other hand, if the entity is not made of distinct objects, the "part to update" may be the entity itself, or a dummy object.

const instance = new Instance(...);
const entity = new Entity('exampleEntity');
instance.add(entity);

Type Parameters

TEventMap extends EntityEventMap = EntityEventMap
The event map of the entity.
TUserData = EntityUserData
The type of the userData property.

Hierarchy (view full)

EventDispatcher<TEventMap & EntityEventMap>
- Entity
  - Entity3D

Implements

core.Disposable

Index

Constructors

constructor

new Entity<TEventMap, TUserData>(): Entity<TEventMap, TUserData>
Creates an entity with the specified unique identifier.
Type Parameters
- TEventMap extends EntityEventMap = EntityEventMap
- TUserData = EntityUserData
Returns Entity<TEventMap, TUserData>
Overrides EventDispatcher.constructor
- Defined in entities/Entity.ts:128

Properties

`Readonly`id

id: string

The unique identifier of this entity.

`Readonly`isEntity

isEntity: boolean = ...

Read-only flag to check if a given object is of type Entity.

name

name: undefined | string

The name of this entity.

type

type: string

The name of the type of this object.

`Readonly`userData

userData: TUserData

An object that can be used to store custom data about the Entity.

Accessors

frozen

get frozen(): boolean
Gets or sets the frozen status of this entity. A frozen entity is still visible but will not be updated automatically.

Useful for debugging purposes.

Returns boolean
- Defined in entities/Entity.ts:144
set frozen(v): void
Parameters
- v: boolean
Returns void
- Defined in entities/Entity.ts:148

instance

get instance(): Instance
Returns Instance
- Defined in entities/Entity.ts:96

loading

get loading(): boolean
Gets whether this entity is currently loading data.

Returns boolean
- Defined in entities/Entity.ts:158

progress

get progress(): number
Gets the current loading progress (between 0 and 1). Note: This property is only meaningful if loading is true.

Returns number
- Defined in entities/Entity.ts:167

ready

get ready(): boolean
Determine if this entity is ready to use.

Returns boolean
- Defined in entities/Entity.ts:92

Methods

addEventListener

addEventListener<T>(type, listener): void
Adds a listener to an event type.
Type Parameters
- T extends string
Parameters
- type: T
  The type of event to listen to.
- listener: EventListener<(TEventMap & EntityEventMap)[T], T, Entity<TEventMap, TUserData>>
  The function that gets called when the event is fired.
Returns void
Inherited from EventDispatcher.addEventListener
- Defined in ../node_modules/@types/three/src/core/EventDispatcher.d.ts:52
addEventListener<T>(type, listener): void
Type Parameters
- T extends string
Parameters
- type: T
- listener: EventListener<{}, T, Entity<TEventMap, TUserData>>
Returns void
Inherited from EventDispatcher.addEventListener
- Defined in ../node_modules/@types/three/src/core/EventDispatcher.d.ts:56

dispatchEvent

dispatchEvent<T>(event): void
Fire an event type.
Type Parameters
- T extends string
Parameters
- event: BaseEvent<T> & (TEventMap & EntityEventMap)[T]
  The event that gets fired.
Returns void
Inherited from EventDispatcher.dispatchEvent
- Defined in ../node_modules/@types/three/src/core/EventDispatcher.d.ts:84

dispose

dispose(): void
Disposes this entity and all resources associated with it.

The default implementation of this method does nothing. You should implement it in your custom entities to handle any special logic of disposal.

For example: disposing materials, geometries, stopping HTTP requests, etc.

Returns void
Implementation of Disposable.dispose
- Defined in entities/Entity.ts:330

filterChangeSources

filterChangeSources(updateSources): Set<unknown>
Filters what objects need to be updated, based on updatedSources. The returned objects are then passed to preUpdate and postUpdate.

Inherited classes should override shouldFullUpdate and shouldUpdate if they need to change this behavior.
Parameters
- updateSources: Set<unknown>
  Sources that triggered an update
Returns Set<unknown>
Set of objects to update
- Defined in entities/Entity.ts:254

hasEventListener

hasEventListener<T>(type, listener): boolean
Checks if listener is added to an event type.
Type Parameters
- T extends string
Parameters
- type: T
  The type of event to listen to.
- listener: EventListener<(TEventMap & EntityEventMap)[T], T, Entity<TEventMap, TUserData>>
  The function that gets called when the event is fired.
Returns boolean
Inherited from EventDispatcher.hasEventListener
- Defined in ../node_modules/@types/three/src/core/EventDispatcher.d.ts:63
hasEventListener<T>(type, listener): boolean
Type Parameters
- T extends string
Parameters
- type: T
- listener: EventListener<{}, T, Entity<TEventMap, TUserData>>
Returns boolean
Inherited from EventDispatcher.hasEventListener
- Defined in ../node_modules/@types/three/src/core/EventDispatcher.d.ts:67

`Protected`notifyChange

notifyChange(source?): void
Notifies the parent instance that a change occured in the scene.
Parameters
- Optionalsource: unknown
Returns void
- Defined in entities/Entity.ts:337

postUpdate

postUpdate(context, changeSources): void
Method called after Entity.update.
Parameters
- context: Context
  the update context.
- changeSources: Set<unknown>
  the objects that triggered an update step. This is useful to filter out unnecessary updates if no sources are relevant to this entity. For example, if one of the sources is a camera that moved during the previous frame, any entity that depends on the camera's field of view should be updated.
Returns void
- Defined in entities/Entity.ts:317

`Protected`preprocess

preprocess(_opts): Promise<void>
Asynchronously preprocess the entity. This method may be overriden to perform any operation that must be done before the entity can be used in the scene, such as fetching metadata about a dataset, etc.
Parameters
- _opts: EntityPreprocessOptions
Returns Promise<void>
A promise that resolves when the entity is ready to be used.
- Defined in entities/Entity.ts:181

preUpdate

preUpdate(context, changeSources): null | unknown[]
This method is called just before update() to filter and select which elements should be actually updated. For example, in the case of complex entities made of a hierarchy of elements, the entire hierarchy may not need to be updated.

Use this method to optimize the update step by reducing the number of elements to process.

Note: if this functions returns nothing, update() will not be called.
Parameters
- context: Context
  the update context.
- changeSources: Set<unknown>
  the objects that triggered an update step. This is useful to filter out unnecessary updates if no sources are relevant to this entity. For example, if one of the sources is a camera that moved during the previous frame, any entity that depends on the camera's field of view should be updated.
Returns null | unknown[]
the elements to update during update().
- Defined in entities/Entity.ts:286

removeEventListener

removeEventListener<T>(type, listener): void
Removes a listener from an event type.
Type Parameters
- T extends string
Parameters
- type: T
  The type of the listener that gets removed.
- listener: EventListener<(TEventMap & EntityEventMap)[T], T, Entity<TEventMap, TUserData>>
  The listener function that gets removed.
Returns void
Inherited from EventDispatcher.removeEventListener
- Defined in ../node_modules/@types/three/src/core/EventDispatcher.d.ts:74
removeEventListener<T>(type, listener): void
Type Parameters
- T extends string
Parameters
- type: T
- listener: EventListener<{}, T, Entity<TEventMap, TUserData>>
Returns void
Inherited from EventDispatcher.removeEventListener
- Defined in ../node_modules/@types/three/src/core/EventDispatcher.d.ts:78

shouldCheckForUpdate

shouldCheckForUpdate(): boolean
This method is called before update to check if the MainLoop should try to update this entity or not. For better performances, it should return false if the entity has no impact on the rendering (e.g. the element is not visible).

The inherited child can completely ignore this value if it makes sense.

Returns boolean
true if should check for update
- Defined in entities/Entity.ts:207

shouldFullUpdate

shouldFullUpdate(updateSource): boolean
This method is called at the beginning of the update step to determine if we should do a full render of the object. This should be the case if, for instance, the source is the camera.

You can override this depending on your needs. The inherited child should not ignore this value, it should do a boolean OR, e.g.: return super.shouldFullUpdate(updateSource) || this.contains(updateSource);
Parameters
- updateSource: unknown
  Source of change
Returns boolean
true if requires a full update of this object
- Defined in entities/Entity.ts:223

shouldUpdate

shouldUpdate(updateSource): boolean
This method is called at the beginning of the update step to determine if we should re-render updateSource. Not used when shouldFullUpdate returns true.

You can override this depending on your needs. The inherited child should not ignore this value, it should do a boolean OR, e.g.: return super.shouldUpdate(updateSource) || this.contains(updateSource);
Parameters
- updateSource: unknown
  Source of change
Returns boolean
true if requires an update of updateSource
- Defined in entities/Entity.ts:240

update

update(context, element): undefined | null | unknown[]
Performs an update on an element of the entity.

Note: this method will be called for each element returned by preUpdate().
Parameters
- context: Context
  the update context. This is the same object that the entity whose update() is being called.
- element: unknown
  the element to update. This is one of the elements returned by preUpdate.
Returns undefined | null | unknown[]
New elements to update
- Defined in entities/Entity.ts:302

Class Entity<TEventMap, TUserData>Abstract

The userData property

Lifetime

The update methods

A note on "parts"

Type Parameters

Hierarchy (view full)

Implements

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Type Parameters

Returns Entity<TEventMap, TUserData>

Properties

Readonlyid

ReadonlyisEntity

name

type

ReadonlyuserData

Accessors

frozen

Returns boolean

Parameters

Returns void

instance

Returns Instance

loading

Returns boolean

progress

Returns number

ready

Returns boolean

Methods

addEventListener

Type Parameters

Parameters

Returns void

Type Parameters

Parameters

Returns void

dispatchEvent

Type Parameters

Parameters

Returns void

dispose

Returns void

filterChangeSources

Parameters

Returns Set<unknown>

hasEventListener

Type Parameters

Parameters

Returns boolean

Type Parameters

Parameters

Returns boolean

ProtectednotifyChange

Parameters

Returns void

postUpdate

Parameters

Returns void

Protectedpreprocess

Parameters

Returns Promise<void>

preUpdate

Parameters

Returns null | unknown[]

removeEventListener

Type Parameters

Parameters

Returns void

Type Parameters

Parameters

Returns void

shouldCheckForUpdate

Class Entity<TEventMap, TUserData>`Abstract`

The `userData` property

`Readonly`id

`Readonly`isEntity

`Readonly`userData

`Protected`notifyChange

`Protected`preprocess