microecs 0.2.3__tar.gz → 0.3.0__tar.gz

{microecs-0.2.3 → microecs-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: microecs
-Version: 0.2.3
+Version: 0.3.0
 Summary: MicroECS: Minimal Entity Component System (ECS) in python and numpy
 Home-page: https://gitlab.com/meehai/microecs
 License: MIT
@@ -20,54 +20,55 @@ Usage:
 - Sandbox: `python main.py`
 - Tests: `pytest test/`
 
-There are only 5 primitives (bottom up): `Component`, `Pool`, `QueryResult`, `World` and `System`.
+There are only 4 primitives (bottom up): `Component`, `Pool`, `QueryResult`, `World`:
 
-- `Component` is a simple python dataclass holding only data. All entries must be numpy arrays with metadata fields: shape and dtype. We support 5 dtypes only: `int32`, `float32`, `bool`, `str` and `object`.
+- `Component` is a simple python dataclass holding only data. All entries must be numpy arrays with metadata fields: shape and dtype. We support 5 dtypes only: `int32`, `float32`, `bool`, `str` and `object`. A component with no fields is a valid **tag** for querying (e.g. `class Frozen(Component): pass`).
 - `Pool` is a simple 'archetype' dynamic array, holding entities of the same type (same set of components). Usses `Components` metadata to construct contiguous arrays for all entities of the same type.
 - `QueryResult` is a list of pools that match some query on all the entities of the `World`. It acts as a contiguous numpy-like container that implements numpy's `__array_function__` and `__array_ufunc__`. For all intents and purposes it should feel like a `(N, ...)` view over all the entities. If you need a numpy array (not all ops are supported, for e.g. indexing on the first axis), use `QueryResult.numpy()`. It also exposes `entity_ids`: a flat `(N,)` array of the matched entities' ids, in the same pool-by-pool order as the fields, so you can `zip(qr.entity_ids, qr.position)` or feed an id back to `world.get_entity` / `world.remove_entity`.
-- `World` is a manager of `Pools` and has an overview of all the entities in the scene. It also manages the migration of entities from one pool to the other.
-- `System` is an abstract class that queries the `World` for a subset of `Pools` matching some components. It updates the entities in these pools given some logic (e.g. collisions, motion physics or simply calls the drawing functions). They are merely a convention, not tied to `World` per se.
+- `World` is a manager of `Pools` and has an overview of all the entities in the scene. It also manages the migration of entities from one pool to the other. A `World` can also require extra metadata keys on every field via `World(extra_field_metadata=["serializable"])`, to enforce component-level behavior such as field serialization.
 
 Few relevant concepts:
 
 - `Pool` operates on array indices, while `World` operates on entity IDs (also integers). This allows seamless movement between pools while the high-level systems still working as intended.
 - All mutable operations on `World` are lazy. These are: `add_entity`, `remove_entity`, `add_component`, `remove_component`. They are added to a command buffer which is only executed when calling `world.update()`.
+- `Systems` are a convention, they are not part of this library. They can be defined at application level and act as hooks or callbacks. The `World` object doesn't need to know more than entities and components.
 
 Super simplified main loop structure:
 
 ```python
+from typing import Callable
 import numpy as np
 import raylib as rl
-from microecs import World, Component, TickSystem
+from microecs import World, Component
 
 # components
 class HasPosition(Component):
-    position: np.ndarray = field(metadata={"shape": (2, ), "dtype": "float32"})
+    position: np.ndarray = field(metadata={"shape": (2, ), "dtype": "float32"}) # 'shape' + 'dtype' are always required
 class HasVelocity(Component):
     velocity: np.ndarray = field(metadata={"shape": (2, ), "dtype": "float32"})
 class HasColor(Component):
     color: np.ndarray = field(metadata={"shape": (4, ), "dtype": "int32"})
 
-# systems
-class RenderSystem(TickSystem):
-    def on_tick(self, world: World): # must override
-        query_result = world.query_and((HasPosition, HasColor)) # contiguous-like view of all entities matching
+# systems: Note they are a convention!
+class RenderSystem:
+    def __call__(self, world: World):
+        query_result = world.query(HasPosition, HasColor, exclude=[]) # contiguous-like view of all entities matching
         for position, color in zip(query_result.position, query_result.color): # draw each entity
             DrawEntity(position, color)
 
-class MotionSystem(TickSystem)
-    def on_tick(self, world: World): # must override
-        qr = world.query_and((HasPosition, HasVelocity))
+class MotionSystem:
+    def __call__(self, world: World):
+        qr = world.query(HasPosition, HasVelocity) # 'exclude' is optional
         qr.position[:] = qr.position + qr.velocity * DT # writes back to all the underlying pools using numpy's rules
         # Alternative for per-pool update. Less ergonomic, but maybe faster in extreme cases as it avoids the _Field obj
         for pool in qr.pool_list:
             pool.position[:] = pool.position + pool.velocity * DT
 
 def main():
-    render_system = RenderSystem()
-    update_systems: list[TickSystem] = [MotionSystem()]
+    render_system: list[Callable] = RenderSystem()
+    update_systems: list[Callable] = [MotionSystem()]
 
-    world = World(components=[HasPosition, HasColor, HasVelocity])
+    world = World(components=[HasPosition, HasColor, HasVelocity], extra_field_metadata=None)
     for _ in range(n_objects):
         # NOTE: world.{add/remove}_{entity/component} are lazy. They take effect after the first world.update() call.
         world.add_entity(components=(HasPosition, HasVelocity, HasColor), # tuple of components (types)
@@ -78,11 +79,11 @@ def main():
     while not rl.WindowShouldClose():
         world.update() # must be called at each tick so the lazy methods are processed and entities are updated
         # update stuff...
-        _ = [system.on_tick(world=world) for system in update_systems]
+        _ = [system(world=world) for system in update_systems]
         # draw stuff, e.g. using raylib
         rl.BeginDrawing()
         rl.ClearBackground(rl.RAYWHITE)
         rl.DrawFPS(rl.GetScreenWidth() - 100, 0)
-        render_system.on_tick(world=world)
+        render_system(world=world)
         rl.EndDrawing()
 ```

{microecs-0.2.3 → microecs-0.3.0}/README.md

@@ -8,54 +8,55 @@ Usage:
 - Sandbox: `python main.py`
 - Tests: `pytest test/`
 
-There are only 5 primitives (bottom up): `Component`, `Pool`, `QueryResult`, `World` and `System`.
+There are only 4 primitives (bottom up): `Component`, `Pool`, `QueryResult`, `World`:
 
-- `Component` is a simple python dataclass holding only data. All entries must be numpy arrays with metadata fields: shape and dtype. We support 5 dtypes only: `int32`, `float32`, `bool`, `str` and `object`.
+- `Component` is a simple python dataclass holding only data. All entries must be numpy arrays with metadata fields: shape and dtype. We support 5 dtypes only: `int32`, `float32`, `bool`, `str` and `object`. A component with no fields is a valid **tag** for querying (e.g. `class Frozen(Component): pass`).
 - `Pool` is a simple 'archetype' dynamic array, holding entities of the same type (same set of components). Usses `Components` metadata to construct contiguous arrays for all entities of the same type.
 - `QueryResult` is a list of pools that match some query on all the entities of the `World`. It acts as a contiguous numpy-like container that implements numpy's `__array_function__` and `__array_ufunc__`. For all intents and purposes it should feel like a `(N, ...)` view over all the entities. If you need a numpy array (not all ops are supported, for e.g. indexing on the first axis), use `QueryResult.numpy()`. It also exposes `entity_ids`: a flat `(N,)` array of the matched entities' ids, in the same pool-by-pool order as the fields, so you can `zip(qr.entity_ids, qr.position)` or feed an id back to `world.get_entity` / `world.remove_entity`.
-- `World` is a manager of `Pools` and has an overview of all the entities in the scene. It also manages the migration of entities from one pool to the other.
-- `System` is an abstract class that queries the `World` for a subset of `Pools` matching some components. It updates the entities in these pools given some logic (e.g. collisions, motion physics or simply calls the drawing functions). They are merely a convention, not tied to `World` per se.
+- `World` is a manager of `Pools` and has an overview of all the entities in the scene. It also manages the migration of entities from one pool to the other. A `World` can also require extra metadata keys on every field via `World(extra_field_metadata=["serializable"])`, to enforce component-level behavior such as field serialization.
 
 Few relevant concepts:
 
 - `Pool` operates on array indices, while `World` operates on entity IDs (also integers). This allows seamless movement between pools while the high-level systems still working as intended.
 - All mutable operations on `World` are lazy. These are: `add_entity`, `remove_entity`, `add_component`, `remove_component`. They are added to a command buffer which is only executed when calling `world.update()`.
+- `Systems` are a convention, they are not part of this library. They can be defined at application level and act as hooks or callbacks. The `World` object doesn't need to know more than entities and components.
 
 Super simplified main loop structure:
 
 ```python
+from typing import Callable
 import numpy as np
 import raylib as rl
-from microecs import World, Component, TickSystem
+from microecs import World, Component
 
 # components
 class HasPosition(Component):
-    position: np.ndarray = field(metadata={"shape": (2, ), "dtype": "float32"})
+    position: np.ndarray = field(metadata={"shape": (2, ), "dtype": "float32"}) # 'shape' + 'dtype' are always required
 class HasVelocity(Component):
     velocity: np.ndarray = field(metadata={"shape": (2, ), "dtype": "float32"})
 class HasColor(Component):
     color: np.ndarray = field(metadata={"shape": (4, ), "dtype": "int32"})
 
-# systems
-class RenderSystem(TickSystem):
-    def on_tick(self, world: World): # must override
-        query_result = world.query_and((HasPosition, HasColor)) # contiguous-like view of all entities matching
+# systems: Note they are a convention!
+class RenderSystem:
+    def __call__(self, world: World):
+        query_result = world.query(HasPosition, HasColor, exclude=[]) # contiguous-like view of all entities matching
         for position, color in zip(query_result.position, query_result.color): # draw each entity
             DrawEntity(position, color)
 
-class MotionSystem(TickSystem)
-    def on_tick(self, world: World): # must override
-        qr = world.query_and((HasPosition, HasVelocity))
+class MotionSystem:
+    def __call__(self, world: World):
+        qr = world.query(HasPosition, HasVelocity) # 'exclude' is optional
         qr.position[:] = qr.position + qr.velocity * DT # writes back to all the underlying pools using numpy's rules
         # Alternative for per-pool update. Less ergonomic, but maybe faster in extreme cases as it avoids the _Field obj
         for pool in qr.pool_list:
             pool.position[:] = pool.position + pool.velocity * DT
 
 def main():
-    render_system = RenderSystem()
-    update_systems: list[TickSystem] = [MotionSystem()]
+    render_system: list[Callable] = RenderSystem()
+    update_systems: list[Callable] = [MotionSystem()]
 
-    world = World(components=[HasPosition, HasColor, HasVelocity])
+    world = World(components=[HasPosition, HasColor, HasVelocity], extra_field_metadata=None)
     for _ in range(n_objects):
         # NOTE: world.{add/remove}_{entity/component} are lazy. They take effect after the first world.update() call.
         world.add_entity(components=(HasPosition, HasVelocity, HasColor), # tuple of components (types)
@@ -66,11 +67,11 @@ def main():
     while not rl.WindowShouldClose():
         world.update() # must be called at each tick so the lazy methods are processed and entities are updated
         # update stuff...
-        _ = [system.on_tick(world=world) for system in update_systems]
+        _ = [system(world=world) for system in update_systems]
         # draw stuff, e.g. using raylib
         rl.BeginDrawing()
         rl.ClearBackground(rl.RAYWHITE)
         rl.DrawFPS(rl.GetScreenWidth() - 100, 0)
-        render_system.on_tick(world=world)
+        render_system(world=world)
         rl.EndDrawing()
 ```

{microecs-0.2.3 → microecs-0.3.0}/microecs/__init__.py

@@ -4,6 +4,5 @@ from .component import Component
 from .pool import Pool
 from .query_result import QueryResult
 from .world import World
-from .system import TickSystem
 
-__all__ = ["Component", "Pool", "QueryResult", "World", "TickSystem"]
+__all__ = ["Component", "Pool", "QueryResult", "World"]

{microecs-0.2.3 → microecs-0.3.0}/microecs/world.py

@@ -9,8 +9,14 @@ from .component import ComponentType
 from .query_result import QueryResult
 
 class World:
-    """Generic container for pools of components. Newly added components are assigned a unique id and go in a pool"""
-    def __init__(self, components: list[ComponentType]):
+    """
+    Generic container for pools of components. Newly added components are assigned a unique id and go in a pool
+    Parameters
+    - components The list of components that the world accepts
+    - extra_field_metadata The list of required extra metadata for each field besides shape and dtype.
+    """
+    def __init__(self, components: list[ComponentType], extra_field_metadata: list[str] | None = None):
+        self.extra_field_metadata = extra_field_metadata or []
         self._check_components(components)
         self.pools: dict[PoolKey, Pool] = {}
         self.pool_to_components: dict[Pool, list[ComponentType]] = {}
@@ -30,7 +36,7 @@ class World:
         self._live_ids: set[EntityId] = set() # 'eager' mode ids so e.g. calling remove_entity twice before update fails
         # command buffer management. {add/remove}_{entity/component} are lazy. Taken into account after update().
         self._command_buffer: list[Callable] = []
-        self._cache: dict[PoolKey, QueryResult] = {}
+        self._cache: dict[tuple[PoolKey, PoolKey], QueryResult] = {} # include+exclude key
         logger.debug(f"Created scene with components: {self.component_names}")
 
     # public api
@@ -79,20 +85,34 @@ class World:
         assert component in self.component_types, f"Component '{component}' not in {self.component_types}"
         self._command_buffer.append(partial(self._do_remove_component, entity_id=entity_id, component=component))
 
-    def query_and(self, component_types: list[ComponentType]) -> QueryResult:
-        """returns A QueryResult object with the entities that have all the requested components (entity ids too)."""
+    def query(self, *include: ComponentType, exclude: list[ComponentType] | None = None) -> QueryResult:
+        """
+        Queries the world for entities that match the include set of components.
+        Syntax: `world.query(A, B, exclude=[C, D])` is, in logic form, a chain of 'ands': `A & B & ~C & ~D`.
+        Return: A `QueryResult` object with the entities that have all the requested components. Has `EntityIds` too.
+        """
+
         # Note: we can cache the queries. The only time it can get invalidated (via public API) is at update().
-        if (key := self._make_key(component_types)) in self._cache:
+        include_key = self._make_key(include)
+        exclude_key = self._make_key(exclude or [])
+        if (key := (include_key, exclude_key)) in self._cache:
             return self._cache[key]
 
+        # archetype_key = (1 0 0 1 1) &
+        #           key = (1 0 0 0 1)
+        #              -> (1 0 0 0 1) OK
+        # but
+        # archetype_key = (1 0 0 1 1) &
+        #           key = (1 0 1 0 0)
+        #              -> (1 0 0 0 0) NOT OK
         res = []
         for archetype_key, archetype_pool in self.pools.items():
-            if (archetype_key & key) == key: # key is subset of archetype_key
+            if (archetype_key & include_key) == include_key and (archetype_key & exclude_key) == 0:
                 res.append(archetype_pool)
 
-        field_names  = sum([self.component_to_field_names[c] for c in component_types], [])
-        field_shapes = dict(zip(field_names, sum([self.component_to_shapes[c] for c in component_types], [])))
-        field_dtypes = dict(zip(field_names, sum([self.component_to_dtypes[c] for c in component_types], [])))
+        field_names = sum([self.component_to_field_names[c] for c in include], [])
+        field_shapes = dict(zip(field_names, sum([self.component_to_shapes[c] for c in include], [])))
+        field_dtypes = dict(zip(field_names, sum([self.component_to_dtypes[c] for c in include], [])))
         entity_ids = np.array(sum((self._pool_ids[p] for p in res), []), dtype="int64")
 
         self._cache[key] = QueryResult(res, field_shapes=field_shapes, field_dtypes=field_dtypes, entity_ids=entity_ids)
@@ -178,7 +198,7 @@ class World:
             hints = get_type_hints(component) # make it work with from __future__ import annotations
             for field_name, _field in component.__dataclass_fields__.items():
                 assert hints[field_name] is np.ndarray, f"Field '{field_name}' of '{component=}' not an array: {_field}"
-                assert _field.metadata.keys() == {"shape", "dtype"}, _field.metadata
+                assert _field.metadata.keys() == {"shape", "dtype", *self.extra_field_metadata}, _field.metadata
                 assert isinstance(_field.metadata["shape"], tuple), _field.metadata["shape"]
                 assert isinstance(fmd := _field.metadata["dtype"], str) and fmd in _dtypes, f"{fmd} not in {_dtypes}"
                 assert field_name not in _query_result_reserved_names, f"Field '{field_name}' in {_qres}"

{microecs-0.2.3 → microecs-0.3.0}/microecs.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: microecs
-Version: 0.2.3
+Version: 0.3.0
 Summary: MicroECS: Minimal Entity Component System (ECS) in python and numpy
 Home-page: https://gitlab.com/meehai/microecs
 License: MIT
@@ -20,54 +20,55 @@ Usage:
 - Sandbox: `python main.py`
 - Tests: `pytest test/`
 
-There are only 5 primitives (bottom up): `Component`, `Pool`, `QueryResult`, `World` and `System`.
+There are only 4 primitives (bottom up): `Component`, `Pool`, `QueryResult`, `World`:
 
-- `Component` is a simple python dataclass holding only data. All entries must be numpy arrays with metadata fields: shape and dtype. We support 5 dtypes only: `int32`, `float32`, `bool`, `str` and `object`.
+- `Component` is a simple python dataclass holding only data. All entries must be numpy arrays with metadata fields: shape and dtype. We support 5 dtypes only: `int32`, `float32`, `bool`, `str` and `object`. A component with no fields is a valid **tag** for querying (e.g. `class Frozen(Component): pass`).
 - `Pool` is a simple 'archetype' dynamic array, holding entities of the same type (same set of components). Usses `Components` metadata to construct contiguous arrays for all entities of the same type.
 - `QueryResult` is a list of pools that match some query on all the entities of the `World`. It acts as a contiguous numpy-like container that implements numpy's `__array_function__` and `__array_ufunc__`. For all intents and purposes it should feel like a `(N, ...)` view over all the entities. If you need a numpy array (not all ops are supported, for e.g. indexing on the first axis), use `QueryResult.numpy()`. It also exposes `entity_ids`: a flat `(N,)` array of the matched entities' ids, in the same pool-by-pool order as the fields, so you can `zip(qr.entity_ids, qr.position)` or feed an id back to `world.get_entity` / `world.remove_entity`.
-- `World` is a manager of `Pools` and has an overview of all the entities in the scene. It also manages the migration of entities from one pool to the other.
-- `System` is an abstract class that queries the `World` for a subset of `Pools` matching some components. It updates the entities in these pools given some logic (e.g. collisions, motion physics or simply calls the drawing functions). They are merely a convention, not tied to `World` per se.
+- `World` is a manager of `Pools` and has an overview of all the entities in the scene. It also manages the migration of entities from one pool to the other. A `World` can also require extra metadata keys on every field via `World(extra_field_metadata=["serializable"])`, to enforce component-level behavior such as field serialization.
 
 Few relevant concepts:
 
 - `Pool` operates on array indices, while `World` operates on entity IDs (also integers). This allows seamless movement between pools while the high-level systems still working as intended.
 - All mutable operations on `World` are lazy. These are: `add_entity`, `remove_entity`, `add_component`, `remove_component`. They are added to a command buffer which is only executed when calling `world.update()`.
+- `Systems` are a convention, they are not part of this library. They can be defined at application level and act as hooks or callbacks. The `World` object doesn't need to know more than entities and components.
 
 Super simplified main loop structure:
 
 ```python
+from typing import Callable
 import numpy as np
 import raylib as rl
-from microecs import World, Component, TickSystem
+from microecs import World, Component
 
 # components
 class HasPosition(Component):
-    position: np.ndarray = field(metadata={"shape": (2, ), "dtype": "float32"})
+    position: np.ndarray = field(metadata={"shape": (2, ), "dtype": "float32"}) # 'shape' + 'dtype' are always required
 class HasVelocity(Component):
     velocity: np.ndarray = field(metadata={"shape": (2, ), "dtype": "float32"})
 class HasColor(Component):
     color: np.ndarray = field(metadata={"shape": (4, ), "dtype": "int32"})
 
-# systems
-class RenderSystem(TickSystem):
-    def on_tick(self, world: World): # must override
-        query_result = world.query_and((HasPosition, HasColor)) # contiguous-like view of all entities matching
+# systems: Note they are a convention!
+class RenderSystem:
+    def __call__(self, world: World):
+        query_result = world.query(HasPosition, HasColor, exclude=[]) # contiguous-like view of all entities matching
         for position, color in zip(query_result.position, query_result.color): # draw each entity
             DrawEntity(position, color)
 
-class MotionSystem(TickSystem)
-    def on_tick(self, world: World): # must override
-        qr = world.query_and((HasPosition, HasVelocity))
+class MotionSystem:
+    def __call__(self, world: World):
+        qr = world.query(HasPosition, HasVelocity) # 'exclude' is optional
         qr.position[:] = qr.position + qr.velocity * DT # writes back to all the underlying pools using numpy's rules
         # Alternative for per-pool update. Less ergonomic, but maybe faster in extreme cases as it avoids the _Field obj
         for pool in qr.pool_list:
             pool.position[:] = pool.position + pool.velocity * DT
 
 def main():
-    render_system = RenderSystem()
-    update_systems: list[TickSystem] = [MotionSystem()]
+    render_system: list[Callable] = RenderSystem()
+    update_systems: list[Callable] = [MotionSystem()]
 
-    world = World(components=[HasPosition, HasColor, HasVelocity])
+    world = World(components=[HasPosition, HasColor, HasVelocity], extra_field_metadata=None)
     for _ in range(n_objects):
         # NOTE: world.{add/remove}_{entity/component} are lazy. They take effect after the first world.update() call.
         world.add_entity(components=(HasPosition, HasVelocity, HasColor), # tuple of components (types)
@@ -78,11 +79,11 @@ def main():
     while not rl.WindowShouldClose():
         world.update() # must be called at each tick so the lazy methods are processed and entities are updated
         # update stuff...
-        _ = [system.on_tick(world=world) for system in update_systems]
+        _ = [system(world=world) for system in update_systems]
         # draw stuff, e.g. using raylib
         rl.BeginDrawing()
         rl.ClearBackground(rl.RAYWHITE)
         rl.DrawFPS(rl.GetScreenWidth() - 100, 0)
-        render_system.on_tick(world=world)
+        render_system(world=world)
         rl.EndDrawing()
 ```

{microecs-0.2.3 → microecs-0.3.0}/microecs.egg-info/SOURCES.txt

@@ -5,7 +5,6 @@ microecs/__init__.py
 microecs/component.py
 microecs/pool.py
 microecs/query_result.py
-microecs/system.py
 microecs/utils.py
 microecs/world.py
 microecs.egg-info/PKG-INFO

{microecs-0.2.3 → microecs-0.3.0}/setup.py

@@ -3,7 +3,7 @@ from pathlib import Path
 from setuptools import setup, find_packages
 
 NAME = "microecs"
-VERSION = "0.2.3"
+VERSION = "0.3.0"
 DESCRIPTION = "MicroECS: Minimal Entity Component System (ECS) in python and numpy"
 URL = "https://gitlab.com/meehai/microecs"
 

microecs-0.2.3/microecs/system.py

@@ -1,10 +0,0 @@
-"""systems.py - Interfaces for various types of systems in ECS"""
-from abc import ABC, abstractmethod
-
-from .world import World
-
-class TickSystem(ABC):
-    """Generic tick-level system. Called inside the hot main engine loop on every tick"""
-    @abstractmethod
-    def on_tick(self, world: World):
-        """callback called on each tick"""