Class Entity<TEventMap>

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 core.Instance.Instance.

The class inherits three.js' EventDispatcher.

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:

  • preUpdate() to determine which parts of the object should actually be updated.
  • update() called for each part returned by preUpdate()
  • 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.

Example

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

Type Parameters

Hierarchy

Constructors

  • Creates an entity with the specified unique identifier.

    Type Parameters

    Parameters

    • id: string

      the unique identifier of this entity.

    Returns Entity<TEventMap>

Properties

_frozen: boolean
_id: string
isEntity: boolean = true

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

ready?: boolean
type: string

The name of the type of this object.

userData: Record<string, any> = {}

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

whenReady?: Promise<Entity<TEventMap>>

Accessors

  • 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

  • set frozen(v): void
  • Parameters

    • v: boolean

    Returns void

  • get id(): string
  • Gets the unique identifier of this entity.

    Returns string

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

    Returns boolean

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

    Returns number

Methods

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

      The function that gets called when the event is fired.

    Returns void

  • Type Parameters

    • T extends string

    Parameters

    • type: T
    • listener: EventListener<{}, T, Entity<TEventMap>>

    Returns void

  • Fire an event type.

    Type Parameters

    • T extends string

    Parameters

    • event: BaseEvent<T> & (TEventMap & EntityEventMap)[T]

      The event that gets fired.

    Returns 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

  • 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

  • Attached layers expect to receive the visual representation of a layer (= THREE object with a material). So if a layer's update function don't process this kind of object, the layer must provide a getObjectToUpdateForAttachedLayers function that returns the correct object to update for attached layer from the objects returned by preUpdate.

    Parameters

    • obj: unknown

      the Mesh or the object containing a Mesh. These are the objects returned by preUpdate or update.

    Returns ObjectToUpdate

    an object passed to the update function of attached layers.

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

      The function that gets called when the event is fired.

    Returns boolean

  • Type Parameters

    • T extends string

    Parameters

    • type: T
    • listener: EventListener<{}, T, Entity<TEventMap>>

    Returns boolean

  • Method called after 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

  • 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 unknown[]

    the elements to update during update().

  • 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.

    Returns Promise<void>

    A promise that resolves when the entity is ready to be used.

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

      The listener function that gets removed.

    Returns void

  • Type Parameters

    • T extends string

    Parameters

    • type: T
    • listener: EventListener<{}, T, Entity<TEventMap>>

    Returns void

  • 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

  • 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

  • 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

  • Returns Entity<TEventMap>

  • 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 ().

    Returns unknown[]

    New elements to update

Generated using TypeDoc