ECStremity

ECStremity is an Entity-Component library. It is a Python port of the JavaScript library geotic by @ddmills.

• entity : a unique id and a collection of components
• component : a data container
• query : a way to gather collections of entities that match some criteria, for use in systems
• event : a message to an entity and its components

Installation

pip install ecstremity

Usage

To start using ECStremity, import the library and make some components.

from ecstremity import (Engine, Component)

ecs = Engine()

class Position(Component):
    def __init__(self, x: int, y: int) -> None:
        self.x = x
        self.y = y

class Velocity(Component):
    def __init__(self, x: int, y: int) -> None:
        self.x = x
        self.y = y

class Frozen(Component):
    """Tag component denoting a frozen character."""

All components must be registered with the engine. Component registration must use the class symbol (i.e. do not use the component name attribute).

ecs.register_component(Position)
ecs.register_component(Velocity)
ecs.register_component(Frozen)

Instruct the engine to make a new entity, then add components to it. Once a component is registered, it can be accessed using the class symbol or a string representing the class. The name attribute is not case-sensitive.

entity = ecs.create_entity()

entity.add(Position)
entity.add("Velocity")

The ecstremity library has no actual "system" class. Instead, instruct the engine to produce a query. For example, make a query that tracks all components that have both a Position and Velocity component, but not a Frozen component. A query can have any combination of the all_of, any_of, and none_of quantifiers.

kinematics = ecs.create_query(
    all_of = ['Position', 'Velocity'],
    none_of = ['Frozen']
    )

Loop over the result set to update the position for all entities in the query. The query will always return an up-to-date list containing entities that match.

def loop(dt):
    for entity in kinematics.result:
        entity['Position'].x += entity['Velocity'].x * dt
        entity['Position'].y += entity['Velocity'].y * dt

Changelog

v.1.0.1

Initial release

v.1.0.2

• Changed how component names are handled. Previously creating a component required setting a class variable name with a string in all-caps that is identical to the class name, e.g. if a component was created as class Position, the class required a variable name = "POSITION". Now all components inherit from componentmeta which handles this automatically. All references to component names inside the engine also convert the name string to the required casing.

• Added the ability to make use of the EntityEvent system. Use entity.fire_event('event_name', data) where data can be any object (typically a dict) that you want to pass to an entity's components. The 'event_name' should have a corresponding on_event_name method on one or more components of the entity, which will have the event passed to it.

• Added a prefab system. This is a work-in-progress addition, but essentially you can now define component structures that can be applied all at once to an entity, allowing for templating of entity types.

v.1.0.3

• Miscellaneous fixes and performance updates.
• Fixed an issue with queries not updating their cache when components are added/removed from an entity.

v.1.0.4

• Added an EngineAdapter class that allows for passing in a reference to the game client.
• Added entity cloning. Use entity.clone() to make a copy of an entity with all attached components.
• Added an EventData class to pass in as the data argument of entity.fire_event. This base class is meant to be extensible, but by default it has five optional parameters:
  • instigator: Entity
    Used to pass reference to the entity that fired the event.
  • target: Union[Tuple[int, int], Entity]
    Used to pass reference to an entity or position that can be used for various things, like forwarding an event or querying for data.
  • interactions: List[Dict[str, str]]
    Used to get back a list of interactions from a component. Typical format is {'name': 'event_name', 'event': 'on_event_method'}.
  • callback: Callable[[Any], Any]
    A callback that can be executed inside a component.
  • cost: float
    An event cost, for use with energy-based action systems.
• Added EntityEvent.route to trigger forwarding of an event to a target entity. For example, in my project game Anathema, I use this to query a target entity for interactions, say when bumping into it:

class Legs(Component):
  # ...
  def on_try_move(self, evt: EntityEvent) -> None:
      if self.area.is_blocked(*evt.data.target):
          if self.area.is_interactable(*evt.data.target):
              self.entity.fire_event('try_interact', evt.data)  

and then in a separate component:

class Brain(Component):
    # ...
    def on_try_interact(self, evt: EntityEvent) -> None:
        evt.data.instigator = self.entity
        evt.data.interactions = []
        
        target: Entity = self.client.interaction_system.get(*evt.dat.target)
        routed_evt: EntityEvent = evt.route(
          new_event='get_interactions', 
          target=target
        )
        routed_evt.handle()

Finally, on a component attached to the target entity, I might have:

class Container(Component):
    # ...
    def on_get_interactions(self, evt) -> None:
        if self._is_open:
            evt.data.interactions.append({
              "name": "Close",
              "event": "try_close_container"
            })
        # ...

Which requires a corresponding Container.on_try_close_container, and so forth.

v.1.0.5

• Radically improved performance by switching to bitmasking for component registration and querying.

v.1.0.6

• Implemented a prefab system.