API (v2.0.0) - Giro3D
    Preparing search index...

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

    The class inherits three.js' EventDispatcher.

    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';

    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.

    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.

    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

    Hierarchy (View Summary)

    Implements

    Index

    Constructors

    constructor

    Properties

    id isEntity name type userData

    Accessors

    frozen instance loading progress ready

    Methods

    dispose filterChangeSources notifyChange postUpdate preprocess preUpdate shouldCheckForUpdate shouldFullUpdate shouldUpdate update

    Constructors

    Properties

    id: string

    The unique identifier of this entity.

    isEntity: boolean = ...

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

    name: string | undefined

    The name of this entity.

    type: string

    The name of the type of this object.

    userData: TUserData

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

    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: boolean): void

      Parameters

      • v: boolean

      Returns void

    • 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

    • get ready(): boolean

      Determine if this entity is ready to use.

      Returns boolean

    Methods

    • 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

    • Notifies the parent instance that a change occured in the scene.

      Parameters

      • Optionalsource: unknown

      Returns void

    • 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

    • 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

      Returns Promise<void>

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

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

      the elements to update during update().

    • 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

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

      New elements to update

    Settings

    Member Visibility

    On This Page

    The propertyLifetimeThe update methodsA note on "parts"
    Constructors
    Properties
    Accessors
    Methods