The Entity Manager

The entity manager is the central registry for entities and components. It creates and removes entities, attaches and removes components, searches for entities by their components, manages parent-child relationships, and enables or disables entities and components.

Inside a scene it is available as this.entityManager. In systems it is obtained through dependency injection. See Custom Components and Systems.

An entity is a numeric identifier; components are the data attached to it. See Architecture.

Creating entities

createEntity returns the new entity’s identifier. It accepts a list of components, which can be component instances or component classes. Classes are instantiated with no arguments; instances are cloned.

import { Transform, SpriteRenderer } from "angry-pixel";
import { Player } from "../component/Player";

// from component instances
const entity = this.entityManager.createEntity([
    new Transform({ position: new Vector2(100, 100) }),
    new Player(),
]);

// from component classes
const other = this.entityManager.createEntity([Transform, SpriteRenderer]);

// an empty entity
const empty = this.entityManager.createEntity();

An entity can be created as a child of another by passing a parent as the second argument:

const child = this.entityManager.createEntity([new Transform()], parent);

Accessing components

const transform = this.entityManager.getComponent(entity, Transform);

this.entityManager.updateComponentData(entity, Transform, (transform) => {
    transform.position = new Vector2(200, 200);
});

Adding and removing components

addComponent attaches a component (instance or class) to an existing entity. removeComponent accepts either an entity and a component type, or a component instance.

this.entityManager.addComponent(entity, new SpriteRenderer());

this.entityManager.removeComponent(entity, SpriteRenderer);
// or, given the instance
this.entityManager.removeComponent(spriteRenderer);

Searching for entities

search finds entities that have a given component type. It has two forms:

• Callback form (recommended in systems): invokes the callback for each match without allocating an intermediate array. Use it in onUpdate and other per-frame loops.
• Array form: returns an array of SearchResult objects ({ entity, component }), useful when you need to sort, slice, or filter the results.

// callback form
this.entityManager.search(Enemy, (enemy, entity) => {
    // do something with each enemy
});

// array form
const enemies = this.entityManager.search(Enemy);
const alive = enemies.filter(({ component }) => component.status === "alive");

Both forms accept a final includeDisabled argument (default false) to include disabled entities and components.

Note: Do not add or remove entities/components of the same component type from within a search callback.

Other search methods:

Enabling and disabling

Disabled entities and components are skipped by systems (and excluded from searches unless includeDisabled is set).

Parent-child relationships

Entities can be organized into hierarchies.

Removing entities

this.entityManager.removeEntity(entity);