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

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

Add a component to the registry.

Parameters:

  • eid – The entity id to add the component to

  • cid – 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, …

Returns:

The cid that was put in as an argument.

Raises:

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

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.

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)

Returns:

None

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

Remove an entity from the system.

Parameters:

eid – The entity ID

Returns:

None

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

Note

Non-existent entity_ids will be silently ignored.

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

Returns:

None

If the component has a shutdown_ attribute, it is assumed to be a list of zero parameter functions to be called in order.

Note

If the entity no longer exists, the error is silently ignored.

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

Returns:

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

The fkt gets the list of all entities that contain the listed components. The list can further be narrowed down my filtering for given properties. Then it runs the function for every entity and the requested components, passing dt as heartbeat.

This function is a direct call. Alternatively, you can use add_system combined with run_all_systems or run_domain below.

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:

The requested component of the given entity ID

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

Get components from the eid for the specified cids.

Parameters:

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

  • cids – the list of components to fetch

Returns:

The (filtered) components of eid

Raises:

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

Note

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

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

ECS Management

tinyecs.reset() → None[source]

Remove everything registered in the ECS.

Use this to clear everything, e.g. before a new game or when restarting a game state.

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

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

Returns:

None

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.

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

Returns:

None

Remove the match for this function from the registry

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.

Parameters:

dt – Delta time

Returns:

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

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

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

Create or extend a domain with the given system.

Parameters:

system – The system function

Returns:

None

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

Important

The system must first be registered with add_system.

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

Remove a registered system from the given domain.

Parameters:

system – The system function

Returns:

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.

Parameters:

dt – Delta time

Returns:

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

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

Other helpers

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

Get the cid of a component.

Parameters:

  • eid – The entity ID

  • comp – The component to identify

Returns:

The cid that the given component was added under.

Raises:

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.

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

Return the list of component IDs of the specified entity.

Parameters:

eid – The entity ID

Returns:

List of component IDs of this entity

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

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

  • as_properties – Optional set/tuple/list of required properties

Returns:

A list of tuples of entity IDs and components

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

Check if the given eid is valid.

Parameters:

  • eid – The entity to verify

  • has_properties – Optional set of required properties

Returns:

True if the eid is valid

Note

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

tinyecs.healthcheck() → bool[source]

Perform a health check on the registry.

Returns:

True if successful, RegistryError exception otherwise.

Raises:

RegistryError – If inconsistencies are found in 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.

Archetypes

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

Create an archetype from the provided cids.

:param cids The list of cids that define the archetype. :return: None

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.

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

There should be no need to call this function manually. It’s called internally, when a new component is added to an entity which makes this entity belong into an archetype it wasn’t a member of before.

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

Return the given archetype.

:param cids The cids that define the archetype. :param has_properties Optional set of required properties :return: A list of tuples of (eid, components) :raises UnknownArchetypeError: If the given archetype doesn’t exist.

Primarily used internally by run_system.

Returns a list of tuples consisting of eid and components.

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.

Returns:

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.

There should be no need to call this function manually. It’s called internally, when a component is removed from an entity, so that the entity no longer belongs to that archetype.

Properties

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

Add a property to the given entity.

Parameters:

  • eid – The entity id to add the component to

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

Returns:

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.

This is just a convenience wrapper around set_property.

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

Removes a property from the given entity.

Parameters:

  • eid – The entity id to add the component to

  • property – The property to remove

Returns:

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 – The entity id to add the component to

  • property – The property to check for

Returns:

True if the property is set for the given entity

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 – The entity id to add the component to

Returns:

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

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

Purge entities that match all given properties.

Parameters:

properties – All properties that need to match

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

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.

Parameters:

  • error – The actual error message

  • eid – The entity ID of the defective registry entry

  • cid – The component ID of the defective registry entry

  • component – The component object of the defective registry entry

  • eid – The properties of the defective registry entry

Contains an error message and the registry objects that have been identified as inconsistent.

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