Manipulate Entities - vux0303/typescript-ECS-framework GitHub Wiki

Create entities

Entity in ECS is number that hold reference to a set of components. Therefore, an entity is defined by its combination of components, this set of component class type then called 'signature' of the entity. There are two ways (overloading) to create an entity.

Using array of component or object of components

Parameter:

  • components Array | Object
  • initCB FilterResultHandler<T>
  • opt CreateOption

Return: Number

    //Transform and Velocity are extended from ecs.Component
    this.admin.createEntity([Transform, Velocity],      //component classes are used to create this entity, defined its signature
        ([transform, velocity]) => {                    //a callback with created instances argument to let you initiate them
            transform.name = 'example';
            velocity.name = 'example';
        };

If an entity contain too many component, using an object to store return instances may be more convenient:

    let entityComponents = {
         transform: Transform,
         velocity: Velocity
    }
 
    this.admin.createEntity(entityComponents,
         (instances) => {
             instances.transform.name = 'example';
             instances.velocity.name = 'example';
         };

Using BluePrint

Parameter:

  • blueprint BluePrint
  • override BluePrintOverrideOption<T, CreateOption>

Return: Number

    //create a BluePrint that store an entity creation config
    let bp = new ecs.BluePrint([Transform, Velocity],
        ([transform, velocity]) => {
            transform.name = 'example';
            velocity.name = 'example';
        };

    //use the blueprint to instantiate the entity
    this.admin.createEntity(dp);

    //you can override initial value from the blueprint
    this.admin.createEntity(dp, {
        overrideComponent: (transform, velocity) => {
            velocity.name = 'overrided example';
        }
    );

Create Options

As shown in parameter list, createEntity() accept an object of CreateOption as argument when creating an entity. There are two options available for now:

  • pool: All entity are pooled. If no pool size option provided, default size will be 1. Pool will resize if exceeded by adding an initial pool size (+n).
  • Signals
    //Transform and Velocity are extended from ecs.Component
    this.admin.createEntity([Transform, Velocity],
        ([transform, velocity]) => {
            transform.name = 'example';
            velocity.name = 'example';
        }, {
            pool: 16; //this will allocate 16 entity in memory but only initiate one of them with the callback in second argument
        };

Delete entities

Each entity is associated with a number as an ID. You can use this ID to destroy an object. ID of entities can only be obtained through query and only if the entity signature fully match the query's filter.

    this.admin.queryAll([Transform, Velocity],
        ([transform, velocity], entityID) => {
            if (entityID) { //entityID may be null if signature don't match
                this.admin.deleteEntity(entityID);
            }
        };

Recycle entities

All entity in the framework are pooled. So instead of release an entity from memory, you can put them back to the pool and reuse them later.

Parameter:

  • entity number
  • signature Filter
  • reset FilterResultHandler<T>
  • blueprint? Blueprint<T, any>

Return: void

    this.admin.queryAll([Transform, Velocity],
        ([transform, velocity], entityID) => {
            if (entityID) {
                this.admin.recycle(entityID, [Transform, Velocity], (t, v) => {
                    t.name = 'default'; //you can use call back reset component data
                    v.name = 'default';
                });
            }
        };

    //or you can you the blueprint of the entity to reset its data
    //you could provide callback in this case instead of passing null. In that case, the entity reset using blueprint first, then calling the callback
    this.admin.recycle(entityID, null, null, blueprint);

Add component

addComponents allow adding components or signals

Parameter:

  • entity number
  • components Filter
  • signals Filter
  • initNewComponentCB Function

Return: void

    this.admin.queryAll([Transform, Velocity],
        ([transform, velocity], entityID) => {
            if (entityID) {
                this.admin.addComponents(entityID, [Component1, Component2], [Signal1, Signal2], ([c1, c2], [s1, s2]) => {
                     //initiate value for c1, c2, s1, s2
                });
            }
        };

Remove component

removeComponents allow removing components or signals

Parameter:

  • entity number
  • components Filter
  • signals Filter

Return: void

    this.admin.queryAll([Transform, Velocity],
        ([transform, velocity], entityID) => {
            if (entityID) {
                this.admin.removeComponents(entityID, [Component1, Component2], [Signal1, Signal2]});
            }
        };
⚠️ **GitHub.com Fallback** ⚠️