let loginButtonEntity = new Entity();
    this.engine.entities.add(loginButtonEntity);
    loginButtonEntity.components.add(
      new RectangleComponent(50, 100, 400, 100, 0xffe800),
      new ClickableComponent()
    );

Does not get an onAddedComponents event triggered however...

   loginButtonEntity.components.add(
      new RectangleComponent(50, 100, 400, 100, 0xffe800),
    );
    loginButtonEntity.components.add(new ClickableComponent());

    this.engine.addListener({
      onAddedEntities: e => {
        const id = e.id as number;

        e.addListener({
          onAddedComponents: c => {``` the `onAddedComponents` appears to be a singular component but not named as such.  Could this be the problem?  Same for `onAddedEntities` only having a single entity.

async processEntity(entity: MyEntity): void {
    const position = entity.components.get(Position);
    //... do your logic here
}

Would return a Promise<void>, or just don't include the return as its inferred.

When you implement a Component with extra properties, typescript gets mad because those new properties don't match to the strict Component interface contract. Thus the error Type 'MyComponent' has no properties in common with type 'Component'.

A solution might be to add an index property such as shown below, although I'm not sure it's the best solution.

Have you tried/considered using something like https://threads.js.org for the asynchronous case? Curious if the messaging passing between system would be too high to be valuable.

I think there is something funny with the Component interface type and my specific TypeScript version.

I defined a component of HasLifeforce and a LifeforceSystem system.

In my system, when I try to get components by their types, I get the following error:

// system
      const lifeforce = entity.components.get<HasLifeforce>(HasLifeforce);
    // the (HasLifeforce) in parenthesis is marked

Argument of type 'typeof HasLifeforce' is not assignable to parameter of type 'string | ComponentClass<HasLifeforce>'.
  Type 'typeof HasLifeforce' is not assignable to type 'ComponentClass<HasLifeforce>'.
    Types of parameters 'lifeforce' and 'args' are incompatible.
      Type 'unknown' is not assignable to type 'number | undefined'.
        Type 'unknown' is not assignable to type 'number'.

I'm using:

    "typescript": "^4.5.3"

I define my component similar to your example with and get the error:

import { Component } from "@trixt0r/ecs";

export class HasLifeforce implements Component {
  constructor(public lifeforce: number = 0) {}
}

Yet if I write it as the following, the error in the system does not pop up and the typing is fine.

import { Component } from "@trixt0r/ecs";

export class HasLifeforce implements Component {
  lifeforce = 0;
}

Any ideas? I'll try to make a reproducible example.
The transpiled code works either way.

Love this library <3

Problem

I've tried to add a Component to an Entity during the processEntity method of a System like entity.components.add(new components.CameraFollow());, but it seems like that component never gets added. In other Systems, this entity will not have that component attached, even after this process tick.

Expected Behavior

I expect that I can add a new component directly to the entity using entity.components.add(newComponent) during the processEntity step, and have that component persist in the entity

Workaround

As a work around, I've had to clone the entity, remove the old entity, add the new component, and add the new entity into the engine. This seems to trigger whatever events are required to keep the entity persistent in the system.

Since you have to extend anyways (<3 that) it would be cleaner to be able to write

export default class Entity extends AbstractEntity {
  constructor(id?: number) {
   ...
  }

Hi. I want to make some kind of 'spatial' separation of my entities and wondering if my approach is sane.

Background: my game is set in space with multiple star systems, where in each star you have planet and ship entities. I have a system for telling ships where to fly next and I want their destinations to only be planets of the same star system.

I created a class called MappedEntitiesAspectListener implementing AspectListener that listens to additions and removals of entities from the engine. The class is given a custom mapper function for mapping entities to different keys based on whatever. Additionally, you can get the entities collected by this class given the mapped key.

This is an example demonstrating the functionality, please let me know if it's sane. If it is, and you wish, I will create a PR with a cleaner example for your examples folder.

import { nanoid } from "nanoid";
import {
  Component,
  Engine,
  AbstractEntity,
  EntityCollection,
  AspectListener,
  EntityListener,
} from "@trixt0r/ecs";

class InStar implements Component {
  constructor(public starId: number) {}
}

class MyEntity extends AbstractEntity {
  constructor() {
    super(nanoid(6));
  }
}

class PlanetEntity extends MyEntity {
  constructor(starId: number) {
    super();
    this.components.add(new InStar(starId));
  }
}

const engine = new Engine();

class MappedEntitiesAspectListener<Key> implements AspectListener {
  constructor(protected mapperFn: (entity: AbstractEntity) => Key) {}

  private mapping = new Map<Key, EntityCollection>();

  getByKey(key: Key): EntityCollection | undefined {
    return this.mapping.get(key);
  }

  onAddedEntities(
    ...entities: AbstractEntity<Component, EntityListener<Component>>[]
  ): void {
    entities.forEach((entity) => {
      const key = this.mapperFn(entity);
      if (this.mapping.has(key)) {
        this.mapping.get(key)!.add(entity);
      } else {
        this.mapping.set(key, new EntityCollection([entity]));
      }
    });
  }

  onRemovedEntities(
    ...entities: AbstractEntity<Component, EntityListener<Component>>[]
  ): void {
    entities.forEach((entity) => {
      const key = this.mapperFn(entity);
      this.mapping.get(key)?.remove(entity);
    });
  }
}

const entitiesByStarId = new MappedEntitiesAspectListener((entity) => {
  const inStar = entity.components.get(InStar);
  return inStar ? inStar.starId : undefined;
});

engine.addListener(entitiesByStarId);
const somePlanet = new PlanetEntity(1);

engine.entities.add(somePlanet);
engine.entities.add(new PlanetEntity(1));
engine.entities.add(new PlanetEntity(1));
engine.entities.add(new PlanetEntity(2));
engine.entities.add(new PlanetEntity(2));
engine.entities.add(new PlanetEntity(3));
engine.entities.add(new PlanetEntity(4));
engine.entities.add(new PlanetEntity(4));
engine.entities.add(new PlanetEntity(4));
engine.entities.add(new PlanetEntity(4));

function showPlanetsForStarId(starId: number) {
  const planets = entitiesByStarId.getByKey(starId);
  console.log(
    `Star ${starId} has ${planets?.length} planets`,
    planets?.map((entity) => {
      return entity.id;
    })
  );
}

showPlanetsForStarId(1);
showPlanetsForStarId(2);
showPlanetsForStarId(3);
showPlanetsForStarId(4);
console.log("removing some planet");
engine.entities.remove(somePlanet);
showPlanetsForStarId(1);

Example output:

As previously talked about now that all Systems have an aspect could you have lifecycle events on the Aspect? Stuff like added/removed component/entity.

I have a situation where I have init and cleanup at the system level when a component is added to an entity. Can do in process but it gets run every frame. Would be ideal to have as a dispatched event at the engine &&|| system level.

Starting a bigger project and constantly casting the id: to string|number. The id is suppose to be more like a primary key and used for fast lookups. Especially in es6 maps the lookup speed of integers versus string when used constantly is dramatic. If strings are needed they are better placed in Tag/Debug components.

Hello. How do you feel about getting entities by ids?
I have something like this when I want to find a planet in my game with a specific id.

this.engine.entities.find((x) => x.id === planetId) ?? null;

I looked at your code for Collection and it's rather type-agnostic and keeps the elements in an array. If it "knew" it holds elements with an id, like entities, it could store them in a map/dict and we could fetch those instantly instead of .finding through the entire collection.

Thinking about this, I thought maybe listening to an "onAdded" event somewhere and track id->entity somehow in my own code, but it would be nice to have this in the library-level.

Is that possible? Does it accidentally break the data-driven nature of ECS possible optimizations?
I'd be happy to hear your input. Thanks for the cool library.

Its wonderful that you have component filtering. Usually in ECS parlance this is called an Aspect. Unfortunately filter is super overloaded in games for effects especially.