Get the basics

To start working with ecso you must make sure to have a Haxe version including ecso. To know how to proceed you can check the build instructions. Then add -L ecso to your compilation flags and you are ready to go!

Create entities

Any entity must be created as part of a group:

import ecso.Entity;

var entities = new EntityGroup();

entities.createEntity({
    name: "Sally",
    position: { x: 2.0, y: 4.5 },
    gfx: new Graphics();
});

In the above code, we create a new entity inside entities with the components:

• name of type String, initialized with the value "Sally",
• position of type { x : Float, y : Float },
• gfx of type Graphics, initialized with a new instance.

Groups are adding a small layer of modularity and additional groups can be declared.

ℹ️ Note that we use anonymous structures as a convenient way to define entities and to initialize their components. The run-time representation of entities might be very different depending on your build configuration (more details on that soon).

To avoid suprises, we can enfore the archetype of our entity. For clarity, let's first give some names to our components:

typedef Name = { name : String }
typedef Position = { position : { x:Float, y:Float} }
typedef Player = Name & { gfx : Graphics }

We can now enforce the archetype of our entity using type constraint:

entities.createEntity(({
    name: "Sally",
    gfx: new Graphics();
} : Player & Position)); // Some type constraints

The above code will complain at compilation time with Object requires field position. This guarantee our entity stays conform to Player and Position.

Process systems

TODO:

• basic processing
• with binding

Add and remove components

ecso provides an interristing way to add or remove components. The first logical step, is to know if our entity already has or not a given component. Like any other entity manipulation, we must operate inside a system:

entities.foreachEntity(function (entity:{ ?name:String }) {
    var hasName = entity.name != null;
});

The above system will match any entity which has or not a component name. In ecso, a component which is equal to null is a missing component. From that, it is pretty straightfoward, and integreates nicely with the language:

entities.foreachEntity(function (entity:{ ?name:String }) {
    if (entity.name == null) {
        entity.name = "value"; // adding the component "name" to the entity
    } else {
        entity.name = null; // removing the component from "name" the entity
    }
});

ecso integrates well with the Haxe null-safety feature, which helps to make component nullability more apparent in the code.

Delete entities

entities.foreachEntity(function (entity:Position & Name) {
    entities.deleteEntity(entity);
});