---
title: Entities
slug: /entities
section: Entity Component System
---

An [[Entity]] in is an empty container for [[Component|Components]] which store data, alone an Entity has little behavior.

They are useful for defining bare bones game objects with custom behavior.

If you want a batteries included prebuilt Entity use an [[Actor]], read more [here](/docs/actor). Remember an Excalibur [[Actor]] is just an Entity with a list of prebuilt components and some useful apis built over them.

## Entity

Entities have no behavior by default, only a few lifecycle hooks `onInitialize`, and a concept of parent/children.

Building and adding an entity to a game is pretty straightforward.

```typescript
const game = new ex.Engine({...});

const entity = new ex.Entity();
const entityWithName = new ex.Entity({name: 'Named Entity'});
game.currentScene.add(entity);
```

## Child Entities

Entities can be added as children of other entities, once added child entities move relative to their parents.

- `Entity.parent` - Returns the parent of this entity, if one exists otherwise returns `null`
- `Entity.children` - Returns the list of child entities, otherwise returns an empty list
- `Entity.unparent()` - Removes this entity from its parent this entity

- `Entity.addChild(entity)` - Add a child to this entity
- `Entity.removeChild(entity)` - Remove a child
- `Entity.removeAllChildren()` - Removal all children

## Lifecycle

- `onInitialize` happens before first update
- `onPreUpdate` happens at the beginning of update
- `onPostUpdate` happens at the end of the update

## Components

Components can be added and removed from an entity. Only 1 instance of a component type can be part of an entity at at time.

When removing components removal is deferred until the end of the update, unless forced. Deferred removal is useful to prevent bugs where an entity is only partially processed by all applicable systems.

```typescript
const entity = new ex.Entity()
entity.addComponent(new ex.TransformComponent())

// Remove by type or instances
entity.removeComponent(ex.TransformComponent)

// Force removal
entity.removeComponent(ex.TransformComponent, true)
```

Components can be retrieved by type name, however if the component doesn't exist undefined will be returned.

```typescript
const entity = new ex.Entity()
const maybeTransform = entity.get(ex.TransformComponent)
if (maybeTransform) {
  console.log(maybeTransform.pos)
}
```

Entities can be checked for components as well

```typescript
const entity = new ex.Entity()
if (entity.has(ex.TransformComponent)) {
  console.log('Entity has a transform component')
}
```

All the components can be retrieved at once

```typescript
const components: Component[] = entity.getComponents()
```

## Tags

Tags are special components that are only types. Useful when the presence of a component is all that is needed.

- `Entity.addTag("someTag")` - Add a tag to an entity
- `Entity.removeTag("someTag")` - Remove a tag on an entity
- `Entity.hasTag("someTag")` - Check if a tag exists

## Templates aka Prefab

- Entity.addTemplate(TemplateEntity)

## EntityManager

- EntityManager.getById(entityId)
- EntityManager.getByName(entityName)
