rym-cx

The cx module implements an ECS in python. This module is POC and is not yet feature complete.

> Note: The ESC inventory needs some cleanup. It’s a critical piece of the > design, but it’s clunky to access. It also needs some better documentation.

Usage

Declare Components via Decorator

This decorator is aliased in the root package as cx.component.

Features

Catalogs the class as a component.
Adds “uid” and “entity_uid” properties.
Converts to a dataclass.
Auto-registers instances in the inventory.

Example

>>> from rym import cx
>>> @cx.component
... class Health:
...     max_hp: int
...     current: int

Spawn an Entity

Never use cx.Entity directly. It’s provided only for type hints. Instead, use cx.spawn_entity

>>> from rym import cx
>>> @cx.component
... class Foo: ...
...
>>> cx.spawn_entity((Foo(), ))
[Entity(component=(UUID('4e818f68-299c-4807-bd2b-5d36bd17cc1d'),))]

API

class rym.cx.Component(*args, **kwargs)

class rym.cx.Entity(component: tuple[Component])

Define an entity object.

NOTE: Entity is little more than a struct. Prefer a functional paradigm over OO.

component

A tuple of component UIDs.

Type:: tuple[rym.cx.core.component.Component]

__post_init__() → None: Initialize and link.

property uid: UUID: Return inventory UID.

class rym.cx.MagicMock(spec=None, wraps=None, name=None, spec_set=None, parent=None, _spec_state=None, _new_name='', _new_parent=None, _spec_as_instance=False, _eat_self=None, unsafe=False, **kwargs)

MagicMock is a subclass of Mock with default implementations of most of the magic methods. You can use MagicMock without having to configure the magic methods yourself.

If you use the spec or spec_set arguments then only magic methods that exist in the spec will be created.

Attributes and the return value of a MagicMock will also be MagicMocks.

mock_add_spec(spec, spec_set=False)

Add a spec to a mock. spec can either be an object or a list of strings. Only attributes on the spec can be fetched as attributes from the mock.

If spec_set is True then only attributes on the spec can be set.

reset_mock(*args, return_value: bool = False, **kwargs): Restore the mock object to its initial state.

rym.cx.clear_registrar(*args, **kwargs) → None: Clear catalog and inventory.

async rym.cx.clear_registrar_async(*args, **kwargs) → None: Clear catalog and inventory.

rym.cx.component(klass: T | None = None) → T

Placeholders for functional tests.

The functional tests fail outside of test cases b/c objects are not defined. Define a set of placeholders to allow tests to run (and fail) more accurately.

rym.cx.get_catalog() → Registrar

Return a static catalog.

This function will return the same registrar every time, i.e., the _global_ catalog. Multiple registrar instances may exist at any given time, but only one is the global catalog.

Parameters:: None
Returns:: A static catalog instance.

rym.cx.get_inventory() → Registrar

Return a static inventory.

This function will return the same registrar every time, i.e., the _global_ inventory. Multiple registrar instances may exist at any given time, but only one is the global inventory.

Parameters:: None
Returns:: A static inventory instance.

rym.cx.get_inventory_uid(obj: Any) → None

Return inventory UID of an item.

The attribute name is determined by the registrar, so provide an easy lookup.

NOTE: While this _could_ be on the registrar, it would require access to the: registrar instance. This function assumes we want the global inventory.

rym.cx.register_as_component(klass: T | None = None) → T

Decorate a component class.

Integrates with ECS inventory, including attribuets and post-init updates.
Converts to dataclass

Parameters:: klass – The class to decorate.
Returns:: The modified class as a dataclass.