# Entity

Class · extends [`GraphNode`](https://api.playcanvas.com/engine/classes/GraphNode.md) · category: Framework

Source: https://github.com/playcanvas/engine/blob/970d89f6d3bc6667f4e1f88153abd6e7e82ed52c/src/framework/entity.js#L153

An Entity is the core primitive of a PlayCanvas application. Every object in a scene (a camera, a
light, a 3D model, a sound source, a piece of UI, or your own gameplay object) is represented by
an Entity. On its own, an Entity is simply a named node in the scene graph; it gains behavior
from the [Component](https://api.playcanvas.com/engine/classes/Component.md)s attached to it.

An Entity therefore brings together two things:

- A transform: Entity extends [GraphNode](https://api.playcanvas.com/engine/classes/GraphNode.md), so it has a position, rotation and scale, and
can be parented to other entities to form a hierarchy. The root of that hierarchy is
[AppBase#root](https://api.playcanvas.com/engine/classes/AppBase.md#root), and child entities inherit the transforms of their ancestors.
- A set of components: each [Component](https://api.playcanvas.com/engine/classes/Component.md) adds a single capability. For example, a
[CameraComponent](https://api.playcanvas.com/engine/classes/CameraComponent.md) renders the scene, a [LightComponent](https://api.playcanvas.com/engine/classes/LightComponent.md) lights it, a
[RenderComponent](https://api.playcanvas.com/engine/classes/RenderComponent.md) draws a 3D mesh, and a [ScriptComponent](https://api.playcanvas.com/engine/classes/ScriptComponent.md) runs your own code.

Add a capability with [Entity#addComponent](https://api.playcanvas.com/engine/classes/Entity.md#addcomponent), access it later through the matching property
(such as [Entity#camera](https://api.playcanvas.com/engine/classes/Entity.md#camera) or [Entity#render](https://api.playcanvas.com/engine/classes/Entity.md#render)), and remove it with
[Entity#removeComponent](https://api.playcanvas.com/engine/classes/Entity.md#removecomponent). An entity, together with all of its descendants and their
components, can be enabled or disabled as a group via [GraphNode#enabled](https://api.playcanvas.com/engine/classes/GraphNode.md#enabled), and removed from
the scene with [Entity#destroy](https://api.playcanvas.com/engine/classes/Entity.md#destroy).

**Example**

```ts
// Create an entity, give it a camera component, position it, and add it to the scene
const camera = new Entity('camera');
camera.addComponent('camera', {
    clearColor: new Color(0.1, 0.1, 0.1)
});
camera.setPosition(0, 0, 10);
app.root.addChild(camera);
```

**Example**

```ts
// Entities form a hierarchy: a child inherits its parent's transform
const parent = new Entity('parent');
const child = new Entity('child');
parent.addChild(child);
parent.setLocalPosition(5, 0, 0); // moves both parent and child
```

## Constructors

### constructor

```ts
new Entity(name?: string, app?: AppBase)
```

Create a new Entity.

**Parameters**

- `name` (`string`, optional): The non-unique name of the entity, default is "Untitled".
- `app` ([`AppBase`](https://api.playcanvas.com/engine/classes/AppBase.md), optional): The application the entity belongs to, default is the current
  application.

**Example**

```ts
const entity = new 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);
```

## Properties

### anim

```ts
readonly anim: AnimComponent | undefined
```

Gets the [AnimComponent](https://api.playcanvas.com/engine/classes/AnimComponent.md) attached to this entity.

### animation

```ts
readonly animation: AnimationComponent | undefined
```

Gets the [AnimationComponent](https://api.playcanvas.com/engine/classes/AnimationComponent.md) attached to this entity.

### audiolistener

```ts
readonly audiolistener: AudioListenerComponent | undefined
```

Gets the [AudioListenerComponent](https://api.playcanvas.com/engine/classes/AudioListenerComponent.md) attached to this entity.

### button

```ts
readonly button: ButtonComponent | undefined
```

Gets the [ButtonComponent](https://api.playcanvas.com/engine/classes/ButtonComponent.md) attached to this entity.

### camera

```ts
readonly camera: CameraComponent | undefined
```

Gets the [CameraComponent](https://api.playcanvas.com/engine/classes/CameraComponent.md) attached to this entity.

### collision

```ts
readonly collision: CollisionComponent | undefined
```

Gets the [CollisionComponent](https://api.playcanvas.com/engine/classes/CollisionComponent.md) attached to this entity.

### element

```ts
readonly element: ElementComponent | undefined
```

Gets the [ElementComponent](https://api.playcanvas.com/engine/classes/ElementComponent.md) attached to this entity.

### gsplat

```ts
readonly gsplat: GSplatComponent | undefined
```

Gets the [GSplatComponent](https://api.playcanvas.com/engine/classes/GSplatComponent.md) attached to this entity.

### joint

```ts
readonly joint: JointComponent | undefined
```

Gets the [JointComponent](https://api.playcanvas.com/engine/classes/JointComponent.md) attached to this entity.

### layoutchild

```ts
readonly layoutchild: LayoutChildComponent | undefined
```

Gets the [LayoutChildComponent](https://api.playcanvas.com/engine/classes/LayoutChildComponent.md) attached to this entity.

### layoutgroup

```ts
readonly layoutgroup: LayoutGroupComponent | undefined
```

Gets the [LayoutGroupComponent](https://api.playcanvas.com/engine/classes/LayoutGroupComponent.md) attached to this entity.

### light

```ts
readonly light: LightComponent | undefined
```

Gets the [LightComponent](https://api.playcanvas.com/engine/classes/LightComponent.md) attached to this entity.

### model

```ts
readonly model: ModelComponent | undefined
```

Gets the [ModelComponent](https://api.playcanvas.com/engine/classes/ModelComponent.md) attached to this entity.

### particlesystem

```ts
readonly particlesystem: ParticleSystemComponent | undefined
```

Gets the [ParticleSystemComponent](https://api.playcanvas.com/engine/classes/ParticleSystemComponent.md) attached to this entity.

### render

```ts
readonly render: RenderComponent | undefined
```

Gets the [RenderComponent](https://api.playcanvas.com/engine/classes/RenderComponent.md) attached to this entity.

### rigidbody

```ts
readonly rigidbody: RigidBodyComponent | undefined
```

Gets the [RigidBodyComponent](https://api.playcanvas.com/engine/classes/RigidBodyComponent.md) attached to this entity.

### screen

```ts
readonly screen: ScreenComponent | undefined
```

Gets the [ScreenComponent](https://api.playcanvas.com/engine/classes/ScreenComponent.md) attached to this entity.

### script

```ts
readonly script: ScriptComponent | undefined
```

Gets the [ScriptComponent](https://api.playcanvas.com/engine/classes/ScriptComponent.md) attached to this entity.

### scrollbar

```ts
readonly scrollbar: ScrollbarComponent | undefined
```

Gets the [ScrollbarComponent](https://api.playcanvas.com/engine/classes/ScrollbarComponent.md) attached to this entity.

### scrollview

```ts
readonly scrollview: ScrollViewComponent | undefined
```

Gets the [ScrollViewComponent](https://api.playcanvas.com/engine/classes/ScrollViewComponent.md) attached to this entity.

### sound

```ts
readonly sound: SoundComponent | undefined
```

Gets the [SoundComponent](https://api.playcanvas.com/engine/classes/SoundComponent.md) attached to this entity.

### sprite

```ts
readonly sprite: SpriteComponent | undefined
```

Gets the [SpriteComponent](https://api.playcanvas.com/engine/classes/SpriteComponent.md) attached to this entity.

## Accessors

### guid

```ts
get guid(): string
```

Gets the GUID for this Entity.

## Methods

### _notifyHierarchyStateChanged

```ts
protected _notifyHierarchyStateChanged(node: GraphNode, enabled: boolean): void
```

**Parameters**

- `node` ([`GraphNode`](https://api.playcanvas.com/engine/classes/GraphNode.md)): The node to update.
- `enabled` (`boolean`): Enable or disable the node.

### _onHierarchyStateChanged

```ts
protected _onHierarchyStateChanged(enabled: boolean): void
```

**Parameters**

- `enabled` (`boolean`): Enable or disable the node.

### addComponent

```ts
addComponent<K extends string & {} | ComponentName>(type: K, data?: K extends ComponentName ? ComponentOptions<K> : any): (K extends ComponentName ? ComponentMap[K] : Component) | null
```

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.

For the built-in components the `type` also types the options and the result:
`entity.addComponent('camera', { fov: 45 })` accepts any settable property of
[CameraComponent](https://api.playcanvas.com/engine/classes/CameraComponent.md) and returns `CameraComponent | null`. See [ComponentOptions](https://api.playcanvas.com/engine/types/ComponentOptions.md) for
the rule and [ComponentMap](https://api.playcanvas.com/engine/types/ComponentMap.md) for extending this to application-defined components.

**Parameters**

- `type` ([`K`](https://api.playcanvas.com/engine/classes/Entity.md#addcomponentk)): The name of the component to add (a [ComponentName](https://api.playcanvas.com/engine/types/ComponentName.md)). Valid strings are:

  - "anim" - see [AnimComponent](https://api.playcanvas.com/engine/classes/AnimComponent.md)
  - "animation" - see [AnimationComponent](https://api.playcanvas.com/engine/classes/AnimationComponent.md)
  - "audiolistener" - see [AudioListenerComponent](https://api.playcanvas.com/engine/classes/AudioListenerComponent.md)
  - "button" - see [ButtonComponent](https://api.playcanvas.com/engine/classes/ButtonComponent.md)
  - "camera" - see [CameraComponent](https://api.playcanvas.com/engine/classes/CameraComponent.md)
  - "collision" - see [CollisionComponent](https://api.playcanvas.com/engine/classes/CollisionComponent.md)
  - "element" - see [ElementComponent](https://api.playcanvas.com/engine/classes/ElementComponent.md)
  - "gsplat" - see [GSplatComponent](https://api.playcanvas.com/engine/classes/GSplatComponent.md)
  - "layoutchild" - see [LayoutChildComponent](https://api.playcanvas.com/engine/classes/LayoutChildComponent.md)
  - "layoutgroup" - see [LayoutGroupComponent](https://api.playcanvas.com/engine/classes/LayoutGroupComponent.md)
  - "light" - see [LightComponent](https://api.playcanvas.com/engine/classes/LightComponent.md)
  - "model" - see [ModelComponent](https://api.playcanvas.com/engine/classes/ModelComponent.md)
  - "particlesystem" - see [ParticleSystemComponent](https://api.playcanvas.com/engine/classes/ParticleSystemComponent.md)
  - "render" - see [RenderComponent](https://api.playcanvas.com/engine/classes/RenderComponent.md)
  - "rigidbody" - see [RigidBodyComponent](https://api.playcanvas.com/engine/classes/RigidBodyComponent.md)
  - "screen" - see [ScreenComponent](https://api.playcanvas.com/engine/classes/ScreenComponent.md)
  - "script" - see [ScriptComponent](https://api.playcanvas.com/engine/classes/ScriptComponent.md)
  - "scrollbar" - see [ScrollbarComponent](https://api.playcanvas.com/engine/classes/ScrollbarComponent.md)
  - "scrollview" - see [ScrollViewComponent](https://api.playcanvas.com/engine/classes/ScrollViewComponent.md)
  - "sound" - see [SoundComponent](https://api.playcanvas.com/engine/classes/SoundComponent.md)
  - "sprite" - see [SpriteComponent](https://api.playcanvas.com/engine/classes/SpriteComponent.md)
- `data` ([`K`](https://api.playcanvas.com/engine/classes/Entity.md#addcomponentk) `extends` [`ComponentName`](https://api.playcanvas.com/engine/types/ComponentName.md) `?` [`ComponentOptions`](https://api.playcanvas.com/engine/types/ComponentOptions.md)`<`[`K`](https://api.playcanvas.com/engine/classes/Entity.md#addcomponentk)`> : any`, optional): The
  initialization data for the specific component type: the settable properties of the component
  class plus the extras its system understands (see [ComponentOptions](https://api.playcanvas.com/engine/types/ComponentOptions.md)). Any object is
  accepted for a component name that is not in [ComponentMap](https://api.playcanvas.com/engine/types/ComponentMap.md).

**Returns** `(`[`K`](https://api.playcanvas.com/engine/classes/Entity.md#addcomponentk) `extends` [`ComponentName`](https://api.playcanvas.com/engine/types/ComponentName.md) `?` [`ComponentMap`](https://api.playcanvas.com/engine/types/ComponentMap.md)`[`[`K`](https://api.playcanvas.com/engine/classes/Entity.md#addcomponentk)`] :` [`Component`](https://api.playcanvas.com/engine/classes/Component.md)`) | null`: The new
Component that was attached to the entity or null if there was an error.

**Example**

```ts
const entity = new 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 Color(1, 0, 0)
});
```

### clone

```ts
clone(): Entity
```

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** [`Entity`](https://api.playcanvas.com/engine/classes/Entity.md): A new Entity which is a deep copy of the original.

**Example**

```ts
const e = this.entity.clone();

// Add clone as a sibling to the original
this.entity.parent.addChild(e);
```

### destroy

```ts
destroy(): void
```

Destroy the entity and all of its descendants. First, all of the entity's components are
disabled and then removed. Then, the entity is removed from the hierarchy. This is then
repeated recursively for all descendants of the entity.

The last thing the entity does is fire the `destroy` event.

**Example**

```ts
const firstChild = this.entity.children[0];
firstChild.destroy(); // destroy child and all of its descendants
```

### findByGuid

```ts
findByGuid(guid: string): Entity | null
```

Find a descendant of this entity with the GUID.

**Parameters**

- `guid` (`string`): The GUID to search for.

**Returns** [`Entity`](https://api.playcanvas.com/engine/classes/Entity.md) `| null`: The entity with the matching GUID or null if no entity is found.

### findComponent

```ts
findComponent<K extends string & {} | ComponentName>(type: K): (K extends ComponentName ? ComponentMap[K] : Component) | null
```

Search the entity and all of its descendants for the first component of specified type.

**Parameters**

- `type` ([`K`](https://api.playcanvas.com/engine/classes/Entity.md#findcomponentk)): The name of the component type to retrieve.

**Returns** `(`[`K`](https://api.playcanvas.com/engine/classes/Entity.md#findcomponentk) `extends` [`ComponentName`](https://api.playcanvas.com/engine/types/ComponentName.md) `?` [`ComponentMap`](https://api.playcanvas.com/engine/types/ComponentMap.md)`[`[`K`](https://api.playcanvas.com/engine/classes/Entity.md#findcomponentk)`] :` [`Component`](https://api.playcanvas.com/engine/classes/Component.md)`) | null`: A component of
specified type, if the entity or any of its descendants has one. Returns null otherwise.

**Example**

```ts
// Get the first found light component in the hierarchy tree that starts with this entity
const light = entity.findComponent("light");
```

### findComponents

```ts
findComponents<K extends string & {} | ComponentName>(type: K): (K extends ComponentName ? ComponentMap[K] : Component)[]
```

Search the entity and all of its descendants for all components of specified type.

**Parameters**

- `type` ([`K`](https://api.playcanvas.com/engine/classes/Entity.md#findcomponentsk)): The name of the component type to retrieve.

**Returns** `(`[`K`](https://api.playcanvas.com/engine/classes/Entity.md#findcomponentsk) `extends` [`ComponentName`](https://api.playcanvas.com/engine/types/ComponentName.md) `?` [`ComponentMap`](https://api.playcanvas.com/engine/types/ComponentMap.md)`[`[`K`](https://api.playcanvas.com/engine/classes/Entity.md#findcomponentsk)`] :` [`Component`](https://api.playcanvas.com/engine/classes/Component.md)`)[]`: All components of
specified type in the entity or any of its descendants. Returns empty array if none found.

**Example**

```ts
// Get all light components in the hierarchy tree that starts with this entity
const lights = entity.findComponents("light");
```

### findScript

```ts
findScript<T extends Script>(type: Object): T | undefined
```

Search the entity and all of its descendants for the first script instance of the specified
class. The result is typed as an instance of that class, so no cast is needed.

**Parameters**

- `type` (`Object`): The script class to search for.

**Returns** [`T`](https://api.playcanvas.com/engine/classes/Entity.md#findscriptt) `| undefined`: A script instance of the specified class, if the entity or any of its
descendants has one. Returns undefined otherwise.

**Example**

```ts
// Get the first PlayerController instance in the hierarchy tree that starts with this entity
const controller = entity.findScript(PlayerController); // PlayerController | undefined
```

```ts
findScript(name: string): Script | undefined
```

Search the entity and all of its descendants for the first script instance with the
specified name.

**Parameters**

- `name` (`string`): The name of the script to search for.

**Returns** [`Script`](https://api.playcanvas.com/engine/classes/Script.md) `| undefined`: A script instance with the specified name, if the entity or any
of its descendants has one. Returns undefined otherwise.

**Example**

```ts
// Get the first found "playerController" instance in the hierarchy tree that starts with this entity
const controller = entity.findScript("playerController");
```

### findScripts

```ts
findScripts<T extends Script>(type: Object): T[]
```

Search the entity and all of its descendants for all script instances of the specified
class. The result is typed as an array of that class, so no cast is needed.

**Parameters**

- `type` (`Object`): The script class to search for.

**Returns** [`T`](https://api.playcanvas.com/engine/classes/Entity.md#findscriptst)`[]`: All script instances of the specified class in the entity or any of its
descendants. Returns an empty array if none are found.

**Example**

```ts
// Get all PlayerController instances in the hierarchy tree that starts with this entity
const controllers = entity.findScripts(PlayerController); // PlayerController[]
```

```ts
findScripts(name: string): Script[]
```

Search the entity and all of its descendants for all script instances with the specified
name.

**Parameters**

- `name` (`string`): The name of the script to search for.

**Returns** [`Script`](https://api.playcanvas.com/engine/classes/Script.md)`[]`: All script instances with the specified name in the entity or any of its
descendants. Returns an empty array if none are found.

**Example**

```ts
// Get all "playerController" instances in the hierarchy tree that starts with this entity
const controllers = entity.findScripts("playerController");
```

### removeComponent

```ts
removeComponent(type: string & {} | ComponentName): void
```

Remove a component from the Entity.

**Parameters**

- `type` (`string & {} |` [`ComponentName`](https://api.playcanvas.com/engine/types/ComponentName.md)): The name of the Component type.

**Example**

```ts
const entity = new Entity();
entity.addComponent("light"); // add new light component

entity.removeComponent("light"); // remove light component
```

## Events

### EVENT_DESTROY

```ts
static EVENT_DESTROY: string = 'destroy'
```

Fired after the entity is destroyed.

**Example**

```ts
entity.on('destroy', (e) => {
    console.log(`Entity ${e.name} has been destroyed`);
});
```

## Inherited from [GraphNode](https://api.playcanvas.com/engine/classes/GraphNode.md)

- `protected _children: GraphNode[] = []`
- `name: string`
- `tags: Tags`
- `get children(): readonly GraphNode[]`
- `get enabled(): boolean` · `set enabled(enabled: boolean)`
- `get forward(): Readonly<Vec3>`
- `get graphDepth(): number`
- `get parent(): GraphNode | null`
- `get path(): string`
- `get right(): Readonly<Vec3>`
- `get root(): GraphNode`
- `get up(): Readonly<Vec3>`
- `addChild(node: GraphNode): void`
- `find(attr: string | FindNodeCallback, value?: any): GraphNode[]`
- `findByName(name: string): GraphNode | null`
- `findByPath(path: string | string[]): GraphNode | null`
- `findByTag(...query: any[]): GraphNode[]`
- `findOne(attr: string | FindNodeCallback, value?: any): GraphNode | null`
- `fire(name: string, arg1?: any, arg2?: any, arg3?: any, arg4?: any, arg5?: any, arg6?: any, arg7?: any, arg8?: any): EventHandler`
- `forEach(callback: ForEachNodeCallback, thisArg?: any): void`
- `getEulerAngles(): Readonly<Vec3>`
- `getLocalEulerAngles(): Readonly<Vec3>`
- `getLocalPosition(): Readonly<Vec3>`
- `getLocalRotation(): Readonly<Quat>`
- `getLocalScale(): Readonly<Vec3>`
- `getLocalTransform(): Readonly<Mat4>`
- `getPosition(): Readonly<Vec3>`
- `getRotation(): Readonly<Quat>`
- `getWorldTransform(): Readonly<Mat4>`
- `hasEvent(name: string): boolean`
- `insertChild(node: GraphNode, index: number): void`
- `isAncestorOf(node: GraphNode): boolean`
- `isDescendantOf(node: GraphNode): boolean`
- `lookAt(x: number, y: number, z: number, ux?: number, uy?: number, uz?: number): void` · `lookAt(target: Vec3, up?: Vec3): void`
- `off(name?: string, callback?: HandleEventCallback, scope?: any): EventHandler`
- `on(name: string, callback: HandleEventCallback, scope?: any): EventHandle`
- `once(name: string, callback: HandleEventCallback, scope?: any): EventHandle`
- `remove(): void`
- `removeChild(child: GraphNode): void`
- `reparent(parent: GraphNode, index?: number): void`
- `rotate(x: number, y: number, z: number): void` · `rotate(rotation: Vec3): void`
- `rotateLocal(x: number, y: number, z: number): void` · `rotateLocal(rotation: Vec3): void`
- `setEulerAngles(x: number, y: number, z: number): void` · `setEulerAngles(angles: Vec3): void`
- `setLocalEulerAngles(x: number, y: number, z: number): void` · `setLocalEulerAngles(angles: Vec3): void`
- `setLocalPosition(x: number, y: number, z: number): void` · `setLocalPosition(position: Vec3): void`
- `setLocalRotation(x: number, y: number, z: number, w: number): void` · `setLocalRotation(rotation: Quat): void`
- `setLocalScale(x: number, y: number, z: number): void` · `setLocalScale(scale: Vec3): void`
- `setPosition(x: number, y: number, z: number): void` · `setPosition(position: Vec3): void`
- `setPositionAndRotation(position: Vec3, rotation: Quat): void`
- `setRotation(x: number, y: number, z: number, w: number): void` · `setRotation(rotation: Quat): void`
- `translate(x: number, y: number, z: number): void` · `translate(translation: Vec3): void`
- `translateLocal(x: number, y: number, z: number): void` · `translateLocal(translation: Vec3): void`