# Entities

Class · extends `Events` · category: Other

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

The entities editor API

## Constructors

### constructor

```ts
new Entities()
```

Creates new API instance

## Accessors

### root

```ts
get root(): Entity
```

Gets the root Entity

## Methods

### add

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

Adds entity to list

**Parameters**

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

### addScript

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

Like [Entity.addScript](https://api.playcanvas.com/editor/classes/Entity.md#addscript) but works on multiple entities using
a single history action.

**Parameters**

- `entities` ([`Entity`](https://api.playcanvas.com/editor/classes/Entity.md)`[]`): The entities.
- `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

### clear

```ts
clear(): void
```

Removes all entities from the list

### copyToClipboard

```ts
copyToClipboard(entities: Entity[]): void
```

Copy specified entities to localStorage clipboard. Can be used
to paste these entities later on.

**Parameters**

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

### create

```ts
create(data?: CreateEntityArguments, options?: object): Entity
```

Creates new entity and adds it to the hierarchy

**Parameters**

- `data` ([`CreateEntityArguments`](https://api.playcanvas.com/editor/types/CreateEntityArguments.md), optional, default `null`): Initial data for the entity
- `options` (`object`, optional, default `{}`)
    - `options.history` (`boolean`, optional): Whether to record a history action. Defaults to true.
    - `options.index` (`number`, optional): The child index that this entity will have under its parent.
    - `options.select` (`boolean`, optional): Whether to select new Entity. Defaults to false.

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

**Example**

```javascript
const root = editor.entities.create({
    name: 'parent',
});

const child = editor.entities.create({
    name: 'child',
    parent: root,
});
```

### delete

```ts
delete(entities: Entity | Entity[], options?: object): Promise<void>
```

Delete specified entities

**Parameters**

- `entities` ([`Entity`](https://api.playcanvas.com/editor/classes/Entity.md) `|` [`Entity`](https://api.playcanvas.com/editor/classes/Entity.md)`[]`): The entities
- `options` (`object`, optional, default `{}`)
    - `options.history` (`boolean`, optional): Whether to record a history action. Defaults to true.

**Returns** `Promise<void>`

**Example**

```javascript
await editor.entities.delete([entity1, entity2]);
```

### duplicate

```ts
duplicate(entities: Entity[], options?: object): Promise<Entity[]>
```

Duplicates the specified entities under the same parent

**Parameters**

- `entities` ([`Entity`](https://api.playcanvas.com/editor/classes/Entity.md)`[]`): The entities
- `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 entities. Defaults to false.
    - `options.select` (`boolean`, optional): Whether to select the new entities. Defaults to false.

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

**Example**

```ts
const duplicated = await editor.entities.duplicate(entities);
```

### get

```ts
get(id: string): Entity
```

Gets entity by resource id

**Parameters**

- `id` (`string`): The entity's resource id

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

**Example**

```javascript
const entity = editor.entities.get(resourceId);
```

### list

```ts
list(): any[]
```

Returns array of all entities

**Returns** `any[]`: The entities

**Example**

```javascript
const entities = editor.entities.list();
console.log(entities.length);
```

### pasteFromClipboard

```ts
pasteFromClipboard(parent: Entity, options?: object): Promise<Entity[]>
```

Paste entities copied into clipboard
under the specified parent.

**Parameters**

- `parent` ([`Entity`](https://api.playcanvas.com/editor/classes/Entity.md)): The parent
- `options` (`object`, optional, default `{}`)
    - `options.history` (`boolean`, optional): Whether to record a history action. Defaults to true.

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

### remove

```ts
remove(entity: Entity, entityReferences?: object): void
```

Removes entity from the list

**Parameters**

- `entity` ([`Entity`](https://api.playcanvas.com/editor/classes/Entity.md)): The entity
- `entityReferences` (`object`, optional, default `null`): A map of entity references to nullify
  when this entity is removed

### removeScript

```ts
removeScript(entities: Entity[], scriptName: string, options?: object): void
```

Like [Entity.removeScript](https://api.playcanvas.com/editor/classes/Entity.md#removescript) but works on multiple entities using
a single history action.

**Parameters**

- `entities` ([`Entity`](https://api.playcanvas.com/editor/classes/Entity.md)`[]`): The entities.
- `scriptName` (`string`): The name of the script.
- `options` (`object`, optional, default `{}`)
    - `options.history` (`boolean`, optional): Whether to record a history action. Defaults to true.

### reparent

```ts
reparent(data: ReparentArguments[], options?: object): void
```

Reparents entities under new parent.

**Parameters**

- `data` ([`ReparentArguments`](https://api.playcanvas.com/editor/types/ReparentArguments.md)`[]`): The reparenting data
- `options` (`object`, optional, default `{}`)
    - `options.history` (`boolean`, optional): Whether to record history. Defaults to true
    - `options.preserveTransform` (`boolean`, optional): Whether to preserve the transform of the entities. Defaults to false.

**Example**

```javascript
const child = editor.entities.create();
const parent = editor.entities.create();
editor.entities.reparent([{
    entity: child,
    parent: parent
}])
```

### serverAdd

```ts
serverAdd(entityData: object): void
```

Called when an entity is added from the server

**Parameters**

- `entityData` (`object`): The entity data
    - `entityData.children` ([`Entity`](https://api.playcanvas.com/editor/classes/Entity.md)`[]`)
    - `entityData.parent` ([`Entity`](https://api.playcanvas.com/editor/classes/Entity.md))

### serverRemove

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

Called when an entity is removed from the server

**Parameters**

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

### waitToExist

```ts
waitToExist(entityIds: string[], timeoutMs: number, callback: (entities: Entity[]) => void): () => void
```

Waits for specified entity ids to be added to the scene.
Once they are the callback is called with the entities as its argument.

**Parameters**

- `entityIds` (`string[]`): The ids of the entities to wait for
- `timeoutMs` (`number`): Number of ms to wait before stopping to wait
- `callback` (`(entities: Entity[]) => void`): The callback to call when all entities have been added.
  The signature is (Entity[]) => void.

**Returns** `() => void`: Returns a cancel function which can be called to cancel calling the
callback when the entities are added.