ecsape v0.3.0
ECSape 
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.)
Examples
For complete examples, see ecsape-examples.
API
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.
Index
- 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
Create a new Entity dynamically
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.
Create a new Component dynamically
var position = new ECS.Component();
position.name = 'position';
position.x = position.y = 0;Define a new Component type
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';Add a Component to an Entity
entity.addComponent(new Position({x: 100, y: 100}));Remove a Component from an Entity
entity.removeComponent(position);Create a new World
var world = new ECS.World();Add an entity to the World
world.add(entity);Add many entities to the World in bulk
var entities = [
entity1,
entity2,
// ...
entityN
];
world.addAll(entities);Remove an entity from the world
world.remove(entity);Remove many entities from the World in bulk
var entities = [
entity1,
entity2,
// ...
entityN
];
world.removeAll(entities);Flush all added/removed/changed entities into corresponding entity lists
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.
Get all entities that have certain Components
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:
Iterate through an Entity List with a callback
world.get('position', 'velocity').each(function (entity) {
entity.position.x -= 100;
});Iterate through an Entity List with a loop (faster)
var next = world.get('position', 'velocity').first,
entity;
while (next) {
entity = next.obj;
entity.position.x -= 100;
next = next.next;
};Detect when an Entity is added to an Entity List
world.get('position', 'velocity').on('entitiesAdded', function (entities) {
console.log('Number of entities added: ' + entities.length);
});Detect when an Entity is removed from an Entity List
world.get('position', 'velocity').on('entitiesRemoved', function (entities) {
console.log('Number of entities removed: ' + entities.length);
});Create a new System dynamically
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.
Define a new System type
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.
Add a system to the World
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.
Remove a system from the world
world.removeSystem(physics);Invoke a function on all systems
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:
Install
npm install ecsape --saveLicense
MIT