Classes

AComponent

AComponent represent data or behaviors on an Entity. As an example, it can represent a position (x,y), a hitbox or a texture.

The A in AComponent is for Abstract, it means you can not construct but you must inherit it. A non-inherited AComponent represent nothing.

So on, you must inherit it, specify your datas and/or behaviours. You can set your behaviours in the update() function or in public functions. You can access the parent entity, and others components.

If your component require others components, you must check their existence in the constructor and throw if they are missing. Remember, if you want to follow this project design, you must fail-fast. It means you check every error-case and throw as soon as possible. Better see sooner than unreproducible undefined behaviors in production.

The update() function is automatically called when your entity tree got its function update() called.

ASystem

ASystem mean Abstract System. You can create systems by inheriting this class.

A system is a 'module' on which ASystem.earlyUpdate() and ASystem.lateUpdate() will run on each Entity.update() call from the world entity. It perform predictable actions on a set of entities.

On inheriting ASystem, you must set a constructor which call super(). First argument is the parent which will be given to your constructor. The second argument must be specified from your constructor: it must be an array with all the components the system can work on.

You must implement earlyUpdate(entities) and/or lateUpdate(entities). First argument is an array of entities, which comply to your components requirements. All entities that have all the required components will be in the given array.

See examples to understand how systems work.

To create systems, you must add SystemComponent to your world entity.

Entity

An entity represent 'a thing' into your world.

By default, an entity is empty: no behaviours, no meaning, no purpose.

You can attach components. As an example, you can create an entity named wall which have the following components: Position, Hitbox, Sprite.
You can create child entities.

On updating an entity, this procedure apply:

Emit nextEarlyUpdate
Call earlyUpdate() on child entities (which call earlyUpdate() on child entities then components)
Call earlyUpdate() on entity's components
Emit nextLateUpdate
Call lateUpdate() on child entities (which call lateUpdate() on child entities then components)
Call lateUpdate() on entity's components

On adding components to an entity, the order they are added matter: first added, first to be updated. Last added, last to be updated.

nextEarlyUpdate and nextLateUpdate may be useful if you do something now and you want to do something at now+1.

It may be useful if you have a drawing system:

On your world, a component is drawing sprites on screen
Childs of your world are sprites.
First, sprites get earlyUpdate() called
Then, drawing system get earlyUpdate() called
Finally, sprites get lateUpdate() called

SystemComponent

SystemComponent is a component which allow you to add systems to an entity. We recommend to add it only to world entities to keep simple and predictable behaviours.

System are always executed in the order they are added: first added, first updated.

To create your own system, take a look a the file asystem.js.

AComponent

AComponent represent data or behaviors on an Entity. As an example, it can represent a position (x,y), a hitbox or a texture.

The A in AComponent is for Abstract, it means you can not construct but you must inherit it. A non-inherited AComponent represent nothing.

So on, you must inherit it, specify your datas and/or behaviours. You can set your behaviours in the update() function or in public functions. You can access the parent entity, and others components.

If your component require others components, you must check their existence in the constructor and throw if they are missing. Remember, if you want to follow this project design, you must fail-fast. It means you check every error-case and throw as soon as possible. Better see sooner than unreproducible undefined behaviors in production.

The update() function is automatically called when your entity tree got its function update() called.

Kind: global class

AComponent
- new AComponent(parent)
- instance
  - .parent ⇒ Entity
  - .identity ⇒ String
  - .emit(name, [payload])
  - .earlyUpdate()
  - .lateUpdate()
  - .destructor()
- static
  - .identity ⇒ String

new AComponent(parent)

On inheriting AComponent, parent will be passed to your constructor among your own arguments. You must keep parentEntity first, then your arguments.

Param	Type	Description
parent	`Entity`	The entity which own this component

aComponent.parent ⇒ `Entity`

Kind: instance property of AComponent
Returns: Entity - Owner of this component.

aComponent.identity ⇒ `String`

On inheriting AComponent, you must override this function to return the component name from your class static function name.

See static function AComponent.identity.

Kind: instance property of AComponent

aComponent.emit(name, [payload])

