punyecs 0.1.0__tar.gz

punyecs-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.3
+Name: punyecs
+Version: 0.1.0
+Summary: A simple attribute-based approach to ECS.
+Author-email: csumnicht@berkeley.edu
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# punyecs
+
+`punyecs` is a tiny Entity Component System (ECS) inspired by [tiny-ecs](https://github.com/bakpakin/tiny-ecs) for Python. `punyecs` operates directly on class attributes as opposed to creating components along with querying mechanisms for fine grain control over which objects are operated on by systems similar to how tiny-ecs works on Lua tables.
+
+# What is it?
+
+Instead of requiring inheritance, one can specify which attributes to operate on and any object (regardless of class) that has those attributes is operated on. That is, if a `Player` has an `x` and `y` attribute and an (unrelated) `Enemy` class has an `x` and `y` attribute you can have them both influenced by a `World` object. This avoids complicated inheritance hierarchies.
+
+Here is a small example to illustrate the above:
+
+```py
+from dataclasses import dataclass
+from punyecs import World, requirements
+
+w = World()
+
+@dataclass
+class Player:
+    x: float
+    y: float
+
+@dataclass
+class Enemy:
+    x: float
+    y: float
+
+@requirements(w, {"x", "y"})
+def move(e, dt):
+    e.x += 0.1
+    e.y += 0.1
+
+player = Player(0.0, 0.0)
+enemy = Enemy(1.0, 1.0)
+w.add(player)
+w.add(enemy)
+
+w.update(1)
+print(player.x)
+# Prints 0.1
+print(player.y)
+# Prints 0.1
+
+print(enemy.x)
+# Prints 1.1
+print(enemy.y)
+# Prints 1.1
+```
+
+# A Bit More Sophistication
+
+We may also do exclusions for fine grain control. Returning to the example above, we may want various enemies to move like above but instead want to allow controller input for the `player` object. We can avoid influencing the `player` object by putting it in the excluded objects list. The function `f` becomes:
+
+```py
+@requirements(w, {"x", "y"}, exclude_objs=[player])
+def move(e, dt):
+    e.x += 0.1
+    e.y += 0.1
+```
+
+Then after every `world.update(1)`, the `player` object *will still remain at* `x=0.0`, `y=0.0`.
+
+# Even More Sophistication!
+
+It might be inconvenient to exclude *individual* objects if a large number of objects need to be excluded. `punyecs` provides a couple more filtering options. One way around this is to specify which attributes an object should *not* have.
+
+For instance, we may have many different kinds of creatures. Most can follow the usual movement update function, but some creatures have a `wiggle` attribute. `wiggle` could be a Boolean, or even something more sophisticated like a function that describes how the creature wiggles.
+
+To illustrate this consider:
+
+```py
+from dataclasses import dataclass
+from punyecs import World, requirements
+
+w = World()
+
+@dataclass
+class Player:
+    x: float
+    y: float
+
+@dataclass
+class WalkingEnemy:
+    x: float
+    y: float
+
+@dataclass
+class Wiggler:
+    x: float
+    y: float
+    wiggle: lambda x: x + 2
+
+@requirements(w, {"x", "y"}, exclude={"wiggle"})
+def move(e, dt):
+    e.x += 0.1
+    e.y += 0.1
+
+@requirements(w, {"wiggle", "x", "y"})
+def wiggle(e, dt):
+    e.x = wiggle(e.x)
+    e.y = wiggle(e.y)
+
+
+player = Player(0.0, 0.0)
+enemy = Enemy(1.0, 1.0)
+wiggler = Wiggle(3.0, 3.0)
+w.add(player)
+w.add(enemy)
+w.add(wiggler)
+
+w.update(1)
+print(player.x)
+# Prints 0.1
+print(player.y)
+# Prints 0.1
+
+print(enemy.x)
+# Prints 1.1
+print(enemy.y)
+# Prints 1.1
+
+print(wiggler.x)
+# Prints 5.0
+print(wiggler.y)
+# Prints 5.0
+```
+
+Thus, `move` does not operate on `wiggler` but `wiggle` does.
+
+# Documentation
+
+Even more filtering options are available. To learn more, see the [readthedocs.](https://punyecs.readthedocs.io/en/latest/api.html)

punyecs-0.1.0/README.md

@@ -0,0 +1,131 @@
+# punyecs
+
+`punyecs` is a tiny Entity Component System (ECS) inspired by [tiny-ecs](https://github.com/bakpakin/tiny-ecs) for Python. `punyecs` operates directly on class attributes as opposed to creating components along with querying mechanisms for fine grain control over which objects are operated on by systems similar to how tiny-ecs works on Lua tables.
+
+# What is it?
+
+Instead of requiring inheritance, one can specify which attributes to operate on and any object (regardless of class) that has those attributes is operated on. That is, if a `Player` has an `x` and `y` attribute and an (unrelated) `Enemy` class has an `x` and `y` attribute you can have them both influenced by a `World` object. This avoids complicated inheritance hierarchies.
+
+Here is a small example to illustrate the above:
+
+```py
+from dataclasses import dataclass
+from punyecs import World, requirements
+
+w = World()
+
+@dataclass
+class Player:
+    x: float
+    y: float
+
+@dataclass
+class Enemy:
+    x: float
+    y: float
+
+@requirements(w, {"x", "y"})
+def move(e, dt):
+    e.x += 0.1
+    e.y += 0.1
+
+player = Player(0.0, 0.0)
+enemy = Enemy(1.0, 1.0)
+w.add(player)
+w.add(enemy)
+
+w.update(1)
+print(player.x)
+# Prints 0.1
+print(player.y)
+# Prints 0.1
+
+print(enemy.x)
+# Prints 1.1
+print(enemy.y)
+# Prints 1.1
+```
+
+# A Bit More Sophistication
+
+We may also do exclusions for fine grain control. Returning to the example above, we may want various enemies to move like above but instead want to allow controller input for the `player` object. We can avoid influencing the `player` object by putting it in the excluded objects list. The function `f` becomes:
+
+```py
+@requirements(w, {"x", "y"}, exclude_objs=[player])
+def move(e, dt):
+    e.x += 0.1
+    e.y += 0.1
+```
+
+Then after every `world.update(1)`, the `player` object *will still remain at* `x=0.0`, `y=0.0`.
+
+# Even More Sophistication!
+
+It might be inconvenient to exclude *individual* objects if a large number of objects need to be excluded. `punyecs` provides a couple more filtering options. One way around this is to specify which attributes an object should *not* have.
+
+For instance, we may have many different kinds of creatures. Most can follow the usual movement update function, but some creatures have a `wiggle` attribute. `wiggle` could be a Boolean, or even something more sophisticated like a function that describes how the creature wiggles.
+
+To illustrate this consider:
+
+```py
+from dataclasses import dataclass
+from punyecs import World, requirements
+
+w = World()
+
+@dataclass
+class Player:
+    x: float
+    y: float
+
+@dataclass
+class WalkingEnemy:
+    x: float
+    y: float
+
+@dataclass
+class Wiggler:
+    x: float
+    y: float
+    wiggle: lambda x: x + 2
+
+@requirements(w, {"x", "y"}, exclude={"wiggle"})
+def move(e, dt):
+    e.x += 0.1
+    e.y += 0.1
+
+@requirements(w, {"wiggle", "x", "y"})
+def wiggle(e, dt):
+    e.x = wiggle(e.x)
+    e.y = wiggle(e.y)
+
+
+player = Player(0.0, 0.0)
+enemy = Enemy(1.0, 1.0)
+wiggler = Wiggle(3.0, 3.0)
+w.add(player)
+w.add(enemy)
+w.add(wiggler)
+
+w.update(1)
+print(player.x)
+# Prints 0.1
+print(player.y)
+# Prints 0.1
+
+print(enemy.x)
+# Prints 1.1
+print(enemy.y)
+# Prints 1.1
+
+print(wiggler.x)
+# Prints 5.0
+print(wiggler.y)
+# Prints 5.0
+```
+
+Thus, `move` does not operate on `wiggler` but `wiggle` does.
+
+# Documentation
+
+Even more filtering options are available. To learn more, see the [readthedocs.](https://punyecs.readthedocs.io/en/latest/api.html)

punyecs-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "punyecs"
+version = "0.1.0"
+description = "A simple attribute-based approach to ECS."
+readme = "README.md"
+authors = [
+    { email = "csumnicht@berkeley.edu" }
+]
+requires-python = ">=3.11"
+dependencies = []
+
+[tool.pyrefly]
+project-includes = [
+    "**/*.py*",
+    "**/*.ipynb",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.5,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+]
+docs = [
+    "sphinx>=9.0.4",
+    "sphinx-automodapi>=0.22.0",
+]

punyecs-0.1.0/src/punyecs/__init__.py

@@ -0,0 +1,111 @@
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+
+@dataclass
+class Query:
+    """A class that represnets which attributes and objects should be allowed
+    (or disallowed) in a group."""
+    and_attr: set[str] = field(default_factory=set)
+    exclude_attr: set[str] = field(default_factory=set)
+    exclude_objs: list[Any] = field(default_factory=list)
+    exclude_attr_vals: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class World:
+    groups: list[tuple[Query, list, list[Callable[[Any, float], None]]]] = \
+            field(default_factory=list)
+
+    def entity_satisfies_query(self, entity, query) -> bool:
+        """Check if an entity should (or should not) be added to a particular
+        group by analyzing the query structure.
+
+        :param entity: The entity to query.
+        :param query: The query to check if the entity can belong to it.
+        """
+        for e in query.exclude_objs:
+            if entity == e:
+                return False
+        for attr in query.and_attr:
+            if not hasattr(entity, attr):
+                return False
+        for attr in query.exclude_attr:
+            if hasattr(entity, attr):
+                return False
+        for attr, val in query.exclude_attr_vals.items():
+            if hasattr(entity, attr) and getattr(entity, attr) == val:
+                return False
+        return True
+
+    def push_group(self, query: Query):
+        """Add the group and return that group.
+
+        :param query: The query to associate with the group.
+        """
+        new_group = (query, [], [])
+        self.groups.append(new_group)
+        return new_group
+
+    def add(self, entity: Any):
+        """Add an entity to the world. Under the hood, determines what groups
+        the entity should belong to.
+
+        :param entity: The entity to add to the world.
+        """
+        for query, group, funcs in self.groups:
+            if self.entity_satisfies_query(entity, query):
+                group.append(entity)
+
+    def update(self, dt: float):
+        """Update the world (and all the corresponding groups/entities).
+
+        :param dt: The amount of time that elapsed. (Common for videogame 
+           applications)
+        """
+        for _, group, funcs in self.groups:
+            for func in funcs:
+                for entity in group:
+                    func(entity, dt)
+
+
+def 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):
+    """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).
+
+    :param require: Required attribute for an entity to be ran.
+    :param exclude: Entity must *not* have the following attributes.
+    :param exclude_objs: Exculde individual objects from being ran.
+    """
+    exclude = exclude or set()
+    exclude_objs = exclude_objs or []
+    exclude_attr_vals = exclude_attr_vals or {}
+    def req_dec(func):
+        query = Query(require, exclude, exclude_objs, exclude_attr_vals)
+        group = world.push_group(query)
+        def inner(e, dt):
+            return func(e, dt)
+        group[2].append(inner)
+        return inner
+    return req_dec
+
+def 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.
+
+    :param world: World to query over.
+    :param query: Query to execute against.
+    """
+    def query_dec(func):
+        group = world.push_group(query)
+        def inner(e, dt):
+            return func(e, dt)
+        group[2].append(inner)
+        return inner
+    return query_dec