Engine

import { Engine } from "encompass-ecs";

An Engine is the encompass notion of an ECS System. Engines are responsible for reading the game state and emitting messages, as well as mutating Entities and Components.

A particular type of Component may be modified by only one Engine. If you have two Engines which mutate the same Component type, an error will be thrown.

An Engine which Reads a particular Message is guaranteed to run after all Engines which Emit that particular Message.

Decorators

@Emits(...message_type_args)

Writes MessageTypes to the emit_message_types property.

Arguments:
  • message_type_args (Type<Message>[]) – MessageTypes which are emitted by the Engine.
@Reads(...message_type_args)

Writes MessageTypes to the read_message_types property.

Arguments:
  • message_type_args (Type<Message>[]) – MessageTypes which are read by the Engine.
@Mutates(...component_type_args)

Writes ComponentTypes to the mutate_component_types property.

Arguments:
  • component_type_args (Type<Component>[]) – ComponentTypes which are mutated by the Engine.
@Detects(...component_type_args)

Specifies that the given component types should be tracked by the Detector.

Arguments:
  • component_type_args (Type<Component>[]) – ComponentTypes which should cause the Detector to track an Entity.

Abstracts

update(dt)

Called by the World each frame. Place all of your logic in here.

Arguments:
  • dt (number) – Delta time.

Functions

create_entity()
Returns:An instance of Entity.
emit_message(MessageType)

This function creates a new Message instance and makes it available to be read by other engines.

Arguments:
  • MessageType (Type<Message>) – A constructor reference to a subtype of Message.
Throws:

EmitUndeclaredMessageError – When this function is called on a MessageType which has not been declared in emit_message_types.
Returns Message:
 

An instance of Message of the given type.
emit_component_message(ComponentMessageType, component)

This function creates a new ComponentMessage instance and makes it available to be read by other engines.

Arguments:
  • ComponentMessageType (Type<ComponentMessage>) – A constructor reference for a subtype of ComponentMessage.
  • component (Component) – An instance of a component.
Throws:

EmitUndeclaredMessageError – When this function is called on a MessageType which has not been declared in emit_message_types.
Returns ComponentMessage:
 

An instance of ComponentMessage of the given type.
emit_entity_message(EntityMessageType, entity)

This function creates a new EntityMessage instance and makes it available to be read by other engines.

Arguments:
  • EntityMessageType (Type<EntityMessage>) – A constructor reference for a subtype of EntityMessage.
  • entity (Entity) – An instance of Entity.
Throws:

EmitUndeclaredMessageError – When this function is called on a MessageType which has not been declared in emit_message_types.
Returns EntityMessage:
 

An instance of EntityMessage of the given type.
get_entity(entity_id)
Arguments:
  • entity_id (number) – The ID of the Entity.
Returns Entity | undefined:
 

Either the Entity instance with given ID, or undefined if none exists.
read_components(ComponentType)
Arguments:
  • ComponentType (Type<Component>) – A constructor reference for a subtype of Component.
Returns GCOptimizedList<Readonly<ComponentType>>:
 

A GCOptimizedSet containing all active Components of the given ComponentType. The Components are readonly.
read_component(ComponentType)
Arguments:
  • ComponentType (Type<Component>) – A constructor reference for a subtype of Component.
Returns Readonly<TComponent> | null:
 

Returns a singleton Component of the given type or null if none exist.
read_components_mutable(ComponentType)
Arguments:
  • ComponentType (Type<Component>) – A constructor reference for a subtype of Component.
Throws:

IllegalComponentMutationError – When this function is called on a ComponentType which has not been declared in mutate_component_types.
Returns GCOptimizedList<ComponentType>:
 

A GCOptimizedSet containing mutable Component instances of the given ComponentType.
read_component_mutable(ComponentType)
Arguments:
  • ComponentType (Type<Component>) – A constructor reference for a subtype of Component.
Returns Readonly<TComponent> | null:
 

Returns a singleton Component of the given type or null if none exist.
read_inactive_components(ComponentType)
Arguments:
  • ComponentType (Type<Component>) – A constructor reference for a subtype of Component.
Returns GCOptimizedList<Readonly<ComponentType>>:
 

A GCOptimizedSet containing all inactive Components of the given ComponentType. The Components are readonly.
make_mutable(component)
Arguments:
  • component (Readonly<Component>) – A readonly Comopnent.
Returns Component:
 

A mutable version of the Component.
read_messages(MessageType)
Arguments:
  • MessageType (Type<Message>) – A constructor reference for a subtype of Message.
Throws:

ReadUndeclaredMessageError – When this function is called with a MessageType that has not been declared in @Reads.
Returns GCOptimizedList<Message>:
 

A GCOptimizedSet containing all Message instances of MessageType.
some(MessageType)
Arguments:
  • MessageType (Type<Message>) – A constructor reference for a subtype of Message.
Throws:

ReadUndeclaredMessageError – When this function is called with a MessageType that has not been declared in @Reads