Emit an event from parent identified as this component.

This function works as a regular EventEmitter. Only differences are:

Event will be emitted from the parent entity
Event name will be identity:name (ex: 'sprite:visible')

So on, it is a shortcut to this.parent.emit(this.identity + ':' + name, payload).

Kind: instance method of AComponent

Param	Type	Default	Description
name	`String`		Name of this event.
[payload]	`*`		Optional payload to pass to the event.

aComponent.earlyUpdate()

Early update of this component. See Entity documentation for more information.

Kind: instance method of AComponent

aComponent.lateUpdate()

Late update of this component. See Entity documentation for more information.

Kind: instance method of AComponent

aComponent.destructor()

This function will be called on destruction.

You can do some cleanup if needed.

Kind: instance method of AComponent

AComponent.identity ⇒ `String`

On inheriting AComponent, you must override this function to return the component name.

The component name will be the easy-access key on your entity. If you set position, you will be able to access the component using entity.position.

It must be unique.

See the instance function AComponent.identity.

Kind: static property of AComponent

ASystem

ASystem mean Abstract System. You can create systems by inheriting this class.

A system is a 'module' on which ASystem.earlyUpdate() and ASystem.lateUpdate() will run on each Entity.update() call from the world entity. It perform predictable actions on a set of entities.

On inheriting ASystem, you must set a constructor which call super(). First argument is the parent which will be given to your constructor. The second argument must be specified from your constructor: it must be an array with all the components the system can work on.

You must implement earlyUpdate(entities) and/or lateUpdate(entities). First argument is an array of entities, which comply to your components requirements. All entities that have all the required components will be in the given array.

See examples to understand how systems work.

To create systems, you must add SystemComponent to your world entity.

Kind: global class

ASystem

new ASystem(parent, requiredComponents)

On inheriting ASystem, parent will be given to your constructor as first argument. You just have to pass parent to super().

requiredComponents must be specified by yourself: all the components you want in the entities that will be passed to update(). It is an entity filter by components.

Param	Type	Description
parent	`Entity`	The entity which own the system.
requiredComponents	`Array.<AComponent>`	Components filter to get complying entities which will be given to `update()` function.

aSystem.parent ⇒ `Entity`

Kind: instance property of ASystem
Returns: Entity - The Entity which own this system.

aSystem.requiredComponents ⇒ `Array.<AComponent>`

Kind: instance property of ASystem
Returns: Array.<AComponent> - The components which will filter entities to be given to update().

Entity

An entity represent 'a thing' into your world.

By default, an entity is empty: no behaviours, no meaning, no purpose.

You can attach components. As an example, you can create an entity named wall which have the following components: Position, Hitbox, Sprite.
You can create child entities.

On updating an entity, this procedure apply:

Emit nextEarlyUpdate
Call earlyUpdate() on child entities (which call earlyUpdate() on child entities then components)
Call earlyUpdate() on entity's components
Emit nextLateUpdate
Call lateUpdate() on child entities (which call lateUpdate() on child entities then components)
Call lateUpdate() on entity's components

On adding components to an entity, the order they are added matter: first added, first to be updated. Last added, last to be updated.

nextEarlyUpdate and nextLateUpdate may be useful if you do something now and you want to do something at now+1.

It may be useful if you have a drawing system:

On your world, a component is drawing sprites on screen
Childs of your world are sprites.
First, sprites get earlyUpdate() called
Then, drawing system get earlyUpdate() called
Finally, sprites get lateUpdate() called

Kind: global class

Entity
- new Entity([parent], [ComponentsType])
- instance
  - .childs ⇒ Object
  - .parent ⇒ Entity
  - .name ⇒ String
  - .update()
  - ._(name) ⇒ Entity
  - .getChild(name) ⇒ Entity
  - .createChild(name, [ComponentsType]) ⇒ Entity
  - .deleteChild(name)
  - .deleteChildIfExist(name)
  - .deleteChilds()
  - .deleteThis()
  - .has(ComponentsType) ⇒ Boolean
  - .get([ComponentType]) ⇒ AComponent
  - .add(ComponentType, ...args) ⇒ Entity
  - .addMany(ComponentsType) ⇒ Entity
  - .delete(ComponentType) ⇒ Entity
  - .deleteIfExist(ComponentType) ⇒ Entity
  - .deleteMany(ComponentsType) ⇒ Entity
  - .deleteManyIfExist(ComponentsType) ⇒ Entity
