tinyecs API

Primary functions

tinyecs.create_entity(tag: EntityID = None, components: dict[ComponentID, Component] | None = None, properties: _OptionalProperties = None) → EntityID[source]

Create a new entity

Parameters:

  • tag – an optional ID for the entity, e.g. “player” if no tag is passed, a uuid is generated

  • components – A dict with component IDs as keys and components as values (see add_component)

  • properties – An iterable of properties

Returns:

The entity ID. Same as given if one is passed, otherwise a uuid4

Return type:

Hashable

tinyecs.add_component(eid: EntityID, cid: ComponentID, comp: Component) → ComponentID[source]

Add a component to the registry.

Parameters:

  • eid (hashable) – The entity id to add the component to

  • cid (hashable) – An identifier for the component This will be used to assign systems to entities

  • comp –

    The actual data object A comp can be anything that holds data, just a string, e.g. a name, a SimpleNamespace, a dataclass, …

    Note: Technically, there is no reason a comp object couldn’t have methods, but by concept, functionality is reserved for the System working on the components, not the component itself.

Returns:

cid – The cid that was put in as an argument.

Return type:

hashable

Raises:

UnknownEntityError – If the eid doesn’t exist in the registry.

tinyecs.add_components(eid: EntityID, components: dict[ComponentID, Component]) → list[ComponentID][source]

A convenience wrapper around add_component

Parameters:

components – A dict with component IDs as keys and components as values (see add_component)

Return type:

None

tinyecs.remove_entity(eid: EntityID) → None[source]

Remove an entity from the system.

Removes all bindings to components and the entity_id itself from the registry.

non-existent entity_ids will be silently ignored

Parameters:

eid (hashable) – The entity ID

Return type:

None

tinyecs.remove_component(eid: EntityID, *cids: ComponentID) → None[source]

Remove one or more components from an entity.

Parameters:

  • eid – The entity to remove the component from

  • cids – The component ids to remove

  • attribute (If the component has a shutdown)

  • of (it is assumed to be a list)

  • order. (zero parameter functions to be called in)

  • Note (If the entity no longer exists, the error is silently ignored.)

Return type:

None

tinyecs.run_system(dt: float, fkt: SystemFunction, *cids: ComponentID, has_properties: _OptionalProperties = None, **kwargs: dict[str, Any]) → _RunSystemResult[source]

Run the system for the matching cids.

Parameters:

  • dt – delta time since the last frame (miliseconds)

  • fkt – the actual system function

  • *cids – the components to run on

  • has_properties – set of required properties

  • listed (The fkt gets the list of all entities that contain the)

  • given (components. The list can further be narrowed down my filtering for)

  • requested (properties. Then it runs the function for every entity and the)

  • components

  • heartbeat. (passing dt as)

  • Alternatively (This function is a direct call.)

  • add_system (you can use)

  • below. (combined with run_all_systems or run_domain)

Returns:

A dictionary with entity IDs as key and the function result as value

Return type:

dict

Requesting components

tinyecs.comp_of_eid(eid: EntityID, cid: ComponentID) → Component[source]

Get a single component from an entity.

Parameters:

  • eid – the entity id from which to get the component

  • cid – the component id to filter for

Returns:

component – The requested component of the given entity ID

Return type:

object

tinyecs.comps_of_eid(eid: EntityID, *cids: ComponentID) → list[Component][source]

Get components from the eid for the specified cids.

While cids_of_eid gets component IDs, this function now gets the actual components containing the data.

if cids is empty or None, returns all components of eid.

Parameters:

  • eid – the entity id from which to get the components

  • cids – the list of components to fetch

Returns:

The (filtered) components of eid

Return type:

list

Raises:
tinyecs.eid_has(eid: EntityID, *cids: ComponentID) → bool[source]

check if entity eid has all listed cids.

Parameters:

*cids – All component ids that need to match

Returns:

True if all given cids are available for the specified eid

Return type:

bool

ECS Management

tinyecs.reset() → None[source]

Remove everything registered in the ECS.

Use this to clear everything, e.g. before a new game

Running systems in bulk

tinyecs.add_system(fkt: SystemFunction, *cids: ComponentID) → None[source]

Add a system for the specifiied cids.

Parameters:

  • fkt –

    The system function

    The prototype for the function is

    fkt(delta_time, eid, *comps)

    where delta_time is e.g. the miliseconds from a pygame tick. eid is the id of the entity that matches, and *comps are all requested components for this specific entity.

    This function is called for every entity that matches all specified component ids.

  • *cids – The component ids that are required for this system

