API Documentation

ecs Package

An entity system in Python.

exceptions Module

Exceptions that may be raised.

exception ecs.exceptions.DuplicateSystemTypeError(system_type)[source]

Bases: exceptions.Exception

Error indicating that the system type already exists in the system manager.

Parameters:system_type (type) – type of the system
exception ecs.exceptions.NonexistentComponentTypeForEntity(entity_instance, component_type)[source]

Bases: exceptions.Exception

Error indicating that a component type does not exist for a certain entity.

  • entity (Entity) – entity without component type
  • component_type (type) – component type not in entity

managers Module

Entity and System Managers.

class ecs.managers.EntityManager[source]

Provide database-like access to components based on an entity key.

add_component(entity_id, component_instance)[source]

Add a component to the database and associates it with the given entity_id. entity_id can be an ecs.models.Entity object or a plain int.

component_for_entity(entity_id, component_type)[source]

Return the instance of component_type for the entity_id from the database.

  • entity_id (int) – entity GUID
  • component_type (type) – a type of created component

list of (entity_id, component_instance) tuples

Return type:

tuple of (int, ecs.models.Component)

Raises :

NonexistentComponentTypeForEntity when component_type does not exist on entity_instance


Return a new entity instance with the current lowest GUID value. Does not store a reference to it, and does not make any entries in the database referencing it.

Returns:the new entity
Return type:ecs.models.Entity

Get this manager’s database. Direct modification is not permitted.

Returns:the database
Return type:dict

Return a list of (entity_id, component_instance) tuples for all entities in the database possessing a component of component_type. Return an empty list if there are no components of this type in the database. Can use in a loop like this, where Renderable is a component type:

for entity, renderable_component in entity_manager.pairs_for_type(Renderable):
    pass # do something
Parameters:component_type (type) – a type of created component
Returns:list of (entity_id, component_instance) tuples
Return type:tuple of (int, ecs.models.Component)
remove_component(entity_id, component_type)[source]

Remove the component of component_type associated with entity_id from the database. Doesn’t do any kind of data-teardown. It is up to the system calling this code to do that. In the future, a callback system may be used to implement type-specific destructors.

  • entity_id (int) – GUID of the entity
  • component_type (ecs.models.Component) – component to remove from the entity

Remove all components from the database that are associated with entity_id, with the side-effect that the entity is also no longer in the database.

Parameters:entity_id (int) – entity GUID
class ecs.managers.SystemManager[source]

A container and manager for ecs.models.System objects.


Add a ecs.models.System instance to the manager.

Parameters:system_instance (ecs.models.System) – instance of a system

Tell the manager to no longer run the system of this type.

Parameters:system_type (type) – type of system to remove

Get this manager’s list of systems.

Returns:system list
Return type:list of ecs.models.System

Run all systems in order, for this frame.

Parameters:dt (float) – delta time, or elapsed time for this frame

models Module

Entity, Component, and System classes.

class ecs.models.Component[source]

Class from which all components should derive.

class ecs.models.Entity(guid)[source]

Encapsulation of a GUID to use in the entity database.

Parameters:guid (int) – globally unique identifier
class ecs.models.System[source]

An object that represents an operation on a set of objects from the game database. The update() method must be implemented.


Run the system for this frame. This method is called by the system manager, and is where the functionality of the system is implemented.

Parameters:dt (float) – delta time, or elapsed time for this frame

Table Of Contents

Previous topic


This Page