API Reference#
Core Modules#
World#
- class pyecs.core.World.ECSWorld[source]#
Bases:
object- 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.
- 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:
- Parameters:
entity (Entity)
- 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:
- Parameters:
entity (Entity)
component (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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
Managers#
EntityManager#
- class pyecs.managers.EntityManager.EntityManager[source]#
Bases:
object- 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.
- 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)
SystemManager#
- class pyecs.managers.SystemManager.SystemManager[source]#
Bases:
object- register_system(system)[source]#
Register a new system with the system manager.
This method assigns a unique UUID to the system and adds it to the systems list for execution during world updates.
Returns a tuple containing SYSTEM_REGISTERED status and the system on success, or FAILURE if the system is already registered.
- unregister_system(id)[source]#
Remove a system from the system manager by UUID.
This method removes the specified system from all tracking structures and prevents it from being executed during world updates.
Returns SYSTEM_UNREGISTERED on successful removal, or FAILURE if the system ID does not exist.
- Return type:
Literal[<StatusCodes.SYSTEM_UNREGISTERED: 301>,<StatusCodes.FAILURE: -1>]- Parameters:
id (pyecs.common.Types.UUID4)
- remove_system(system)[source]#
Remove a system from the system manager by reference.
This convenience method allows removal using the System object directly rather than requiring the UUID. Internally delegates to unregister_system.
Returns SYSTEM_UNREGISTERED on successful removal, or FAILURE if the system is not currently registered.
- update_all(world, dt)[source]#
Execute the update method for all registered systems.
This method calls the update method on each registered system in registration order, passing the world instance and delta time.
Systems are responsible for querying entities and performing their specific logic during this update cycle.
Processing#
System#
- class pyecs.processing.System.System(*args, **kwargs)[source]#
Bases:
Protocol- property required_components: set[type]#
Define which component types this system requires.
Systems will only process entities that have ALL of the specified component types. This allows the world to efficiently query and cache relevant entities for each system.
Returns a set of component types that entities must have to be processed by this system.
- init(world)[source]#
Initialize the system when added to the world.
This method is called once when the system is registered with the world. Use it to set up resources, caches, event subscriptions, or perform any one-time initialization required by the system.
The world parameter provides access to entity queries, component storage, and other world systems for initial setup.
- Return type:
- update(world, dt)[source]#
Process system logic for the current frame.
This method is called every frame by the world’s update loop. It should contain the core logic of the system, typically querying entities with specific component combinations and updating their state.
The dt parameter represents delta time in seconds since the last frame, enabling frame-rate independent updates for physics and animations.
- cleanup(world)[source]#
Clean up system resources when removed from the world.
This method is called when the system is unregistered from the world or when the world is shutting down. Use it to release resources, close connections, unsubscribe from events, and perform proper cleanup.
Proper cleanup prevents memory leaks and ensures graceful shutdown of system resources.
- Return type:
- __init__(*args, **kwargs)#
Storage#
ComponentStorage#
- class pyecs.containers.ComponentStorage.ComponentStorage[source]#
Bases:
object- 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)
- 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.
- 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.
- 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.
- 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.
- 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)
Archetype#
- class pyecs.containers.Archetype.Archetype[source]#
Bases:
object- 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])
- 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)
- 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.
- 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]
- 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.
Querying#
Query#
- class pyecs.querying.Query.Query[source]#
Bases:
object- 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)