Return type:

None

Note

Registering a system automatically creates an archetype from the given cids

tinyecs.remove_system(fkt: SystemFunction) → None[source]

Remove the given function from the registry.

Parameters:

  • fkt – The system function

  • registry (Remove the match for this function from the)

Return type:

None

Note

In contrast to add_system, an existing archetype is not automatically removed.

tinyecs.run_all_systems(dt: float) → dict[SystemFunction, _RunSystemResult][source]

Run all registered systems

This calls above run_system for all registered systems with their appropriate components.

Parameters:

dt – delta time

Returns:

A dict of function as key, and the result of run_system as value

Return type:

dict

tinyecs.add_system_to_domain(domain: DomainID, system: SystemFunction) → None[source]

Create or extend a domain with the given system.

Domains are collections of systems that can run with a single function call run_domain.

Note that the system must first be registered with add_system

add_system_to_domain(‘render-phase’, draw_system)

Parameters:

system (Callable) – The system function

Return type:

None

tinyecs.remove_system_from_domain(domain: DomainID, system: SystemFunction) → None[source]

Remove a registered system from the given domain.

Parameters:

system (Callable) – The system function

Return type:

None

Note

If the system is not in the domain, the error is silently ignored.

tinyecs.run_domain(dt: float, domain: DomainID) → dict[SystemFunction, _RunSystemResult][source]

Run all systems within domain.

This is the same as run_all_systems, but limited to a specific domain.

Parameters:

dt – delta time

Returns:

A dict of function as key, and the result of run_system as value

Return type:

dict

Other helpers

tinyecs.cid_of_comp(eid: EntityID, comp: Component) → ComponentID[source]

Get the cid of a component.

A system only receives an actual component, but cannot know under which name this was targetted. This function searches the cid of the given component.

Note: This is a relatively expensive operation, but since it will mostly be used to clean up old connections between entities, it should be a one-shot and worth the price.

Parameters:

  • eid (hashable) – The entity ID

  • comp (object) – The component to identify

Returns:

The cid that the given component was added under.

Return type:

hashable

Raises:
tinyecs.cids_of_eid(eid: EntityID) → list[ComponentID][source]

Return the list of component IDs of the specified entity

Parameters:

eid (hashable) – The entity ID

Returns:

List of component IDs of this entity

Return type:

list

Raises:

UnknownEntityError – If the entity is not registered (anymore).

tinyecs.eid_of_comp(comp: Component) → {typing.Unpack[EntityID]}[source]

Find the entity id for object comp.

Parameters:

comp – the component to find the entity of

Returns:

The entity_id the given component belongs to

Return type:

entity_id

tinyecs.eids_by_cids(*cids: ComponentID, has_properties: _OptionalProperties = None) → list[tuple[EntityID, list[Component]]][source]

get eids that match all specified cids

Parameters:

  • *cids – All component ids that need to match

  • has_properties (set|tuple|list) – Optional set/tuple/list of required properties

Returns:

A list of tuples of entity IDs and components

Return type:

list

tinyecs.has(eid: EntityID, has_properties: _OptionalProperties = None) → bool[source]

Check if the given eid is valid.

There is no reason to not use eid in tinyecs.eidx. This is just for people who prefer a functional interface.

Parameters:

  • eid – The entity to verify

  • has_properties – Optional set of required properties

Returns:

True if the eid is valid

Return type:

bool

tinyecs.healthcheck() → bool[source]

Perform a health check on the registry.

This function checks if the cross references between the entity index and the component index are still bi-directional.

NOTE: This function is performance heavy and not designed to use in a system. It’s intended for debugging purposes only, e.g. after setting a breakpoint.

Returns:

True if successful, RegistryError exception otherwise.

Return type:

bool

Raises:

RegistryError(error, eid, cid, component, other=None) – error verbose error message eid id of entity cid id of component component component object other component in other index or None

Archetypes

tinyecs.create_archetype(*cids: ComponentID) → None[source]

Create an archetype from the provided cids.

An archetype is a fixed combination of components. Each time a component is added or removed from an entity, that entity and its components are added/removed from the archetype.

This removes the need to search through all entities for the matching cids in favour of returning the finished list directly.

Since every system is usually run every frame, there are a lot of searches, which is very expensive.

The cost to insert/remove an entity into/from the archetype is a rather small operation that is only done when the entity is changed.

Note

