API

class punyecs.Const(val: Any)

Wrapper for constant values in subject_to queries.

class punyecs.Constraint(unary_op: Callable[[Any], Any] | None = None, bin_op: Callable[[Any, Any], Any] | None = None, val1: c | Const | None = None, val2: c | Const | None = None)

The kind of object supplied to a subject_to arguments of decorator functions.

class punyecs.Group(query, entities, systems)
entities

Alias for field number 1

query

Alias for field number 0

systems

Alias for field number 2

class punyecs.Query(and_attr: Trait, constraint: Constraint | None = None)

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

class punyecs.Trait(**kwargs)

A collection of attributes along with their values that other classes can be given.

class punyecs.World(groups: list[Group] = <factory>, entities: list[Any] = <factory>)

A class that represents a world that applies to changes to the objects it governs. (Particularly with .update(...) method.

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.

deserialize(src: str)

Loads and initializes objects of JSON file to be the world.

Parameters:

src – Relative path for JSON file to load world data from.

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.

remove(*entities: Any) → None

Remove any specified entities from the this world.

Parameters:

*entities –

The entities to be removed.

serialize(dest: str) → None

Serializes world objects in JSON file.

Parameters:

dest – Relative path for JSON file to store world in.

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.and_(self: Any)

Cannot override and, so and_ is used to conjunct two Contraints.

punyecs.entity_satisfies_query(entity: Any, query: 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.ex_attr(obj, name)

Exclude a property in a subject_to clause.

Parameters:

  • obj – The obj to exclude a property from.

  • name – The name of the property.

punyecs.give_traits(*traits: Trait, 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.

Parameters:

  • *traits –

    The attribute to value dictionary.

  • exclude – The attributes to exclude from injection. Defaults to None.

  • override – The attributes to override their default values. Defaults

to None.

punyecs.has_attr(obj, name)

Check if a property has an attribute in a subject_to constraint.

Parameters:

  • obj – The object to check.

  • name – The name of the property to check.

punyecs.not_(self: Any)

Cannot override not, so not_ is used to make negations of Contraints.

punyecs.one_shot(world: World, require: Trait, subject_to: Constraint | 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.

  • subject_to – A Constraint object that the object must satisfy.

punyecs.or_(self: Any)

Cannot override or, so or_ is used to disjunct two Contraints.

punyecs.register_bin_op(op: Callable[[Any, Any], Any])

Make a binary operation usable as a subject_to Constraint. :param op: The operation to convert.

punyecs.register_unary_op(op: Callable[[Any], Any])

Make a unary operation usable as a subject_to Constraint. :param op: The operation to convert.

punyecs.requirements(world: World, require: Trait, subject_to: Constraint | 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.

Subject_to:

A Constraint object that the object must satisfy.