El Entity Manager

El Entity Manager es el registro central de entidades y componentes. Crea y elimina entidades, asocia y quita componentes, busca entidades por sus componentes, gestiona relaciones padre-hijo y activa o desactiva entidades y componentes.

Dentro de una escena está disponible como this.entityManager. En los sistemas se obtiene mediante inyección de dependencias. Consulta Componentes y sistemas personalizados.

Una entidad es un identificador numérico; los componentes son los datos asociados a ella. Consulta Arquitectura.

Crear entidades

createEntity devuelve el identificador de la nueva entidad. Acepta una lista de componentes, que pueden ser instancias o clases de componentes. Las clases se instancian sin argumentos; las instancias se clonan.

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

// a partir de instancias de componentes
const entity = this.entityManager.createEntity([
    new Transform({ position: new Vector2(100, 100) }),
    new Player(),
]);

// a partir de clases de componentes
const other = this.entityManager.createEntity([Transform, SpriteRenderer]);

// una entidad vacía
const empty = this.entityManager.createEntity();

Una entidad puede crearse como hija de otra pasando un padre como segundo argumento:

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

Acceder a los componentes

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

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

Agregar y quitar componentes

addComponent asocia un componente (instancia o clase) a una entidad existente. removeComponent acepta o bien una entidad y un tipo de componente, o bien una instancia de componente.

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

this.entityManager.removeComponent(entity, SpriteRenderer);
// o, dada la instancia
this.entityManager.removeComponent(spriteRenderer);

Buscar entidades

search encuentra las entidades que tienen un tipo de componente dado. Tiene dos formas:

• Forma con callback (recomendada en los sistemas): invoca el callback para cada coincidencia sin reservar un array intermedio. Úsala en onUpdate y otros bucles por frame.
• Forma con array: devuelve un array de objetos SearchResult ({ entity, component }), útil cuando necesitas ordenar, recortar o filtrar los resultados.

// forma con callback
this.entityManager.search(Enemy, (enemy, entity) => {
    // hacer algo con cada enemigo
});

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

Ambas formas aceptan un argumento final includeDisabled (por defecto false) para incluir entidades y componentes desactivados.

Nota: No agregues ni quites entidades/componentes del mismo tipo de componente dentro de un callback de search.

Otros métodos de búsqueda:

Activar y desactivar

Las entidades y los componentes desactivados son omitidos por los sistemas (y quedan excluidos de las búsquedas a menos que se indique includeDisabled).

Relaciones padre-hijo

Las entidades pueden organizarse en jerarquías.

Eliminar entidades

this.entityManager.removeEntity(entity);