ecs_engine package

Submodules

ecs_engine.component module

class ecs_engine.component.Component

Bases: ABC

Abstract base class for components in an Entity Component System (ECS) architecture.

Components are reusable data containers that entities use to store state or attributes. Standard Components are intended for use cases where multiple entities each have their own distinct instances of a component, such as a HealthComponent where each entity has separate health values.

Methods:

serialize: Converts the component’s state to a serializable format. deserialize: Reconstructs a component instance from serialized data.

Subclasses must implement serialize and deserialize methods to support serialization and deserialization of component state.

classmethod deserialize(serialized_data: Any) → Type
serialize() → Any
class ecs_engine.component.SingletonComponent(*args, **kwargs)

Bases: Component

A singleton component for global state management within an ECS architecture.

SingletonComponents are used when systems and entities need to access shared information that is not owned by individual entities, facilitating a global state accessible across the entire ECS. This design prevents systems from maintaining their own separate states, promoting a more unified and accessible state management approach.

Example use cases include a global InputComponent that stores the user’s most recent inputs, ensuring that this information is readily available to any system or entity that requires it.

ecs_engine.component_pool module

class ecs_engine.component_pool.ComponentPool(component_type: Type[T], entity_capacity: int)

Bases: object

Manages a pool of components and stores them in memory when out of use to reduce object init times. Stores entity_ids in a Sparse Set for quick querying and management.

Attributes:

component_type (Type[Component]): The type of component this pool manages. pool (list[Component]): A list of inactive component instances available for reuse. active (list[Component): A list of Componens that are actively using components of this type. entity_ids (list[int]): The ‘dense’ array part of the sparse set containing entity IDs. sparse (list[int]): The ‘sparse’ array part of the sparse set for quick lookup. entity_capacity (int): The maximum number of entities that can be managed.

Methods:

get_or_create

add_entity(entity: Entity)

Adds an entity to the component pool if it has the required component.

Args:

entity (Entity): The entity to add.

Raises:

ValueError: If the entity does not have the required component.

contains_entity(entity: Entity) → bool

Checks if the entity is in the component pool.

Args:

entity (Entity): The entity to check.

Returns:

bool: True if the entity is in the pool, False otherwise.

get_or_create_component_obj(**kwargs) → T

Retrieves an inactive component from the pool or creates a new instance if the pool is empty.

Args:

**kwargs: Arbitrary keyword arguments passed to the component’s constructor.

Returns:

An instance of the component.

release_component(instance: Component)

Releases a component instance, making it available for reuse.

Args:

instance (Component): The component instance to release.

remove_entity(entity: Entity)

Removes an entity from the component pool if it is present.

Args:

entity (Entity): The entity to remove.

ecs_engine.entity module

class ecs_engine.entity.Entity

Bases: object

Represents an individual entity in the Entity Component System (ECS).

An entity is a general-purpose object characterized by its unique ID and the components attached to it. Entities themselves are kept lightweight and flexible, serving as containers for components that actually implement functionality and data.

Attributes:

next_id (int): Class variable to track the next available entity ID. max_entities (int): Class variable to limit the total number of entities. destroyed_entities_ids (list[int]): Class variable to recycle IDs of destroyed entities.

Methods:

create_next_id: Generates the next entity ID, recycling IDs if necessary. _add_component: Attaches a component to the entity. _remove_component: Removes a component from the entity. get_component: Retrieves a component attached to the entity, if it exists. has_component: Checks whether the entity has a specific type of component attached. reset_attributes: Resets class-level entity tracking attributes.

create_next_id()

Updates next_id for the next entity creation. Recycles old IDs from destroyed_entities_ids if the max_entities limit has been reached. Raises an error if no IDs are available.

destroyed_entities_ids = []
get_component(component_type: Type[T]) → T | None

Retrieves a component of a specific type attached to this entity, if it exists.

Args:

component_type (Type[Component]): The type of component to retrieve.

Returns:

The component instance if found, otherwise None.

has_component(component_type: Type[Component]) → bool

Checks whether the entity has a component of a specific type attached.

Args:

component_type (Type[Component]): The type of component to check for.

Returns:

True if the component is attached, False otherwise.

max_entities = 1000
next_id = 0
classmethod reset_attributes(max_entites: int = 1000)

Resets the class-level attributes tracking entity IDs. Useful for reinitializing the entity system.

Args:

max_entities (int, optional): The new maximum number of entities. Defaults to 1000.

ecs_engine.entity_admin module

class ecs_engine.entity_admin.EcsAdmin(max_entities: int = 1000)

Bases: IEcsAdmin

Manages the core functionality of the Entity Component System (ECS), acting as the central registry for entities, components, systems, and events.

Attributes:

events (list[str]): A list of event names to be registered with the event bus. init_systems (list[Type[System]]): A list of system types to be initialized. max_entities (int): The maximum number of entities the ECS can manage. entity_map (dict[int, Entity]): A mapping of entity IDs to Entity instances. components (list[Component]): A list of all components managed by the ECS. component_pools (dict[Type[Component], ComponentPool]): A dictionary mapping component types

to their respective ComponentPool instances for efficient management.

singleton_components (dict[Type[SingletonComponent], SingletonComponent]): A dictionary holding

instances of singleton components.

Methods:

add_singleton_component: Registers a singleton component with the ECS. get_singleton_component: Retrieves a registered singleton component by type. create_component_pool: Creates and registers a new component pool for a specific component type. get_component_pool: Retrieves a component pool for a specific component type, if it exists. create_entity: Creates a new entity, optionally initializing it with a set of components. get_entity: Retrieves an entity by its ID. attach_component_to_entity: Attaches a component to an entity and registers the entity with the relevant component pool.

add_singleton_component(component: T)

Registers a singleton component instance with the ECS.

Args:

component (SingletonComponent): An instance of a singleton component to be registered.

attach_component_to_entity(entity: Entity, component: Component)

Attaches a component to an entity and registers the entity with the component’s pool.

Args:

entity (Entity): The entity to which the component will be attached. component (Component): The component to attach to the entity.

create_component_pool(component_type: Type[Component]) → ComponentPool

Creates a new component pool for managing instances of a specific component type.

Args:

component_type (Type[Component]): The component type for which to create a pool.

Returns:

A new ComponentPool instance for the specified component type.

create_entity(components=None) → Entity

Creates a new entity and optionally initializes it with a given set of components.

Args:

components (list[Component], optional): A list of components to attach to the new entity.

Returns:

The newly created Entity instance.

events: list[str] = []
get_component_pool(component_type: Type[Component]) → ComponentPool | None

Retrieves the component pool associated with a specific component type, if it exists.

Args:

component_type (Type[Component]): The component type whose pool to retrieve.

Returns:

The ComponentPool instance for the specified component type, or None if not found.

get_entity(entity_id: int) → Entity

Retrieves an entity by its ID.

Args:

entity_id (int): The ID of the entity to retrieve.

Returns:

The Entity instance with the specified ID.

get_singleton_component(component_type: type[T]) → T

Retrieves a singleton component instance by its type.

Args:

component_type (type[T]): The class type of the singleton component to retrieve.

Returns:

An instance of the specified singleton component type.

init_systems: list[Type[System]] = []

ecs_engine.events module

class ecs_engine.events.EventBus

Bases: IEventBus

Implements a simple event bus for an event-driven architecture, facilitating communication between different parts of the application through events.

The EventBus allows components to subscribe to specific events and be notified when those events are published. This decouples the event publishers from the subscribers, improving modularity and flexibility.

Attributes:

events (dict[str, list[Callable]]): A dictionary mapping event names to lists of callback functions (subscribers) that should be invoked when the event is published.

publish(event_name: str, **kwargs)

Publishes an event of a specific type, invoking all subscribed callback functions.

Args:

event_name (str): The name of the event to publish. **kwargs: Arbitrary keyword arguments that will be passed to the callback functions.

Raises:

KeyError: If the event_name does not exist in the events dictionary.

register_event(event_name: str)

Registers a new event type in the event bus. Each event type is identified by a unique name.

Args:

event_name (str): The unique name of the event to register.

Raises:

KeyError: If the event_name already exists in the events dictionary.

subscribe(event_name: str, callback: Callable)

Subscribes a callback function to a specific event type. The callback will be invoked when the event is published.

Args:

event_name (str): The name of the event to subscribe to. callback (Callable): The callback function that should be invoked when the event is published.

ecs_engine.interfaces module

class ecs_engine.interfaces.IEcsAdmin

Bases: ABC

abstract get_component_pool(component_type: Type[Component]) → ComponentPool
abstract get_entity(entity_id: int) → Entity
abstract get_singleton_component(component: Type[T]) → T
class ecs_engine.interfaces.IEventBus

Bases: ABC

abstract publish(event_name: str, **kwargs)
abstract subscribe(event_name: str, callback: Callable)

ecs_engine.system module

class ecs_engine.system.System(ecs_admin: IEcsAdmin, event_bus: IEventBus)

Bases: ABC

Abstract base class for systems in an Entity Component System (ECS) framework.

Systems encapsulate the logic that operates on entities possessing a specific set of components. This class provides mechanisms to subscribe to events, publish events, and access entities and components relevant to the system’s functionality.

Attributes:

_required_components (list[Type[Component]]): A list of component types required by the system. ecs_admin (IEcsAdmin): The central ECS administration interface, providing access to entities and components. event_bus (IEventBus): The event bus for subscribing to and publishing events.

get_component_pools() → list[ComponentPool] | None

Retrieves the component pools for the system’s required components.

Returns:

A list of ComponentPool instances for the required components, sorted by the number of entities.

get_entity(entity_id: int) → Entity

Retrieves an entity by its ID.

Args:

entity_id (int): The ID of the entity to retrieve.

Returns:

The Entity instance with the specified ID.

get_required_entities() → list[Entity]

Retrieves all entities that possess all of the system’s required components.

Returns:

A list of Entity instances that meet the system’s component requirements.

get_singleton_component(component: Type[T]) → T

Retrieves a singleton component instance.

Args:

component (Type[SingletonComponent]): The type of the singleton component to retrieve.

Returns:

An instance of the specified singleton component type.

publish_event(event_name: str, **kwargs)

Publishes an event through the event bus.

Args:

event_name (str): The name of the event to publish. **kwargs: Arbitrary keyword arguments passed to the event handlers.

required_components = []
subscribe_to_events()

Subscribes the system to events based on methods decorated with subscribe_to_event.

ecs_engine.system.subscribe_to_event(event_name)

Decorator to mark a System method for subscription to a specific event.

Args:

event_name (str): The name of the event to subscribe to.

Returns:

The decorated function with an added ‘_event_subscriptions’ attribute.

Module contents