Manipulate Entities - vux0303/typescript-ECS-framework 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. 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
([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);