Home

Concepts

If you are not familiar with ECS, please take a read:

• Introduction
• Wikipedia

This framework follow the classic definition of ECS:

• Entity: is a unique integer identifier
• Component: data container
• System: execute logic matched with entities based on their components

Admin

Admin is an object contain exposed API of the framework and work as a creator of game world. It functionalities:

• createEntity Create entity using a group of components or a blueprint.
• deleteEntity Delete an entity using its id.
• recycle Put an entity back to entity pool.
• queryAll Access to all component instances with a particular filter.
• queryActive Access to all active component instances with a particular filter.
• addSingleton Define component as global singleton.
• getSingleton Access to a singleton instance.
• addComponent Add one or many component to an entity.
• removeComponent Remove one or many component to an entity.
• registerSystem Register a system.
• update Update game world created by an Admin.

Create an Admin

    let admin = new ecs.Admin();

All classes and types are accessible under ecs 'namespace'. For example: ecs.Admin, ecs.Component,...
Javascript or Typescript don't actually have namespace scope, so classes and types can be used directly without ecs namespace. Though it is better to do so to avoid naming colliding.

Using Admin to initiate a game world

You can store the admin object reference anywhere that suitable. A basic follow of create a game world is:

• Create and initiate all entities
• Register all systems
• Update the created game world

    function createGame(): ecs.Admin {
        let admin = new ecs.Admin();
        
        //create entities
        ...

        //register systems
        ...

        return admin;
    }

    //e.g. in another module, create a game world and use returned admin to update that world
    this.admin = createGame();

    public update(dt) {
        this.admin.update(dt);
    }

Component

Components are ecs.Component objects that should be used only to contain data and utilities function to access the data. There shouldn't be any behavior or calculation make by these objects.

    class ExampleComponent extends ecs.Component {
        //data records should have initial values
        dataRecord1: string = 'example';
        dataRecord2: number = 0'
    }

There are two inherit properties of a component that take effect on creation is activeOnCreation and activeByAll. Those two are used for communication between system.

System

Systems should contain only behavior and calculation on data of components. A system contain a reference to admin object.

    class ExampleSystem extends ecs.System {

        //called when you register a system
        onRegister() {
            
        }
        
        //this.admin is inherited from ecs.System
        onUpdate(dt) {
            //example query
            this.admin.queryAll([Velocity, Position], (vel, pos) => {
                pos.x += vel.x * dt;
            })
        }

        onLaterUpdate(dt) {
        }
    }

Register a system

    function createGame(): ecs.Admin {
        let admin = new ecs.Admin();
        
        //create entities
        ...

        //register systems
        admin.registerSystem(System1); //you can pass what kind of system you want to register, the admin will instantiate for you
        admin.regisSystem(new System2()); // or can pass an object directly. That mean a system can be update many times.

        return admin;
    }

Systems execution order will base on the order you register them.