pyecs

Contents

pyecs#

class pyecs.Archetype[source]#
__init__()[source]#
add_entity(entity, components)[source]#

Add an entity and its components to this archetype.

This method stores the entity and its components in parallel arrays, maintaining alignment between entity indices and component indices.

Returns SUCCESS if the entity was added, or FAILURE if the entity already exists in this archetype.

Return type:

TypeAliasType

Parameters:

  • entity (Entity)

  • components (list[Component])

get_component(entity, component_type)[source]#

Retrieve a specific component for an entity.

This method uses the parallel array structure to efficiently locate the requested component by finding the entity’s index.

Returns the component instance if found, or FAILURE if the entity doesn’t exist or doesn’t have the specified component type.

Return type:

Union[TypeAliasType, Literal[<StatusCodes.FAILURE: -1>]]

Parameters:

  • entity (Entity)

  • component_type (type[Component])

iter_components(component_type)[source]#

Iterate over all components of a specific type.

This method yields all component instances of the requested type stored in this archetype, in the same order as their entities.

Yields component instances if the archetype contains the specified component type, otherwise yields nothing.

Return type:

Iterator[TypeAliasType]

Parameters:

component_type (type)

iter_entities()[source]#

Iterate over all entities in this archetype.

This method provides direct iteration over the entities list, useful for systems that need to process all entities with a specific component combination.

Returns an iterator over all entity UUIDs in this archetype.

Return type:

Iterator[TypeAliasType]

remove_entity(entity)[source]#

Remove an entity and all its component data from this archetype.

This method maintains the parallel array structure by removing the entity and its components from the same index across all arrays.

Returns SUCCESS if the entity was removed, or FAILURE if the entity does not exist in this archetype.

Return type:

TypeAliasType

Parameters:

entity (Entity)

exception pyecs.ComponentNotFoundError[source]#

Raised when a component doesn’t exist on an entity.

class pyecs.ComponentStorage[source]#
__init__()[source]#
add_component(entity, component)[source]#

Add or update a component for an entity.

If the component type doesn’t exist on the entity, adds it and transitions the entity to a new archetype. If the component type already exists, updates the existing component in place.

Returns COMPONENT_ADDED for new components, COMPONENT_UPDATED for existing components, or FAILURE if the entity doesn’t exist.

Return type:

Literal[<StatusCodes.COMPONENT_ADDED: 200>, <StatusCodes.COMPONENT_UPDATED: 202>, <StatusCodes.FAILURE: -1>]

Parameters:

  • entity (Entity)

  • component (Component)

get_component(entity, component_type)[source]#

Retrieve a specific component from an entity.

Returns the component instance if found, or FAILURE if the entity doesn’t exist or doesn’t have the specified component type.

Return type:

Union[TypeAliasType, Literal[<StatusCodes.FAILURE: -1>]]

Parameters:

  • entity (Entity)

  • component_type (type[T])

get_entity_components(entity)[source]#

Retrieve all components for an entity.

Returns a list containing all component instances attached to the entity, in the order they appear in the archetype mask.

Return type:

list[TypeAliasType]

Parameters:

entity (Entity)

has_component(entity, component_type)[source]#

Check if an entity has a specific component type.

Returns True if the entity exists and has the component type, False otherwise.

Return type:

bool

Parameters:

  • entity (Entity)

  • component_type (type[T])

move_entity_to_archetype(entity, new_mask, components=None)[source]#

Move an entity to a different archetype.

Handles the transition of an entity between archetypes when components are added or removed. Creates the target archetype if it doesn’t exist.

Returns SUCCESS after moving the entity to the new archetype.

Return type:

TypeAliasType

Parameters:
remove_component(entity, component_type)[source]#

Remove a component type from an entity.

Transitions the entity to a new archetype without the specified component. If this was the last component, removes the entity entirely.

Returns COMPONENT_REMOVED on success, or FAILURE if the entity doesn’t exist or doesn’t have the specified component type.

Return type:

Literal[<StatusCodes.COMPONENT_REMOVED: 201>, <StatusCodes.FAILURE: -1>]

Parameters:

  • entity (Entity)

  • component_type (type[T])

remove_entity(entity)[source]#

Remove an entity and all its components from storage.

Removes the entity from its current archetype and clears all component data associated with it.

Returns SUCCESS on removal, or FAILURE if the entity doesn’t exist.

Return type:

TypeAliasType

Parameters:

entity (Entity)

class pyecs.ECSWorld[source]#
__init__()[source]#
add_component(entity, component)[source]#

Add a component to an existing entity.

This method attaches the specified component to the entity, potentially moving the entity to a different archetype based on its new component set.

Only adds the component if the entity is currently alive in the world.

Return type:

None

Parameters:

  • entity (Entity)

  • component (Component)

add_system(system)[source]#

Register a system with the world.

This method adds the system to the world’s execution pipeline and calls the system’s init method to perform any necessary setup.

The system will be executed during subsequent world update cycles.

Return type:

None

Parameters:

system (System)

create_entity()[source]#

Create a new entity in the ECS world.

This method generates a unique entity identifier and registers it with both the entity manager and component storage system.

Returns the new entity UUID on success, or FAILURE if entity creation fails.

Return type:

Union[TypeAliasType, Literal[<StatusCodes.FAILURE: -1>]]

create_entity_or_raise()#

Create a new entity in the ECS world.

This method generates a unique entity identifier and registers it with both the entity manager and component storage system.

Returns the new entity UUID on success, or FAILURE if entity creation fails.

Return type:

Union[TypeAliasType, Literal[<StatusCodes.FAILURE: -1>]]

destroy_entity(entity)[source]#

Remove an entity and all its components from the world.

