ECS concepts & implementation inspired by exp-ecs.
Why?
As a big fan of the Macro approach and concepts in exp-ecs, I originally wrote cog as a piece of the ghost framework to provide that same kind of workflow. But as that project evolved and changed it's focus to 2D only, I found I wanted to be able to plug it's dead simple ECS implementation into any kind of project, with no extra dependencies required. So I ripped the ECS out of the ghost framework, and cog was born!
Getting Started
Cog requires Haxe 4 to run.
Install the library from haxelib:
haxelib install cog
Alternatively the dev version of the library can be installed from github:
haxelib git cog https://github.com/AustinEast/cog.git
Then include the library in your project's .hxml:
-lib cogFor OpenFL users, add this into your Project.xml:
<haxelib name="cog" />For Kha users (who don't use haxelib), clone cog to the Libraries folder in your project root, and then add the following to your khafile.js:
project.addLibrary('cog');Usage
Concepts
Component
A Component is an object that holds data that define an entity. Generally a component only holds variables, with little-to-no logic.
Cog Components are created by implementing the IComponent into any Class, like so:
class Position implements IComponent {
public var x:Float = 0;
public var y:Float = 0;
}Components
A Components object is a container that holds Component instances.
This class is meant to be integrated into your own project's base object class (ie Entity, GameObject, Sprite, etc).
System
A System tracks collections of Components (as Nodes) for the purpose of performing logic on them.
Engine
The Engine is the entry point for Cog - it's main purpose is keeping track of Components objects and updating each System.
Node
A Node object keeps reference to a Components object and its relevant Component instances.
Nodes
A Nodes object tracks all the Components objects in the Engine, creating a Node for every Components object that contains all of it's required Component instances. Nodes objects are used by System objects to perform logic on Components.
Integration
A build macro is available to add custom fields to the Components class, such as an Entity class:
in build.hxml:
--macro cog.Macros.add_data("entity", "some.package.Entity")in Main.hx:
var components = new cog.Components();
components.entity = new some.package.Entity();This will also add a reference to the custom field into every Node instance:
class TestSystem extends System {
@:nodes var nodes:Node<Position>;
override function step(dt:Float) {
super.step(dt);
for (node in nodes) {
// The `Entity` custom field can be accessed through the `Components` object
trace('${node.components.entity.name}');
// OR it can be accessed directly from the Node
trace('${node.entity.name}');
}
}
}Example
import cog.IComponent;
import cog.Components;
import cog.System;
import cog.Engine;
import cog.Node;
// Creating Component classes is as simple as implementing the `IComponent` interface.
// When the interface is implemented, the required Component fields are all added automatically.
@:structInit
class Position implements IComponent {
public var x:Float = 0;
public var y:Float = 0;
}
@:structInit
class Velocity implements IComponent {
public var x:Float = 0;
public var y:Float = 0;
}
// Plug the `Components` class into your own `Entity` class
class Entity {
public var components:Components;
public var name:String = '';
public function new() {
components = new Components();
// Assign the Entity field on the Components instance
// This is only available by using the integration build macro, detailed here: https://github.com/AustinEast/cog#integration
components.entity = this;
// Create the Position & Velocity Components, then add them to the Entity's Components instance
var position:Position = {};
var velocity:Velocity = {};
components.add(position);
components.add(velocity);
}
}
// Create a System to randomly move Entities
class MovementSystem extends System {
// Using the `@:nodes` metadata, create a collection of Nodes.
// The Nodes class automatically tracks any `Components` object that has the Position and Velocity components,
// and will create a `Node` object for each one
@:nodes var movers:Node<Position, Velocity>;
public function new() {
super();
// Two callback methods are automatically generated for each Node variable with the `@:nodes` metadata in this System
// This callback is invoked every time a new Node is added to the `movers` Node list.
movers_added = (node) -> {
// Set a random velocity to each Node as it gets added to the System
node.velocity.x = Math.random() * 200;
node.velocity.y = Math.random() * 200;
}
// This callback is invoked every time a Node is removed from the `movers` Node list.
movers_removed = (node) -> {}
}
// This method is called every time the Cog Engine is stepped forward by the Game Loop
override public function step(dt:Float) {
super.step(dt);
for (node in movers) {
// Increment each Node's Position by it's Velocity
// Each Node holds reference to the `Components` object, along with a reference to each Component defined by the Nodes list
node.position.x += node.velocity.x * dt;
node.position.y += node.velocity.y * dt;
}
}
}
// Create a System to "Render" the entities
class RenderSystem extends System {
@:nodes var nodes:Node<Position>;
override function step(dt:Float) {
super.step(dt);
// Log the Entities' Positions
for (node in nodes) {
trace('${node.entity.name} is at position (${node.position.x}, ${node.position.y})');
}
trace('---------- End Frame ------------');
}
}
class Main {
static function main() {
// Create an Array to hold the Game's Entities
var entities = [];
// Create the Cog Engine
var engine = new Engine();
// Define a method to remove Entities from the Game
inline function remove_entity(entity:Entity) {
// Remove the Entity from the Game's Entity List
entities.remove(entity);
// Remove the Entity's `Components` from the Cog Engine
engine.remove_components(entity.components);
}
// Define a method to add Entities to the Game
inline function add_entity(entity:Entity) {
// Remove the Entity from the Game first, to make sure we arent adding it twice
remove_entity(entity);
// Add the Entity to the Game's Entity List
entities.push(entity);
// Add the Entity's `Components` to the Cog Engine
engine.add_components(entity.components);
}
// Add some Entities in random spots
for (i in 0...10) {
var entity = new Entity();
entity.name = 'Entity ${i + 1}';
var position = entity.components.get(Position);
if (position != null) {
position.x = Math.random() * 1000;
position.y = Math.random() * 1000;
}
add_entity(entity);
}
// Add the Movement and Render Systems to the Cog Engine
engine.add_system(new MovementSystem());
engine.add_system(new RenderSystem());
// Simulate a Game Loop
new haxe.Timer(16).run = () -> {
// Update the Cog Engine.
engine.step(16 / 1000);
}
}
}Roadmap
- Source Documentation
- Improve Disposal