Archetypes are created automatically as soon as a system runs for the first time. Manually creating an archetype is only useful if a function wishes to work on a set of entities outside the run_system framework.

Parameters:

cids –

The list of cids that define the archetype.

Note: Order is important, since the system relies on it.

Return type:

None

tinyecs.add_to_archetype(eid: EntityID) → None[source]

Make sure, eid is registered with all appropriate archetypes.

Parameters:

  • eids – The entity ID to add to the archetype

  • called (There should be no need to call this function manually. It's)

  • internally

  • this (when a new component is added to an entity which makes)

  • before. (entity belong into an archetype it wasn't a member of)

tinyecs.comps_of_archetype(*cids: ComponentID, has_properties: _OptionalProperties = None) → list[_EntityComponentsBundle][source]

Return the given archetype.

Primarily used by run_system.

Returns a list of tuples consisting of eid and components.

Parameters:

  • cids – The cids that define the archetype.

  • has_properties – Optional set of required properties

Returns:

A list of tuples of (eid, components)

Return type:

List[tuple[Hashable, list[object]]]

Raises:

UnknownArchetypeError – If the given archetype doesn’t exist.

tinyecs.remove_archetype(cids: Iterable[ComponentID]) → None[source]

Remove an archetype from the system. (See add_archetype).

Parameters:

cids – The list of component IDs that construct the archetype.

Return type:

None

tinyecs.remove_from_archetype(eid: EntityID, cid: ComponentID | None = None) → None[source]

Make sure, eid is only registered with appropriate archetypes.

Parameters:

  • eids – The entity ID to remove from the archetype

  • cid – An optional component ID.

  • called (There should be no need to call this function manually. It's)

  • internally

  • entity (so that the)

  • entity

  • archetype. (no longer belongs to that)

Properties

tinyecs.set_property(eid: EntityID, property: Property) → None[source]

Add a property to the given entity.

Parameters:

  • eid (hashable) – The entity id to add the component to

  • property (hashable) – A flag or tag that can be filtered, e.g. ‘is_drawable’

Return type:

None

Raises:

UnknownEntityError – If the entity is not registered (anymore).

tinyecs.set_properties(eid: EntityID, properties: Iterable[Property]) → None[source]

Add a list of properties to the given entity.

Parameters:

  • eid – The entity ID to add the properties to.

  • property – The list of properties to add.

  • set_property. (This is just a convenience wrapper around)

tinyecs.remove_property(eid: EntityID, prop: Property) → None[source]

Removes a property from the given entity.

Parameters:

  • eid (hashable) – The entity id to add the component to

  • property (hashable) – The property to remove

Return type:

None

Raises:

UnknownEntityError – If the entity is not registered (anymore).

tinyecs.has_property(eid: EntityID, prop: Property) → bool[source]

Checks if the given entity has that property.

Parameters:

  • eid (hashable) – The entity id to add the component to

  • property (hashable) – The property to check for

Return type:

bool

Raises:

UnknownEntityError – If the entity is not registered (anymore).

tinyecs.clear_properties(eid: EntityID) → None[source]

Removes all properties from the given entity.

Parameters:

eid (hashable) – The entity id to add the component to

Return type:

None

Raises:

UnknownEntityError – If the entity is not registered (anymore).

tinyecs.eids_by_property(*properties: Property) → list[EntityID][source]

Get a list of entities that match all given properties.

Parameters:

*properties – All properties that need to match

Returns:

Entities matching the given properties

Return type:

list[EntityID]

tinyecs.purge_by_property(*properties: Property) → None[source]

Purge entities that match all given properties.

This is useful to clean up all entities belonging to a sub state without impacting the remaining registry.

Parameters:

*properties – All properties that need to match

Exceptions

exception tinyecs.UnknownEntityError[source]

Raised if information from an unknown entity is requested.

exception tinyecs.UnknownComponentError[source]

Raised if an unknown component is requested.

exception tinyecs.UnknownSystemError[source]

Raised if an unknown system is requested.

exception tinyecs.UnknownArchetypeError[source]

Raised if an unknown archetype is requested.

exception tinyecs.RegistryError(error, *, eid, cid=None, component=None, other=None, properties=None)[source]

Raised if an inconsistency is found in the internal ecs registry.

Type-hinting

For readability in your code, if you use type hinting, tinyecs defines the following aliases:

type EntityID = Hashable
type ComponentID = Hashable
type DomainID = Hashable
type Property = Hashable
type Component = object