This method removes the entity from the entity manager and cleans up all associated component data from the component storage system.

The entity becomes invalid after this operation and should not be used in subsequent operations.

Return type:

None

Parameters:

entity (Entity)

get_component(entity, component_type)[source]#

Retrieve a specific component from an entity.

This method returns the component instance of the specified type attached to the entity.

Returns the component instance if found, or FAILURE if the entity doesn’t exist or doesn’t have the specified component type.

Return type:

Union[TypeAliasType, Literal[<StatusCodes.FAILURE: -1>]]

Parameters:

  • entity (Entity)

  • component_type (type[Component])

get_component_or_raise(entity, component_type)#

Retrieve a specific component from an entity.

This method returns the component instance of the specified type attached to the entity.

Returns the component instance if found, or FAILURE if the entity doesn’t exist or doesn’t have the specified component type.

Return type:

Union[TypeAliasType, Literal[<StatusCodes.FAILURE: -1>]]

Parameters:

  • entity (Entity)

  • component_type (type[Component])

get_components(entity, *component_types)[source]#

Retrieve multiple specific components from an entity.

This method returns a tuple of each component instance of the specified types attached to the entity.

Returns a tuple of components if all are found, or FAILURE if the entity doesn’t exist or doesn’t have any of the specified component types.

Return type:

Union[tuple[TypeAliasType, ...], Literal[<StatusCodes.FAILURE: -1>]]

Parameters:

  • entity (Entity)

  • component_types (type[Component])

get_components_or_raise(entity, *component_types)#

Retrieve multiple specific components from an entity.

This method returns a tuple of each component instance of the specified types attached to the entity.

Returns a tuple of components if all are found, or FAILURE if the entity doesn’t exist or doesn’t have any of the specified component types.

Return type:

Union[tuple[TypeAliasType, ...], Literal[<StatusCodes.FAILURE: -1>]]

Parameters:

  • entity (Entity)

  • component_types (type[Component])

remove_component(entity, component_type)[source]#

Remove a component type from an entity.

This method detaches the specified component type from the entity, potentially moving the entity to a different archetype.

Only removes the component if the entity is currently alive in the world.

Return type:

None

Parameters:

  • entity (Entity)

  • component_type (type[Component])

remove_system(system)[source]#

Unregister a system from the world.

This method calls the system’s cleanup method to release resources and removes it from the world’s execution pipeline.

The system will no longer be executed during world update cycles.

Return type:

None

Parameters:

system (System)

update(dt)[source]#

Execute one update cycle for all registered systems.

This method calls the update method on all registered systems in registration order, passing the delta time for frame-independent updates.

This is typically called once per frame in the main game loop.

Return type:

None

Parameters:

dt (float)

class pyecs.EntityManager[source]#
__init__()[source]#
create_entity()[source]#

Create a new entity in the entity component system.

This method generates a unique UUID4 identifier for the entity and registers it in the alive_entities set.

Returns a tuple containing ENTITY_CREATED status and the new entity UUID on success. FAILURE is typed for future expansion purposes only; currently cannot be returned.

Return type:

Union[tuple[Literal[<StatusCodes.ENTITY_CREATED: 100>], TypeAliasType], Literal[<StatusCodes.FAILURE: -1>]]

destroy_entity(entity)[source]#

Remove an entity from the entity component system.

This method removes the specified entity UUID from the alive_entities set and triggers cleanup of all associated components. The entity becomes invalid after this operation and should not be used in subsequent operations.

Returns ENTITY_DESTROYED status on successful removal, or FAILURE status if the entity does not exist or destruction fails.

Return type:

Literal[<StatusCodes.ENTITY_DESTROYED: 101>, <StatusCodes.FAILURE: -1>]

Parameters:

entity (Entity)

is_alive(entity)[source]#

Check if an entity is currently alive in the system.

Returns True if the entity exists in the alive_entities set, False otherwise.

Return type:

bool

Parameters:

entity (Entity)

exception pyecs.EntityNotFoundError[source]#

Raised when an entity doesn’t exist.

exception pyecs.OperationFailedError[source]#

Raised when an ECS operation fails.

exception pyecs.PyECSError[source]#

Base exception for all PyECS errors.

class pyecs.Query[source]#
__init__()[source]#
execute(storage_or_world)[source]#

Execute the query on either a ComponentStorage or ECSWorld instance.

Return type:

list[pyecs.common.Types.Entity]

Parameters:

storage_or_world (ComponentStorage | ECSWorld)

with_components(*types)[source]#
Return type:

Query

Parameters:

types (type[TypeAliasForwardRef('pyecs.common.Types.Component')])

without_components(*types)[source]#
Return type:

Query

Parameters:

types (type[TypeAliasForwardRef('pyecs.common.Types.Component')])

class pyecs.StatusCodes(*values)[source]#
ENTITY_CREATED = 100#
ENTITY_DESTROYED = 101#
ENTITY_ACTIVE = 102#
ENTITY_INACTIVE = 103#
COMPONENT_ADDED = 200#
COMPONENT_REMOVED = 201#
COMPONENT_UPDATED = 202#
COMPONENT_NOT_FOUND = 203#
SYSTEM_REGISTERED = 300#
SYSTEM_UNREGISTERED = 301#
SYSTEM_STARTED = 302#
SYSTEM_STOPPED = 303#
SYSTEM_ERROR = 304#
QUERY_SUCCESS = 400#
QUERY_NO_RESULTS = 401#
QUERY_INVALID = 402#
SUCCESS = 0#
FAILURE = -1#
PENDING = 1#
NOT_INITIALIZED = 2#

Modules

common

containers

core

exceptions

helpers

managers

processing

querying

tests

Contents