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:

• entitiesAdded Event
• entitiesRemoved Event

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:

• world.flush()

Install

npm install ecsape --save

License

MIT