# Entity

Class · extends `Events` · category: Other

Source: https://github.com/playcanvas/editor-api/blob/4303c34bcee9a418297350899ad3a3f555526ec4/src/entity.ts#L34

The Entity class represents an entity in the Editor.

## Constructors

### constructor

```ts
new Entity(data?: any)
```

Creates new Entity

**Parameters**

- `data` (`any`, optional, default `{}`): Optional entity data

## Accessors

### children

```ts
get children(): Entity[]
```

The children entities. Warning: this creates a new array every time it's called.

### history

```ts
get history(): ObserverHistory
```

The history object for this entity.

### observer

```ts
get observer(): EntityObserver
```

The observer object for this entity.

### parent

```ts
get parent(): Entity
```

The parent entity.

### viewportEntity

```ts
get viewportEntity(): any
```

The entity in the 3D viewport of the Editor.

## Methods

### addChild

```ts
addChild(entity: Entity): boolean
```

Adds entity as a child

**Parameters**

- `entity` ([`Entity`](https://api.playcanvas.com/editor/classes/Entity.md)): The entity

**Returns** `boolean`: Whether the child was added

### addComponent

```ts
addComponent(component: string, data?: {}): void
```

Adds a component to this Entity

**Parameters**

- `component` (`string`): The component name
- `data` (`{}`, optional, default `{}`): Default component data. Defaults values will be used for any missing fields.
  For details on component properties see [Entity](https://api.playcanvas.com/editor/classes/Entity.md).

**Example**

```javascript
editor.entities.root.addComponent('model', {
    type: 'box'
});
```

### addScript

```ts
addScript(scriptName: string, options?: object): Promise<void>
```

Adds a script to the script component of this entity.
If a script component does not exist, this method will add the script
component as well.

**Parameters**

- `scriptName` (`string`): The name of the script.
- `options` (`object`, optional, default `{}`)
    - `options.attributes` (`object`, optional): The values of attributes. Each key is the name
      of the attributes and each value is the value for that attribute. Leave undefined to
      let the Editor set default values depending on the attribute types.
    - `options.history` (`boolean`, optional): Whether to add a history action. Defaults to true.
    - `options.index` (`number`, optional): The desired index in the entity's scripts order to add this script.

**Returns** `Promise<void>`: A promise

### delete

```ts
delete(options?: object): Promise<void>
```

Deletes entity (and its children)

**Parameters**

- `options` (`object`, optional, default `{}`)
    - `options.history` (`boolean`, optional): Whether to record a history action. Defaults to true.

**Returns** `Promise<void>`: A promise

**Example**

```javascript
editor.entities.root.findByName('door').delete();
```

### depthFirst

```ts
depthFirst(fn: (entity: Entity) => void): void
```

Executes function for this entity and its children in depth first order.

**Parameters**

- `fn` (`(entity: Entity) => void`): A function that takes an entity as an argument

**Example**

```javascript
// get a list of all entities in the graph in depth first order
const entities = [];
editor.entities.root.depthFirst(entity => entities.push(entity));
```

### duplicate

```ts
duplicate(options?: object): Promise<Entity>
```

Duplicates entity under the same parent

**Parameters**

- `options` (`object`, optional, default `{}`)
    - `options.history` (`boolean`, optional): Whether to record a history action. Defaults to true.
    - `options.rename` (`boolean`, optional): Whether to rename the duplicated entity. Defaults to false.
    - `options.select` (`boolean`, optional): Whether to select the new entity. Defaults to false.

**Returns** `Promise<`[`Entity`](https://api.playcanvas.com/editor/classes/Entity.md)`>`: The new entity

### filter

```ts
filter(fn: (entity: Entity) => boolean): Entity[]
```

Returns the entity and children that satisfy the function

**Parameters**

- `fn` (`(entity: Entity) => boolean`): A function that takes an Entity and returns whether it should be included
  in the result

**Returns** [`Entity`](https://api.playcanvas.com/editor/classes/Entity.md)`[]`: The result

**Example**

```javascript
const doors = editor.entities.root.filter(entity => entity.get('name').startsWith('door'));
```

### findByName

```ts
findByName(name: string): Entity
```

Finds first entity by name using depth-first search

**Parameters**

- `name` (`string`): The name

**Returns** [`Entity`](https://api.playcanvas.com/editor/classes/Entity.md): The entity

**Example**

```javascript
const door = editor.entities.root.findByName('Door');
```

### get

```ts
get(path: string): any
```

Gets value at path. See [Entity](https://api.playcanvas.com/editor/classes/Entity.md) for a list of properties.

**Parameters**

- `path` (`string`): The path

**Returns** `any`: The value

**Example**

```javascript
console.log(entity.get('position'));
```

### has

```ts
has(path: string): boolean
```

Checks if path exists. See [Entity](https://api.playcanvas.com/editor/classes/Entity.md) for a list of properties.

**Parameters**

- `path` (`string`): The path

**Returns** `boolean`: True if path exists

**Example**

```javascript
console.log(entity.has('components.model'));
```

### insert

```ts
insert(path: string, value: any, index?: number): boolean
```

Inserts value in array at path, at specified index. See [Entity](https://api.playcanvas.com/editor/classes/Entity.md) for a list of properties.

**Parameters**

- `path` (`string`): The path
- `value` (`any`): The value
- `index` (`number`, optional): The index (if undefined the value will be inserted in the end)

**Returns** `boolean`: Whether the value was inserted

**Example**

```javascript
entity.insert('tags', 'a_tag');
```

### insertChild

```ts
insertChild(entity: Entity, index?: number): boolean
```

Inserts entity as a child at specified index.

**Parameters**

- `entity` ([`Entity`](https://api.playcanvas.com/editor/classes/Entity.md)): The entity
- `index` (`number`, optional, default `undefined`): The index. If undefined the child will be added in the end.

**Returns** `boolean`: Whether the child was added

### isDescendantOf

```ts
isDescendantOf(parent: Entity): boolean
```

Returns true if this entity is a descendant of the specified parent entity.

**Parameters**

- `parent` ([`Entity`](https://api.playcanvas.com/editor/classes/Entity.md)): The parent

**Returns** `boolean`: True if it is

### json

```ts
json(): Record<string, any>
```

Returns JSON representation of entity data

**Returns** `Record<string, any>`: - The data
```javascript
console.log(entity.json());
```

### jsonHierarchy

```ts
jsonHierarchy(): any
```

Returns a JSON representation of entity data. The children array
of the entity gets recursively converted to an array of entity data
instead of containing children resource ids.

**Returns** `any`: - The data

**Example**

```javascript
const data = entity.jsonHierarchy();
console.log(data.children[0].name);
```

### latest

```ts
latest(): Entity
```

Returns the latest version of the Entity from the Entities API.

**Returns** [`Entity`](https://api.playcanvas.com/editor/classes/Entity.md): The entity

### listByTag

```ts
listByTag(...tags: any[]): Entity[]
```

Finds all entities with specified tags

**Parameters**

- `tags` (`any[]`): The tags. If multiple tags are specified then entities that contain ANY of the specified
  tags will be included. If an argument is an array of tags then entities that contain ALL of the tags in the array will be included.

**Returns** [`Entity`](https://api.playcanvas.com/editor/classes/Entity.md)`[]`: The entities

**Example**

```javascript
// entities that have the following tag
const entities = editor.entities.root.listByTag('tag');
// entities that have any of the following tags
const entities = editor.entities.root.listByTag('tag', 'tag2');
// entities that have all of the following tags
const entities = editor.entities.root.listByTag(['tag', 'tag2']);
```

### removeChild

```ts
removeChild(entity: Entity): void
```

Removes entity from children

**Parameters**

- `entity` ([`Entity`](https://api.playcanvas.com/editor/classes/Entity.md)): The entity

### removeComponent

```ts
removeComponent(component: string): void
```

Removes a component from this Entity

**Parameters**

- `component` (`string`): The component name

**Example**

```javascript
editor.entities.root.removeComponent('model');
```

### removeScript

```ts
removeScript(scriptName: string, options?: object): void
```

Removes a script from the entity's script component.

**Parameters**

- `scriptName` (`string`): The name of the script.
- `options` (`object`, optional, default `{}`)
    - `options.history` (`boolean`, optional): Whether to record a history action. Defaults to true.

### removeValue

```ts
removeValue(path: string, value: any): boolean
```

Remove value from array at path. See [Entity](https://api.playcanvas.com/editor/classes/Entity.md) for a list of properties.

**Parameters**

- `path` (`string`): The path
- `value` (`any`): The value

**Returns** `boolean`: Whether the value was removed

**Example**

```javascript
entity.removeValue('tags', 'a_tag');
```

### reparent

```ts
reparent(parent: Entity, index?: number, options?: object): void
```

Reparents entity under new parent

**Parameters**

- `parent` ([`Entity`](https://api.playcanvas.com/editor/classes/Entity.md)): The new parent
- `index` (`number`, optional, default `null`): The desired index. If undefined the entity will be added at the end of the parent's children.
- `options` (`object`, optional, default `{}`)
    - `options.history` (`boolean`, optional): Whether to record a history action. Defaults to true.
    - `options.preserveTransform` (`boolean`, optional): Whether to preserve the original transform after reparenting

**Example**

```javascript
const redHouse = editor.entities.root.findByName('red house');
const greenHouse = editor.entities.root.findByName('green house');
const door = redHouse.findByName('door');
door.reparent(greenHouse);
```

### set

```ts
set(path: string, value: any): boolean
```

Sets value at path. See [Entity](https://api.playcanvas.com/editor/classes/Entity.md) for a list of properties.

**Parameters**

- `path` (`string`): The path
- `value` (`any`): The value

**Returns** `boolean`: Whether the value was set

**Example**

```javascript
entity.set('position', [1, 0, 0]);
```

### unset

```ts
unset(path: string): boolean
```

Unsets value at path. See [Entity](https://api.playcanvas.com/editor/classes/Entity.md) for a list of properties.

**Parameters**

- `path` (`string`): The path

**Returns** `boolean`: Whether the value was unset

**Example**

```javascript
entity.unset('components.model');
```