esper - API documentation

Processors

class esper.Processor

Base class for all Processors to inherit from.

Processor instances must contain a process method. Other than that, you are free to add any additional methods that are necessary. The process method will be called by each call to World.process, so you will generally want to iterate over entities with one (or more) calls to the appropriate world methods there, such as for ent, (rend, vel) in self.world.get_components(Renderable, Velocity):

The World Class

class esper.World(timed=False)

A World object keeps track of all Entities, Components, and Processors.

A World contains a database of all Entity/Component assignments. The World is also responsible for executing all Processors assigned to it for each frame of your game.

add_component(entity: int, component_instance: Any) → None

Add a new Component instance to an Entity.

Add a Component instance to an Entiy. If a Component of the same type is already assigned to the Entity, it will be replaced.

Parameters:
  • entity – The Entity to associate the Component with.
  • component_instance – A Component instance.
add_processor(processor_instance: esper.Processor, priority=0) → None

Add a Processor instance to the World.

Parameters:
  • processor_instance – An instance of a Processor, subclassed from the Processor class
  • priority – A higher number is processed first.
clear_database() → None

Remove all Entities and Components from the World.

component_for_entity(entity: int, component_type: Type[C]) → C

Retrieve a Component instance for a specific Entity.

Retrieve a Component instance for a specific Entity. In some cases, it may be necessary to access a specific Component instance. For example: directly modifying a Component to handle user input.

Raises a KeyError if the given Entity and Component do not exist. :param entity: The Entity ID to retrieve the Component for. :param component_type: The Component instance you wish to retrieve. :return: The Component instance requested for the given Entity ID.

components_for_entity(entity: int) → Tuple[C, ...]

Retrieve all Components for a specific Entity, as a Tuple.

Retrieve all Components for a specific Entity. The method is probably not appropriate to use in your Processors, but might be useful for saving state, or passing specific Components between World instances. Unlike most other methods, this returns all of the Components as a Tuple in one batch, instead of returning a Generator for iteration.

Raises a KeyError if the given entity does not exist in the database. :param entity: The Entity ID to retrieve the Components for. :return: A tuple of all Component instances that have been assigned to the passed Entity ID.

create_entity(*components) → int

Create a new Entity.

This method returns an Entity ID, which is just a plain integer. You can optionally pass one or more Component instances to be assigned to the Entity.

Parameters:components – Optional components to be assigned to the entity on creation.
Returns:The next Entity ID in sequence.
delete_entity(entity: int, immediate=False) → None

Delete an Entity from the World.

Delete an Entity and all of it’s assigned Component instances from the world. By default, Entity deletion is delayed until the next call to World.process. You can request immediate deletion, however, by passing the “immediate=True” parameter. This should generally not be done during Entity iteration (calls to World.get_component/s).

Raises a KeyError if the given entity does not exist in the database. :param entity: The Entity ID you wish to delete. :param immediate: If True, delete the Entity immediately.

get_processor(processor_type: Type[P]) → P

Get a Processor instance, by type.

This method returns a Processor instance by type. This could be useful in certain situations, such as wanting to call a method on a Processor, from within another Processor.

Parameters:processor_type – The type of the Processor you wish to retrieve.
Returns:A Processor instance that has previously been added to the World.
has_component(entity: int, component_type: Any) → bool

Check if a specific Entity has a Component of a certain type.

Parameters:
  • entity – The Entity you are querying.
  • component_type – The type of Component to check for.
Returns:

True if the Entity has a Component of this type, otherwise False

has_components(entity: int, *component_types) → bool

Check if an Entity has all of the specified Component types.

Parameters:
  • entity – The Entity you are querying.
  • component_types – Two or more Component types to check for.
Returns:

True if the Entity has all of the Components, otherwise False

process(*args, **kwargs)

Call the process method on all Processors, in order of their priority.

Call the process method on all assigned Processors, respecting their optional priority setting. In addition, any Entities that were marked for deletion since the last call to World.process, will be deleted at the start of this method call.

Parameters:args – Optional arguments that will be passed through to the process method of all Processors.
remove_component(entity: int, component_type: Any) → int

Remove a Component instance from an Entity, by type.

A Component instance can be removed by providing it’s type. For example: world.delete_component(enemy_a, Velocity) will remove the Velocity instance from the Entity enemy_a.

Raises a KeyError if either the given entity or Component type does not exist in the database. :param entity: The Entity to remove the Component from. :param component_type: The type of the Component to remove.

remove_processor(processor_type: esper.Processor) → None

Remove a Processor from the World, by type.

Parameters:processor_type – The class type of the Processor to remove.
try_component(entity: int, component_type: Type[CT_co])

Try to get a single component type for an Entity.

This method will return the requested Component if it exists, but will pass silently if it does not. This allows a way to access optional Components that may or may not exist, without having to first querty the Entity to see if it has the Component type.

Parameters:
  • entity – The Entity ID to retrieve the Component for.
  • component_type – The Component instance you wish to retrieve.
Returns:

A iterator containg the single Component instance requested, which is empty if the component doesn’t exist.

try_components(entity: int, *component_types)

Try to get a multiple component types for an Entity.

This method will return the requested Components if they exist, but will pass silently if they do not. This allows a way to access optional Components that may or may not exist, without first having to query if the entity has the Component types.

Parameters:
  • entity – The Entity ID to retrieve the Component for.
  • component_types – The Components types you wish to retrieve.
Returns:

A iterator containg the multiple Component instances requested, which is empty if the components do not exist.

Components

esper does not define any specific Component base class. Instead, normal Python classes are used as Components.