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 = ;
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 = ;
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 = ;positionname = 'position';positionx = positiony = 0;
Define a new Component type
var inherits = inherits; var { thisx = posx; thisy = posy;}; ; Positionprototypename = 'position';
Add a Component to an Entity
entity;
Remove a Component from an Entity
entity;
Create a new World
var world = ;
Add an entity to the World
world;
Add many entities to the World in bulk
var entities = entity1 entity2 // ... entityN; world;
Remove an entity from the world
world;
Remove many entities from the World in bulk
var entities = entity1 entity2 // ... entityN; world;
Flush all added/removed/changed entities into corresponding entity lists
world;
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;
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;
Iterate through an Entity List with a loop (faster)
var next = worldfirst entity; while next entity = nextobj; entitypositionx -= 100; next = nextnext;;
Detect when an Entity is added to an Entity List
world;
Detect when an Entity is removed from an Entity List
world;
Create a new System dynamically
var physics = ; physics { thisworld = world; thisentities = world;}; physics { thisentities;};
NOTE: The init
function is important; it runs when a System is added to the world.
Define a new System type
var inherits = inherits; var { PhysicsSystemsuper_;}; ; PhysicsSystemprototype { thisworld = world; thisentities = world;}; PhysicsSystemprototype { thisentities;}; var physics = ;
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;
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;
Invoke a function on all systems
world;
world;
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 --save
License
MIT