WorldBuilder

import { WorldBuilder } from "encompass-ecs";
const world_builder = new WorldBuilder();

A WorldBuilder is used to build a World out of Engines and Renderers.

The WorldBuilder enforces certain rules about Engine structure. It is forbidden to have messages create cycles between Engines, and no Component may be mutated by more than one Engine.

The WorldBuilder uses Engines and their Message read/emit information to determine a valid ordering of the Engines, which is given to the World.

The WorldBuilder is also responsible for creating the World with an initial state of Entities, Components, and Messages.

It is a mistake to instantiate elements of Encompass directly except for WorldBuilder. These elements should be created either through appropriate WorldBuilder functions, or by Engines.

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.
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.
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.
Returns EntityMessage:
 

An instance of EntityMessage of the given type.
add_engine(EngineType)
Arguments:
  • EngineType (Type<Engine>) – A constructor reference to a subtype of Engine.
Returns Engine:

An instantiated Engine of the given type.
add_renderer(RendererType)
Arguments:
  • RendererType (Type<Renderer>) – A constructor reference to a subtype of Renderer.
Returns Renderer:
 

An instantiated Renderer of the given type.
build()

Call this function when you are done adding engines.

Throws:
  • EngineCycleError – When messages between Engines create a cycle.
  • EngineMutationConflictError – When two different Engines mutate the same Component.
Returns World:

An instantiated World.