README
ECS
Simple ecs implementation, inspired by Unity3d ECS.
Getting Started
Installation
npm
npm install @vladnet/ecs
yarn
yarn add @vladnet/ecs
import { EntityManager, SystemManager } from "@vladnet/ecs";
Entities
Entities are managed by EntityManager
.
There are only two methods to work with entities, set
and unset
.
Set
Set without id creates new entity, set with id updates existed one.
console.log(em.length); // 0
// create new entity
let myEntity = em.set({
name: "Petryk",
});
console.log(myEntity); // { id: "entity_1", name: "Petryk", }
console.log(em.length); // 1
// update existed one
myEntity = em.set({
id: newEntity.id,
name: "Vasylko",
});
console.log(myEntity); //{ id: "entity_1", name: "Vasylko", }
console.log(em.length); // 1
Unset
Just pass an entity id.
em.unset(myEntity.id);
Immutable
EntityManager never mutates your data.
// create new entity
const newEntity = em.set({
name: "Petryk",
});
console.log(newEntity); // { id: "entity_1", name: "Petryk", }
// update existed one
const updatedEntity = em.set({
id: newEntity.id,
name: "Vasylko",
});
console.log(updatedEntity); //{ id: "entity_1", name: "Vasylko", }
console.log(newEntity === updatedEntity); // false
forEach/filter/find/toArray etc
EntityManager has few methods working in the same way as such methofs in Array
:
forEach
, filter
, find
, some
, every
.
Sure thing, you can get plain array by em.toArray()
.
Observe
You could subscribe to set
or unset
events.
// on set
em.on(EEntityManagerEventTypes.set, (entity: IEntity) => {
// entity was set (new or updated)
}, context /* `this` for listener */);
// on unset
em.on(EEntityManagerEventTypes.unset, (entity: IEntity) => {
// entity was unset, do forget it and move forward
}, context /* `this` for listener */);
Systems
To manage you entities you should write a system.
System is just an object having update
method and optional start
method.
interface ISystem {
update: (em: EntityManager<IEntity>) => any;
start?: (em: EntityManager<IEntity>) => any;
}
const em = new EntityManager();
const sm = new SystemManager(em);
// add a system
const id = sm.add({
update(em) {
em
.filter(entity => entity.name === "Vasylko")
.forEach(entity => {
console.log(`Another one ${entity.name}!`);
});
}
});
// remove a system
sm.remove(id);
update
will be run each time entity manager changes (both set
or unset
actions). It will not run again for system own changes. SystemManager saves timestamp when its EntityManager and systems were updated.
start
will be run only once at SystemManager start.
Asynchronous
Systems are asynchronous, means you could update EntityManager at anytime and all other systems will update.
Start/Stop
// start all systems
sm.start();
// stop all systems
sm.stop();