- static
  - .createWorld([ComponentsType]) ⇒ Entity

new Entity([parent], [ComponentsType])

Create a new entity.

You must NOT use this function: use static createWorld() or createChild().

Param	Type	Default	Description
[parent]	`Entity`		The parent of this new entity. `null` mean it is a 'world' entity
[ComponentsType]	`Array.<AComponent>`		Components to insert to the new entity. These components must be default-constructible.

entity.childs ⇒ `Object`

Get all childs of this entity. The returned object is a copy of the internal representation and is frozen.

So on, it is read-only.

The returned object won't be kept up to date with later adding or deleting.

Kind: instance property of Entity
Returns: Object - An object with child name as key and child as value

entity.parent ⇒ `Entity`

Get the entity which own this entity.

If this entity represent the world, it will return null.

Kind: instance property of Entity
Returns: Entity - Owner of this entity.

entity.name ⇒ `String`

Get the name of this entity. All entities have a name excepted world entities which have no parent.

Kind: instance property of Entity
Returns: String - Name of this entity

entity.update()

Call earlyUpdate() then lateUpdate(). See documentation of Entity for more information about the update().

You should call this function only on your world Entity.

Kind: instance method of Entity

entity._(name) ⇒ `Entity`

Get a child of this entity.

This function is just an alias for quick-access of getChild(name). See that function for more documentation.

Kind: instance method of Entity
Returns: Entity - The child or null if it does not exist.

Param	Type	Description
name	`String`	Child name you want to get

entity.getChild(name) ⇒ `Entity`

Get a child of this entity.

You can get childs recursively by using points . as delimiter in your name. Example: world.getChild('player.body.arm') will retrieve arm entity which is a child of body entity which is a child of player entity which is a child of world.

Kind: instance method of Entity
Returns: Entity - The child or null if it does not exist.

Param	Type	Description
name	`String`	Child name you want to get

entity.createChild(name, [ComponentsType]) ⇒ `Entity`

Create an entity which will be child of this entity.

name must not contain points . : they are used as delemiter to get child of child.

Kind: instance method of Entity
Returns: Entity - the created entity

Param	Type	Default	Description
name	`String`		Name of the child. You can later get the child using `_()` or `getChild()` functions.
[ComponentsType]	`Array.<AComponent>`		Components to add to the new entity. These components must be default-constructible.

entity.deleteChild(name)

Delete a child. An error will be thrown if child is not found.

Kind: instance method of Entity

Param	Type	Description
name	`String`	Child name you want to delete

entity.deleteChildIfExist(name)

Delete a child if it exist. Does the same thing as deleteChild except it won't throw if the child does not exist.

Kind: instance method of Entity

Param	Type	Description
name	`String`	Child name you want to delete

entity.deleteChilds()

Delete all childs:

Call _destructor() on each child and delete them from this entity.

Kind: instance method of Entity

entity.deleteThis()

Delete this entity and remove all listeners from this entity.

It must be have a parent, else an error will be thrown.

It will also delete all childs of this entity.

Kind: instance method of Entity

entity.has(ComponentsType) ⇒ `Boolean`

Know if components are present on this entity. If not components are given, it will return true.

This function will also return true if you give a super class of an installed component. You can by example have ADrawableComponent which is inherited by SpriteComponent, TextComponent, ...

Kind: instance method of Entity
Returns: Boolean - true if all components are present

Param	Type	Description
ComponentsType	`Array.<AComponent>`	Components that may exist on this entity

entity.get([ComponentType]) ⇒ `AComponent`

Get a specific component from this entity.

If you pass a super class of your component, it will return it.

Kind: instance method of Entity
Returns: AComponent - Return the requested component instance or null.

Param	Type	Description
[ComponentType]	`AComponent`	Type of your component or a subclass to get. `null` if not found.