@animech-public/playcanvas/build/playcanvas/src/framework/entity.d.ts

PlayCanvas WebGL game engine

/**
 * The Entity is the core primitive of a PlayCanvas game. Generally speaking an object in your game
 * will consist of an {@link Entity}, and a set of {@link Component}s which are managed by their
 * respective {@link ComponentSystem}s. One of those components maybe a {@link ScriptComponent}
 * which allows you to write custom code to attach to your Entity.
 *
 * The Entity uniquely identifies the object and also provides a transform for position and
 * orientation which it inherits from {@link GraphNode} so can be added into the scene graph. The
 * Component and ComponentSystem provide the logic to give an Entity a specific type of behavior.
 * e.g. the ability to render a model or play a sound. Components are specific to an instance of an
 * Entity and are attached (e.g. `this.entity.model`) ComponentSystems allow access to all Entities
 * and Components and are attached to the {@link AppBase}.
 */
export class Entity extends GraphNode {
    /**
     * Fired after the entity is destroyed.
     *
     * @event
     * @example
     * entity.on('destroy', (e) => {
     *     console.log(`Entity ${e.name} has been destroyed`);
     * });
     */
    static EVENT_DESTROY: string;
    /**
     * Create a new Entity.
     *
     * @param {string} [name] - The non-unique name of the entity, default is "Untitled".
     * @param {import('./app-base.js').AppBase} [app] - The application the entity belongs to,
     * default is the current application.
     * @example
     * const entity = new pc.Entity();
     *
     * // Add a Component to the Entity
     * entity.addComponent("camera", {
     *     fov: 45,
     *     nearClip: 1,
     *     farClip: 10000
     * });
     *
     * // Add the Entity into the scene graph
     * app.root.addChild(entity);
     *
     * // Move the entity
     * entity.translate(10, 0, 0);
     *
     * // Or translate it by setting its position directly
     * const p = entity.getPosition();
     * entity.setPosition(p.x + 10, p.y, p.z);
     *
     * // Change the entity's rotation in local space
     * const e = entity.getLocalEulerAngles();
     * entity.setLocalEulerAngles(e.x, e.y + 90, e.z);
     *
     * // Or use rotateLocal
     * entity.rotateLocal(0, 90, 0);
     */
    constructor(name?: string, app?: import("./app-base.js").AppBase);
    /**
     * Gets the {@link AnimComponent} attached to this entity.
     *
     * @type {import('./components/anim/component.js').AnimComponent|undefined}
     * @readonly
     */
    readonly anim: import("./components/anim/component.js").AnimComponent | undefined;
    /**
     * Gets the {@link AnimationComponent} attached to this entity.
     *
     * @type {import('./components/animation/component.js').AnimationComponent|undefined}
     * @readonly
     */
    readonly animation: import("./components/animation/component.js").AnimationComponent | undefined;
    /**
     * Gets the {@link AudioListenerComponent} attached to this entity.
     *
     * @type {import('./components/audio-listener/component.js').AudioListenerComponent|undefined}
     * @readonly
     */
    readonly audiolistener: import("./components/audio-listener/component.js").AudioListenerComponent | undefined;
    /**
     * Gets the {@link ButtonComponent} attached to this entity.
     *
     * @type {import('./components/button/component.js').ButtonComponent|undefined}
     * @readonly
     */
    readonly button: import("./components/button/component.js").ButtonComponent | undefined;
    /**
     * Gets the {@link CameraComponent} attached to this entity.
     *
     * @type {import('./components/camera/component.js').CameraComponent|undefined}
     * @readonly
     */
    readonly camera: import("./components/camera/component.js").CameraComponent | undefined;
    /**
     * Gets the {@link CollisionComponent} attached to this entity.
     *
     * @type {import('./components/collision/component.js').CollisionComponent|undefined}
     * @readonly
     */
    readonly collision: import("./components/collision/component.js").CollisionComponent | undefined;
    /**
     * Gets the {@link ElementComponent} attached to this entity.
     *
     * @type {import('./components/element/component.js').ElementComponent|undefined}
     * @readonly
     */
    readonly element: import("./components/element/component.js").ElementComponent | undefined;
    /**
     * Gets the {@link GSplatComponent} attached to this entity.
     *
     * @type {import('./components/gsplat/component.js').GSplatComponent|undefined}
     * @readonly
     */
    readonly gsplat: import("./components/gsplat/component.js").GSplatComponent | undefined;
    /**
     * Gets the {@link LayoutChildComponent} attached to this entity.
     *
     * @type {import('./components/layout-child/component.js').LayoutChildComponent|undefined}
     * @readonly
     */
    readonly layoutchild: import("./components/layout-child/component.js").LayoutChildComponent | undefined;
    /**
     * Gets the {@link LayoutGroupComponent} attached to this entity.
     *
     * @type {import('./components/layout-group/component.js').LayoutGroupComponent|undefined}
     * @readonly
     */
    readonly layoutgroup: import("./components/layout-group/component.js").LayoutGroupComponent | undefined;
    /**
     * Gets the {@link LightComponent} attached to this entity.
     *
     * @type {import('./components/light/component.js').LightComponent|undefined}
     * @readonly
     */
    readonly light: import("./components/light/component.js").LightComponent | undefined;
    /**
     * Gets the {@link ModelComponent} attached to this entity.
     *
     * @type {import('./components/model/component.js').ModelComponent|undefined}
     * @readonly
     */
    readonly model: import("./components/model/component.js").ModelComponent | undefined;
    /**
     * Gets the {@link ParticleSystemComponent} attached to this entity.
     *
     * @type {import('./components/particle-system/component.js').ParticleSystemComponent|undefined}
     * @readonly
     */
    readonly particlesystem: import("./components/particle-system/component.js").ParticleSystemComponent | undefined;
    /**
     * Gets the {@link RenderComponent} attached to this entity.
     *
     * @type {import('./components/render/component.js').RenderComponent|undefined}
     * @readonly
     */
    readonly render: import("./components/render/component.js").RenderComponent | undefined;
    /**
     * Gets the {@link RigidBodyComponent} attached to this entity.
     *
     * @type {import('./components/rigid-body/component.js').RigidBodyComponent|undefined}
     * @readonly
     */
    readonly rigidbody: import("./components/rigid-body/component.js").RigidBodyComponent | undefined;
    /**
     * Gets the {@link ScreenComponent} attached to this entity.
     *
     * @type {import('./components/screen/component.js').ScreenComponent|undefined}
     * @readonly
     */
    readonly screen: import("./components/screen/component.js").ScreenComponent | undefined;
    /**
     * Gets the {@link ScriptComponent} attached to this entity.
     *
     * @type {import('./components/script/component.js').ScriptComponent|undefined}
     * @readonly
     */
    readonly script: import("./components/script/component.js").ScriptComponent | undefined;
    /**
     * Gets the {@link ScrollbarComponent} attached to this entity.
     *
     * @type {import('./components/scrollbar/component.js').ScrollbarComponent|undefined}
     * @readonly
     */
    readonly scrollbar: import("./components/scrollbar/component.js").ScrollbarComponent | undefined;
    /**
     * Gets the {@link ScrollViewComponent} attached to this entity.
     *
     * @type {import('./components/scroll-view/component.js').ScrollViewComponent|undefined}
     * @readonly
     */
    readonly scrollview: import("./components/scroll-view/component.js").ScrollViewComponent | undefined;
    /**
     * Gets the {@link SoundComponent} attached to this entity.
     *
     * @type {import('./components/sound/component.js').SoundComponent|undefined}
     * @readonly
     */
    readonly sound: import("./components/sound/component.js").SoundComponent | undefined;
    /**
     * Gets the {@link SpriteComponent} attached to this entity.
     *
     * @type {import('./components/sprite/component.js').SpriteComponent|undefined}
     * @readonly
     */
    readonly sprite: import("./components/sprite/component.js").SpriteComponent | undefined;
    /**
     * Component storage.
     *
     * @type {Object<string, import('./components/component.js').Component>}
     * @ignore
     */
    c: {
        [x: string]: import("./components/component.js").Component;
    };
    /**
     * @type {import('./app-base.js').AppBase}
     * @private
     */
    private _app;
    /**
     * Used by component systems to speed up destruction.
     *
     * @type {boolean}
     * @ignore
     */
    _destroying: boolean;
    /**
     * @type {string|null}
     * @private
     */
    private _guid;
    /**
     * Used to differentiate between the entities of a template root instance, which have it set to
     * true, and the cloned instance entities (set to false).
     *
     * @type {boolean}
     * @ignore
     */
    _template: boolean;
    /**
     * Create a new component and add it to the entity. Use this to add functionality to the entity
     * like rendering a model, playing sounds and so on.
     *
     * @param {string} type - The name of the component to add. Valid strings are:
     *
     * - "anim" - see {@link AnimComponent}
     * - "animation" - see {@link AnimationComponent}
     * - "audiolistener" - see {@link AudioListenerComponent}
     * - "button" - see {@link ButtonComponent}
     * - "camera" - see {@link CameraComponent}
     * - "collision" - see {@link CollisionComponent}
     * - "element" - see {@link ElementComponent}
     * - "gsplat" - see {@link GSplatComponent}
     * - "layoutchild" - see {@link LayoutChildComponent}
     * - "layoutgroup" - see {@link LayoutGroupComponent}
     * - "light" - see {@link LightComponent}
     * - "model" - see {@link ModelComponent}
     * - "particlesystem" - see {@link ParticleSystemComponent}
     * - "render" - see {@link RenderComponent}
     * - "rigidbody" - see {@link RigidBodyComponent}
     * - "screen" - see {@link ScreenComponent}
     * - "script" - see {@link ScriptComponent}
     * - "scrollbar" - see {@link ScrollbarComponent}
     * - "scrollview" - see {@link ScrollViewComponent}
     * - "sound" - see {@link SoundComponent}
     * - "sprite" - see {@link SpriteComponent}
     *
     * @param {object} [data] - The initialization data for the specific component type. Refer to
     * each specific component's API reference page for details on valid values for this parameter.
     * @returns {import('./components/component.js').Component|null} The new Component that was
     * attached to the entity or null if there was an error.
     * @example
     * const entity = new pc.Entity();
     *
     * // Add a light component with default properties
     * entity.addComponent("light");
     *
     * // Add a camera component with some specified properties
     * entity.addComponent("camera", {
     *     fov: 45,
     *     clearColor: new pc.Color(1, 0, 0)
     * });
     */
    addComponent(type: string, data?: object): import("./components/component.js").Component | null;
    /**
     * Remove a component from the Entity.
     *
     * @param {string} type - The name of the Component type.
     * @example
     * const entity = new pc.Entity();
     * entity.addComponent("light"); // add new light component
     *
     * entity.removeComponent("light"); // remove light component
     */
    removeComponent(type: string): void;
    /**
     * Search the entity and all of its descendants for the first component of specified type.
     *
     * @param {string} type - The name of the component type to retrieve.
     * @returns {import('./components/component.js').Component} A component of specified type, if
     * the entity or any of its descendants has one. Returns undefined otherwise.
     * @example
     * // Get the first found light component in the hierarchy tree that starts with this entity
     * const light = entity.findComponent("light");
     */
    findComponent(type: string): import("./components/component.js").Component;
    /**
     * Search the entity and all of its descendants for all components of specified type.
     *
     * @param {string} type - The name of the component type to retrieve.
     * @returns {import('./components/component.js').Component[]} All components of specified type
     * in the entity or any of its descendants. Returns empty array if none found.
     * @example
     * // Get all light components in the hierarchy tree that starts with this entity
     * const lights = entity.findComponents("light");
     */
    findComponents(type: string): import("./components/component.js").Component[];
    /**
     * Search the entity and all of its descendants for the first script instance of specified type.
     *
     * @param {string|typeof import('./script/script-type.js').ScriptType} nameOrType - The name or type of {@link ScriptType}.
     * @returns {import('./script/script-type.js').ScriptType|undefined} A script instance of specified type, if the entity or any of its descendants
     * has one. Returns undefined otherwise.
     * @example
     * // Get the first found "playerController" instance in the hierarchy tree that starts with this entity
     * var controller = entity.findScript("playerController");
     */
    findScript(nameOrType: string | typeof import("./script/script-type.js").ScriptType): import("./script/script-type.js").ScriptType | undefined;
    /**
     * Search the entity and all of its descendants for all script instances of specified type.
     *
     * @param {string|typeof import('./script/script-type.js').ScriptType} nameOrType - The name or type of {@link ScriptType}.
     * @returns {import('./script/script-type.js').ScriptType[]} All script instances of specified type in the entity or any of its
     * descendants. Returns empty array if none found.
     * @example
     * // Get all "playerController" instances in the hierarchy tree that starts with this entity
     * var controllers = entity.findScripts("playerController");
     */
    findScripts(nameOrType: string | typeof import("./script/script-type.js").ScriptType): import("./script/script-type.js").ScriptType[];
    /**
     * Get the GUID value for this Entity.
     *
     * @returns {string} The GUID of the Entity.
     * @ignore
     */
    getGuid(): string;
    /**
     * Set the GUID value for this Entity. Note that it is unlikely that you should need to change
     * the GUID value of an Entity at run-time. Doing so will corrupt the graph this Entity is in.
     *
     * @param {string} guid - The GUID to assign to the Entity.
     * @ignore
     */
    setGuid(guid: string): void;
    /** @private */
    private _onHierarchyStatePostChanged;
    /**
     * Find a descendant of this entity with the GUID.
     *
     * @param {string} guid - The GUID to search for.
     * @returns {Entity|null} The entity with the matching GUID or null if no entity is found.
     */
    findByGuid(guid: string): Entity | null;
    /**
     * Create a deep copy of the Entity. Duplicate the full Entity hierarchy, with all Components
     * and all descendants. Note, this Entity is not in the hierarchy and must be added manually.
     *
     * @returns {this} A new Entity which is a deep copy of the original.
     * @example
     * const e = this.entity.clone();
     *
     * // Add clone as a sibling to the original
     * this.entity.parent.addChild(e);
     */
    clone(): this;
    /**
     * @param {Object<string, Entity>} duplicatedIdsMap - A map of original entity GUIDs to cloned
     * entities.
     * @returns {this} A new Entity which is a deep copy of the original.
     * @private
     */
    private _cloneRecursively;
}
import { GraphNode } from '../scene/graph-node.js';