A fast, flexible Entity Component System for JavaScript games. Bring your own components/systems.
NOTE: This code has not yet been battle-tested; use at your own risk. (Also, please report issues.)
For complete examples, see ecsape-examples.
var ECS = require('ecsape');
NOTE: ECSape does not include/impose any classical OO utilities. For the sake of example we use node's built-in util.inherits
, but you can use whatever you like (including "vanilla" CoffeeScript classes) to facilitate inheritance.
- Create a new Entity dynamically
- Create a new Component dynamically
- Define a new Component type
- Add a Component to an Entity
- Remove a Component from an Entity
- Create a new World
- Add an entity to the World
- Add many entities to the World in bulk
- Remove an entity from the world
- Remove many entities from the World in bulk
- Flush all added/removed/changed entities into corresponding entity lists
- Get all entities that have certain Components
- Iterate through an Entity List with a callback
- Iterate through an Entity List with a loop (faster)
- Detect when an Entity is added to an Entity List
- Detect when an Entity is removed from an Entity List
- Create a new System dynamically
- Define a new System type
- Add a system to the World
- Remove a system from the world
- Invoke a function on all systems
var entity = new ECS.Entity();
NOTE: When inheriting from ECS.Entity
, you must call the super-constructor, as it assigns a unique
ID to the Entity which is used internally.
var position = new ECS.Component();
position.name = 'position';
position.x = position.y = 0;
var inherits = require('util').inherits;
var Position = function (pos) {
this.x = pos.x;
this.y = pos.y;
};
inherits(Position, ECS.Component);
Position.prototype.name = 'position';
entity.addComponent(new Position({x: 100, y: 100}));
entity.removeComponent(position);
var world = new ECS.World();
world.add(entity);
var entities = [
entity1,
entity2,
// ...
entityN
];
world.addAll(entities);
world.remove(entity);
var entities = [
entity1,
entity2,
// ...
entityN
];
world.removeAll(entities);
world.flush();
This updates all lists acquired with world.get
, based on which entities have
been added/removed, or have changed their component lists, since the last time flush
was called.
Usually, you'll want to call this once per "tick" of your game.
var movables = world.get('position', 'velocity');
NOTE: world.get
returns a special type of list of entities.
This list automatically updates when entities that match its criteria are added or removed, so it can be saved to refer to later, for instance, as a property inside a System.
See also:
world.get('position', 'velocity').each(function (entity) {
entity.position.x -= 100;
});
var next = world.get('position', 'velocity').first,
entity;
while (next) {
entity = next.obj;
entity.position.x -= 100;
next = next.next;
};
world.get('position', 'velocity').on('entitiesAdded', function (entities) {
console.log('Number of entities added: ' + entities.length);
});
world.get('position', 'velocity').on('entitiesRemoved', function (entities) {
console.log('Number of entities removed: ' + entities.length);
});
var physics = new ECS.System();
physics.init = function (world) {
this.world = world;
this.entities = world.get('position', 'velocity');
};
physics.update = function () {
this.entities.each(function (entity) {
entity.position.x += entity.velocity.x;
entity.position.y += entity.velocity.y;
});
};
NOTE: The init
function is important; it runs when a System is added to the world.
var inherits = require('util').inherits;
var PhysicsSystem = function () {
PhysicsSystem.super_.call(this);
};
inherits(PhysicsSystem, ECS.System);
PhysicsSystem.prototype.init = function (world) {
this.world = world;
this.entities = world.get('position', 'velocity');
};
PhysicsSystem.prototype.update = function (dt) {
this.entities.each(function (entity) {
entity.position.x += entity.velocity.x * dt;
entity.position.y += entity.velocity.y * dt;
});
};
var physics = new PhysicsSystem();
NOTE: When creating systems by inheriting from ECS.System
, you must call the super-constructor, as it assigns a unique
ID to the System which is used internally.
world.addSystem(physics);
NOTE: This will automatically invoke the init
function on the System being added (if one exists).
The first and only argument provided to init()
is a reference to this World
.
world.removeSystem(physics);
world.invoke('update', dt);
world.invoke('hasManyArguments', a, b, c, d);
Functions are invoked in the order the systems were added to the world.
If a system does not implement the specified function, it is skipped.
See also:
npm install ecsape --save
MIT