Entity

import { World } from "encompass-ecs";
const world = new World();
const entity = world.create_entity();

An Entity is composed of a unique internal ID and a collection of Components.

Entities do not have any implicit properties or behaviors but are granted these by their collection of Components.

There is no limit to the amount of Components an Entity may have, and Entities can have any number of Components of a particular type.

Entities are active by default and can be deactivated. While deactivated, Entities are still tracked by Engines, but are temporarily ignored. Note that the activation status of an Entity is independent of the activation status of its Components.

Entities typically are either instantiated at load time, or at runtime by a Spawner.

Defining logic on an Entity is an anti-pattern.

Functions

add_component(ComponentType, properties?)

Instantiates a Component of the given subtype and adds it to the Entity.

NOTE: Using the properties argument creates garbage. It may be better to set the component properties after instantiating the component.

Arguments:
  • ComponentType (Type<Component>) – A reference to a constructor for a subtype of Component.
  • properties? (ComponentUserDataOnly<Component>) – An optional reference to an object containing properties of the Component subtype.
Returns Component:
 

An instantiated Component of the given type.
get_components(ComponentType)

Gets all components of the given Component type that belong to the Entity. Note that this does not include subtypes of the given type. Only includes active components by default.

Arguments:
  • ComponentType (Type<Component>) – A reference to a constructor for a subtype of Component.
Returns GCOptimizedList<Component>:
 

A list of active components of the given type.
get_component(ComponentType)

A convenience method for the common case of having a single component of a particular Type on an Entity. Note that if more than one component exists on the Entity, only the first one is returned. Be careful. Only checks active components.

Arguments:
  • ComponentType (Type<Component>) – A reference to a constructor for a subtype of Component.
Returns Component:
 

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

A list of components of the given type.
has_component(ComponentType)

Checks if the Entity has a particular Component type. Only checks active components by default.

Arguments:
  • ComponentType (Type<Component>) – A reference to a constructor for a subtype of Component.
Returns boolean:
 

True if the Entity has a Component of the given type, otherwise false.
has_component_including_inactive(ComponentType)
Arguments:
  • ComponentType (Type<Component>) – A reference to a constructor for a subtype of Component.
Returns boolean:
 

True if the Entity has a Component of the given type including inactive components, otherwise false.
remove_component(component)

Removes a specific Component instance from the entity.

Arguments:
  • component (Component) – A Component.
activate_component(component)

Activates the component, making it tracked by engines. Does nothing if the component is already active.

NOTE: Components are active by default when added to an entity.

Arguments:
  • component (Component) – The component to deactivate.
deactivate_component(component)

Deactivates the component, making it untracked by engines. Does nothing if the component is already inactive.

Arguments:
  • component (Component) – The component to activate.
destroy()

Marks the Entity to be destroyed.

NOTE: The Entity will be destroyed at the end of the World update.