microecs 0.2.2__tar.gz → 0.2.4__tar.gz

{microecs-0.2.2 → microecs-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: microecs
-Version: 0.2.2
+Version: 0.2.4
 Summary: MicroECS: Minimal Entity Component System (ECS) in python and numpy
 Home-page: https://gitlab.com/meehai/microecs
 License: MIT
@@ -20,25 +20,26 @@ 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):
@@ -48,15 +49,15 @@ class HasVelocity(Component):
 class HasColor(Component):
     color: np.ndarray = field(metadata={"shape": (4, ), "dtype": "int32"})
 
-# systems
-class RenderSystem(TickSystem):
-    def on_tick(self, world: World): # must override
+# systems: Note they are a convention!
+class RenderSystem:
+    def __call__(self, world: World): # must override
         query_result = world.query_and((HasPosition, HasColor)) # 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
+class MotionSystem:
+    def __call__(self, world: World): # must override
         qr = world.query_and((HasPosition, HasVelocity))
         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
@@ -64,10 +65,10 @@ class MotionSystem(TickSystem)
             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.2 → microecs-0.2.4}/README.md

@@ -8,25 +8,26 @@ 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):
@@ -36,15 +37,15 @@ class HasVelocity(Component):
 class HasColor(Component):
     color: np.ndarray = field(metadata={"shape": (4, ), "dtype": "int32"})
 
-# systems
-class RenderSystem(TickSystem):
-    def on_tick(self, world: World): # must override
+# systems: Note they are a convention!
+class RenderSystem:
+    def __call__(self, world: World): # must override
         query_result = world.query_and((HasPosition, HasColor)) # 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
+class MotionSystem:
+    def __call__(self, world: World): # must override
         qr = world.query_and((HasPosition, HasVelocity))
         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
@@ -52,10 +53,10 @@ class MotionSystem(TickSystem)
             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.2 → microecs-0.2.4}/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.2 → microecs-0.2.4}/microecs/query_result.py

@@ -70,10 +70,16 @@ class _Field(np.lib.mixins.NDArrayOperatorsMixin):
         for v, chunk in zip(views, np.split(full, np.cumsum(self._lens)[:-1])):
             v[:] = chunk
 
-    # qr.position[:, 0] (or any >1 axis as well as slices not exact indices) is allowed. qr.position[0] is not.
     def __getitem__(self, key):
+        if isinstance(key, (int, np.integer)):       # qr.position[i] -> entity i's row, from its own pool
+            key = range(self.len)[key]               # numpy's exact int-index rule, for free: wraps neg, raises on OOB
+            pool_ix = int(np.searchsorted(self._bounds, key, side="right")) - 1
+            return self.parts[pool_ix][key - self._bounds[pool_ix]]
+
         if not (isinstance(key, tuple) and key and key[0] == slice(None)):
-            raise TypeError("entity-axis indexing crosses pools; use [:, k]. Use .numpy() to get a proper np.ndarray.")
+            raise TypeError("Unsupported indexing. Use .numpy() for a proper array. To set items, use qr.attr[:, k]=xxx"
+                            ". For fancy indexing qr[i, 0:3, k], use qr[i][0:3, k].")
+
         return _Field([part[key] for part in self.parts])
 
     def __iter__(self):

{microecs-0.2.2 → microecs-0.2.4}/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]] = {}
@@ -178,7 +184,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.2 → microecs-0.2.4}/microecs.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: microecs
-Version: 0.2.2
+Version: 0.2.4
 Summary: MicroECS: Minimal Entity Component System (ECS) in python and numpy
 Home-page: https://gitlab.com/meehai/microecs
 License: MIT
@@ -20,25 +20,26 @@ 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):
@@ -48,15 +49,15 @@ class HasVelocity(Component):
 class HasColor(Component):
     color: np.ndarray = field(metadata={"shape": (4, ), "dtype": "int32"})
 
-# systems
-class RenderSystem(TickSystem):
-    def on_tick(self, world: World): # must override
+# systems: Note they are a convention!
+class RenderSystem:
+    def __call__(self, world: World): # must override
         query_result = world.query_and((HasPosition, HasColor)) # 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
+class MotionSystem:
+    def __call__(self, world: World): # must override
         qr = world.query_and((HasPosition, HasVelocity))
         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
@@ -64,10 +65,10 @@ class MotionSystem(TickSystem)
             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.2 → microecs-0.2.4}/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.2 → microecs-0.2.4}/setup.py

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

microecs-0.2.2/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, scene: World):
-        """callback called on each tick"""