API

class punyecs.Query(and_attr: set[str] = <factory>, exclude_attr: set[str] = <factory>, exclude_objs: list[~typing.Any] = <factory>, exclude_attr_vals: dict[str, ~typing.Any] = <factory>, exclude_attr_funcs: dict[str, ~typing.Callable[[~typing.Any], bool]] = <factory>)

A class that represnets which attributes and objects should be allowed (or disallowed) in a group.

class punyecs.World(groups: list[tuple[punyecs.Query, list, list[typing.Callable[[typing.Any, float], NoneType]]]] = <factory>)
add(entity: Any)

Add an entity to the world. Under the hood, determines what groups the entity should belong to.

Parameters:

entity – The entity to add to the world.

extend(entities: list[Any])

Add a collection of entities to the world.

Parameters:

entities – The collection of entities to add to the world.

push_group(query: Query)

Add the group and return that group.

Parameters:

query – The query to associate with the group.

update(dt: float)

Update the world (and all the corresponding groups/entities).

Parameters:

dt – The amount of time that elapsed. (Common for videogame applications)

punyecs.entity_satisfies_query(entity, query) → bool

Check if an entity should (or should not) be added to a particular group by analyzing the query structure.

Parameters:

  • entity – The entity to query.

  • query – The query to check if the entity can belong to it.

punyecs.inject_attrs(attrs_val: dict[str, Any], exclude=None, override=None)

Use as a class decorator. Given a dictionary of attribute name to value pairs, set attributes of every object to include those as attributes. Furthermore, if exclude is supplied, do not include those attributes. Lastly, if you want to customize the value of an attribute, you may override the supplied value with an override dictionary. :param attr_vals The attribute to value dictionary. :param exclude The attributes to exclude from injection. Defaults to None. :param override The attributes to override their default values. Defaults to None.

punyecs.one_shot(world: World, require: set[str], exclude: set[str] | None = None, exclude_objs: list[Any] | None = None, exclude_attr_vals: dict[str, Any] | None = None, exclude_attr_funcs: dict[str, Callable[[Any], bool]] | None = None)

Use as a decorator. Suppose you have a function f(e) that operates on some entity and you decorate it with one_shot. The returned function takes no parameters and when called it is applied to every entity that satisfies the query declared in the one_shot decorator. This contrasts with the requirements decorator, because requirements causes all decorated functions to invoke when update is called.

Parameters:

  • require – Required attribute for an entity to be ran.

  • exclude – Entity must not have the following attributes.

  • exclude_objs – Exculde individual objects from being ran.

  • exclude_attr_vals – Exclude objects that have an attribute with a particular value.

  • exclude_attr_funcs – Exclude objects whose attributes do not satisfy certain predicates.

punyecs.query(world: World, query: Query)

Use as a decorator, runs the decorated function on each entity that satisfy the query object (similar to requirements but takes in a Query object directly. requirements builds a query object.

Parameters:

  • world – World to query over.

  • query – Query to execute against.

punyecs.requirements(world: World, require: set[str], exclude: set[str] | None = None, exclude_objs: list[Any] | None = None, exclude_attr_vals: dict[str, Any] | None = None, exclude_attr_funcs: dict[str, Callable[[Any], bool]] | None = None)

Use as a decorator, runs the decorated function on each entity that has the required components and none of the excluded components (or excluded objects).

Parameters:

  • require – Required attribute for an entity to be ran.

  • exclude – Entity must not have the following attributes.

  • exclude_objs – Exculde individual objects from being ran.

  • exclude_attr_vals – Exclude objects that have an attribute with a particular value.

  • exclude_attr_funcs – Exclude objects whose attributes do not satisfy certain predicates.