tinyecs 0.3.4__tar.gz → 0.3.6__tar.gz

tinyecs-0.3.6/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: tinyecs
+Version: 0.3.6
+Summary: The teeniest, tiniest ECS system
+Author-email: Michael Lamertz <michael.lamertz@gmail.com>
+License-Expression: MIT
+Project-URL: homepage, https://github.com/dickerdackel/tinyecs
+Project-URL: bugtracker, https://github.com/DickerDackel/tinyecs/issues
+Project-URL: docs, https://tinyecs.readthedocs.io/
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Libraries :: pygame
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: pgcooldown
+Dynamic: license-file
+
+Introduction
+############
+
+ECS stands for Entity Component System, and it is a programming paradigm that
+differs from the well known OO.
+
+During my research I stumbled over `this article`_ and after reading part 2 and
+3, I decided to implement an ECS myself, well aware that `esper` is a solid
+and long existing implementation, but I wanted to see how to implement it
+myself.
+
+.. _this article: https://web.archive.org/web/20250408195932/https://t-machine.org/index.php/2007/09/03/entity-systems-are-the-future-of-mmog-development-part-1/
+
+
+I'm not trying to sell you an ECS by explaining the problems of multiple
+inheritance in game programming.  There are articles out there that do this in
+much detail.  If you're here, you're already interested in the concept, so
+the tutorial might be a good starting point.  It will create a small demo with
+bouncing sprites using pygame-ce.  But tinyecs is platform agnostic, you can
+use it with whatever library you like.
+
+
+Installation
+============
+
+tinyecs is available on pip and can be installed by::
+
+    pip install tinyecs
+
+The project is maintained and hosted on `github`_, where you also can find the
+wheels for a local install, or install it directly from the cloned repo.
+
+.. _github: https://github.com/dickerdackel/tinyecs
+
+.. code-block::
+
+    git clone https://github.com/dickerdackel/tinyecs
+    cd tinyecs
+    python3 -m venv --prompt tinyecs .venv
+    .venv/bin/activate
+    # or .venv/Scripts/activate.bat on windows
+    pip install .
+
+Documentation
+=============
+
+The project home and main documentation is on `Read the Docs`_.
+
+.. _Read the Docs: https://tinyecs.readthedocs.io/
+
+Support / Contributing
+======================
+
+Issues can be opened on `github issues`_
+
+.. _github issues: https://github.com/dickerdackel/tinyecs/issues
+
+Please respect, that I don't want any contributions done with the assistance
+of AI.  This is a hobby project with focus on the craft of programming.  I
+have experimentally used AI to audit parts of the code and documentation, and
+while it found a lot of typos and 2 actual issues, without exception, the
+provided solutions were often besides the point or plain wrong.
+
+I have no possibility to enforce that request, the simple fact that I ask for
+it should be sufficient.
+
+License
+=======
+
+This software is provided under the MIT license.
+
+See LICENSE file for details.

{tinyecs-0.3.4 → tinyecs-0.3.6}/pyproject.toml

@@ -1,8 +1,8 @@
 [project]
 name = "tinyecs"
 description = "The teeniest, tiniest ECS system"
-version = "0.3.4"
-readme = "README.md"
+version = "0.3.6"
+readme = "README.rst"
 
 authors = [
     { name="Michael Lamertz", email="michael.lamertz@gmail.com" }

{tinyecs-0.3.4 → tinyecs-0.3.6}/src/tinyecs/__init__.py

@@ -282,16 +282,16 @@ def remove_component(eid: EntityID, *cids: ComponentID) -> None:
                 obj.shutdown_()
 
 
-def add_system(fkt: SystemFunction, *cids: ComponentID) -> None:
+def add_system(fn: SystemFunction, *cids: ComponentID) -> None:
     r"""Add a system for the specifiied cids.
 
-    :param fkt: The system function
+    :param fn: The system function
     :param cids: The component ids that are required for this system
     :return: None
 
     The prototype for the function is::
 
-        fkt(delta_time, eid, *comps)
+        fn(delta_time, eid, *comps)
 
     where delta_time is e.g. the miliseconds from a pygame tick.  eid is the id
     of the entity that matches, and \*comps are all requested components for
@@ -304,13 +304,13 @@ def add_system(fkt: SystemFunction, *cids: ComponentID) -> None:
     """
 
     create_archetype(*cids)
-    sidx[fkt] = cids
+    sidx[fn] = cids
 
 
-def remove_system(fkt: SystemFunction) -> None:
+def remove_system(fn: SystemFunction) -> None:
     """Remove the given function from the registry.
 
-    :param fkt: The system function
+    :param fn: The system function
     :return: None
 
     Remove the match for this function from the registry
@@ -319,11 +319,11 @@ def remove_system(fkt: SystemFunction) -> None:
     """
 
     for domain in didx:
-        remove_system_from_domain(domain, fkt)
+        remove_system_from_domain(domain, fn)
 
     # Ignore unregistered systems, since we're removing anyways
     try:
-        del sidx[fkt]
+        del sidx[fn]
     except KeyError:
         pass
 
@@ -519,43 +519,80 @@ def cid_of_comp(eid: EntityID, comp: Component) -> ComponentID:
     raise UnknownComponentError(f'Component {comp} not found in entity {eid}')
 
 
+def _create_call_list(cids: tuple[ComponentID],
+                      has_properties: _OptionalProperties) -> list[tuple[EntityID, Component]]:
+    at = tuple(cids)
+    if at not in archetype:
+        create_archetype(*cids)
+
+    adict = archetype[at]
+    # need to get call_list upfront, since kill_system could modify the dict
+    # Also: not running in the if clause is vastly faster than checking an
+    # empty set.
+    if has_properties:
+        property_filter = set(has_properties)
+        call_list = [(eid, *parms) for eid, parms in adict.items()
+                     if property_filter <= plist[eid]]
+    else:
+        call_list = [(eid, *parms) for eid, parms in adict.items()]
+    return call_list
+
+
 def run_system(dt: float,
-               fkt: SystemFunction,
+               fn: SystemFunction,
                *cids: ComponentID,
                has_properties: _OptionalProperties = None,
                **kwargs: dict[str, Any]) -> _RunSystemResult:
     """Run the system for the matching cids.
 
     :param dt: delta time since the last frame (miliseconds)
-    :param fkt: the actual system function
+    :param fn: the actual system function
     :param cids: the components to run on
     :param has_properties: set of required properties
     :return: A dictionary with entity IDs as key and the function result as value
 
-    The fkt gets the list of all entities that contain the listed
-    components.  The list can further be narrowed down my filtering for given
-    properties.  Then it runs the function for every entity and the requested
-    components, passing dt as heartbeat.
+    For every entity that has all the listed components, ``fn`` is run.  The
+    function prototype of ``fn`` is::
+
+        def callback(dt: float, eid: EntityID, *comps: Component) -> Any
+
+    The list can further be narrowed down my filtering for given properties.
 
     This function is a direct call.  Alternatively, you can use add_system
     combined with run_all_systems or run_domain below.
     """
 
-    at = tuple(cids)
-    if at not in archetype:
-        create_archetype(*cids)
+    call_list = _create_call_list(cids, has_properties)
+    return {eid: fn(dt, eid, *parms, **kwargs) for eid, *parms in call_list}
 
-    adict = archetype[at]
-    # need to get call_list upfront, since kill_system could modify the dict
-    # Also: not running in the if clause is vastly faster than checking an
-    # empty set.
-    if has_properties:
-        property_filter = set(has_properties)
-        call_list = [(eid, *parms) for eid, parms in adict.items()
-                     if property_filter <= plist[eid]]
-    else:
-        call_list = [(eid, *parms) for eid, parms in adict.items()]
-    return {eid: fkt(dt, eid, *parms, **kwargs) for eid, *parms in call_list}
+
+def run_bulk_system(dt: float,
+                    fn: SystemFunction,
+                    *cids: ComponentID,
+                    has_properties: _OptionalProperties = None,
+                    **kwargs: dict[str, Any]) -> Any:
+    """Run the bulk system for all entities with matching cids.
+
+    :param dt: delta time since the last frame (miliseconds)
+    :param fn: the actual system function
+    :param cids: the components to run on
+    :param has_properties: set of required properties
+    :return: A dictionary with entity IDs as key and the function result as value
+
+    The fn is called with a list of entity ID and components tuples of all
+    entities that contain the listed components.  The list can further be
+    narrowed down my filtering for given properties.
+
+    ``fn`` is called given a list of ``(EntityID, (components,...))``. In
+    contrast to ``run_system``, the user is responsible to loop over the list.
+
+    The prototype of ``fn`` is::
+
+        def callback(dt: call_list: list[tuple[EntityID, list[Component]]]) -> Any
+    """
+
+    call_list = _create_call_list(cids, has_properties)
+    return fn(dt, call_list, **kwargs)
 
 
 def run_all_systems(dt: float) -> dict[SystemFunction, _RunSystemResult]:
@@ -568,8 +605,8 @@ def run_all_systems(dt: float) -> dict[SystemFunction, _RunSystemResult]:
     appropriate components.
     """
 
-    return {fkt: run_system(dt, fkt, *comps)
-            for fkt, comps in sidx.items()}
+    return {fn: run_system(dt, fn, *comps)
+            for fn, comps in sidx.items()}
 
 
 def run_domain(dt: float, domain: DomainID) -> dict[SystemFunction, _RunSystemResult]:
@@ -584,14 +621,14 @@ def run_domain(dt: float, domain: DomainID) -> dict[SystemFunction, _RunSystemRe
     if domain not in didx:
         return {}
 
-    return {fkt: run_system(dt, fkt, *sidx[fkt])
-            for fkt in didx[domain]}
+    return {fn: run_system(dt, fn, *sidx[fn])
+            for fn in didx[domain]}
 
 
 def create_archetype(*cids: ComponentID) -> None:
     """Create an archetype from the provided cids.
 
-    :param cids The list of cids that define the archetype.
+    :param cids: The list of cids that define the archetype.
     :return: None
 
     An archetype is a fixed combination of components.  Each time a component
@@ -672,8 +709,8 @@ def remove_from_archetype(eid: EntityID, cid: ComponentID | None = None) -> None
 def comps_of_archetype(*cids: ComponentID, has_properties: _OptionalProperties = None) -> list[_EntityComponentsBundle]:
     """Return the given archetype.
 
-    :param cids The cids that define the archetype.
-    :param has_properties Optional set of required properties
+    :param cids: The cids that define the archetype.
+    :param has_properties: Optional set of required properties
     :return: A list of tuples of (eid, components)
     :raises UnknownArchetypeError: If the given archetype doesn't exist.
 

{tinyecs-0.3.4 → tinyecs-0.3.6}/src/tinyecs/tutorial.py

@@ -204,6 +204,11 @@ ecs.run_system(dt, deadzone_system, 'position', deadzone=WORLD)
 
 So the system is basically the `update(dt)` function in an OO driven game.
 
+If you prefer to loop over the list of entities yourself, instead of your
+system being called for each entity individually, theren is `run_bulk_system`,
+which gets the same arguments as ``run_system``, but will pass the full list
+to the system.
+
 At this point you might get the feeling, that you will have a very large list
 of systems in a big block in your game loop, and that's exactly right.  You
 either hate that, which is fine, so the option is either to go back to an OO

tinyecs-0.3.6/src/tinyecs.egg-info/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: tinyecs
+Version: 0.3.6
+Summary: The teeniest, tiniest ECS system
+Author-email: Michael Lamertz <michael.lamertz@gmail.com>
+License-Expression: MIT
+Project-URL: homepage, https://github.com/dickerdackel/tinyecs
+Project-URL: bugtracker, https://github.com/DickerDackel/tinyecs/issues
+Project-URL: docs, https://tinyecs.readthedocs.io/
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Libraries :: pygame
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: pgcooldown
+Dynamic: license-file
+
+Introduction
+############
+
+ECS stands for Entity Component System, and it is a programming paradigm that
+differs from the well known OO.
+
+During my research I stumbled over `this article`_ and after reading part 2 and
+3, I decided to implement an ECS myself, well aware that `esper` is a solid
+and long existing implementation, but I wanted to see how to implement it
+myself.
+
+.. _this article: https://web.archive.org/web/20250408195932/https://t-machine.org/index.php/2007/09/03/entity-systems-are-the-future-of-mmog-development-part-1/
+
+
+I'm not trying to sell you an ECS by explaining the problems of multiple
+inheritance in game programming.  There are articles out there that do this in
+much detail.  If you're here, you're already interested in the concept, so
+the tutorial might be a good starting point.  It will create a small demo with
+bouncing sprites using pygame-ce.  But tinyecs is platform agnostic, you can
+use it with whatever library you like.
+
+
+Installation
+============
+
+tinyecs is available on pip and can be installed by::
+
+    pip install tinyecs
+
+The project is maintained and hosted on `github`_, where you also can find the
+wheels for a local install, or install it directly from the cloned repo.
+
+.. _github: https://github.com/dickerdackel/tinyecs
+
+.. code-block::
+
+    git clone https://github.com/dickerdackel/tinyecs
+    cd tinyecs
+    python3 -m venv --prompt tinyecs .venv
+    .venv/bin/activate
+    # or .venv/Scripts/activate.bat on windows
+    pip install .
+
+Documentation
+=============
+
+The project home and main documentation is on `Read the Docs`_.
+
+.. _Read the Docs: https://tinyecs.readthedocs.io/
+
+Support / Contributing
+======================
+
+Issues can be opened on `github issues`_
+
+.. _github issues: https://github.com/dickerdackel/tinyecs/issues
+
+Please respect, that I don't want any contributions done with the assistance
+of AI.  This is a hobby project with focus on the craft of programming.  I
+have experimentally used AI to audit parts of the code and documentation, and
+while it found a lot of typos and 2 actual issues, without exception, the
+provided solutions were often besides the point or plain wrong.
+
+I have no possibility to enforce that request, the simple fact that I ask for
+it should be sufficient.
+
+License
+=======
+
+This software is provided under the MIT license.
+
+See LICENSE file for details.

{tinyecs-0.3.4 → tinyecs-0.3.6}/tests/test_tinyecs.py

@@ -175,6 +175,19 @@ def test_run_system():
     assert worked
 
 
+def test_run_bulk_system():
+    ecs.reset()
+    for i in range(10):
+        eid = ecs.create_entity()
+        ecs.add_component(eid, 'number', i)
+
+    def bulk_runner(dt, call_list):
+        assert len(call_list) == 10
+        return sum([i for eid, i in call_list])
+
+    assert ecs.run_bulk_system(0, bulk_runner, 'number') == 45
+
+
 def test_run_all_systems():
     e1, e2 = setup()
     ecs.add_system(move_system, 'pos', 'velocity')

tinyecs-0.3.4/PKG-INFO

@@ -1,17 +0,0 @@
-Metadata-Version: 2.4
-Name: tinyecs
-Version: 0.3.4
-Summary: The teeniest, tiniest ECS system
-Author-email: Michael Lamertz <michael.lamertz@gmail.com>
-License-Expression: MIT
-Project-URL: homepage, https://github.com/dickerdackel/tinyecs
-Project-URL: bugtracker, https://github.com/DickerDackel/tinyecs/issues
-Project-URL: docs, https://tinyecs.readthedocs.io/
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Games/Entertainment
-Classifier: Topic :: Software Development :: Libraries :: pygame
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pgcooldown
-Dynamic: license-file

tinyecs-0.3.4/src/tinyecs.egg-info/PKG-INFO

@@ -1,17 +0,0 @@
-Metadata-Version: 2.4
-Name: tinyecs
-Version: 0.3.4
-Summary: The teeniest, tiniest ECS system
-Author-email: Michael Lamertz <michael.lamertz@gmail.com>
-License-Expression: MIT
-Project-URL: homepage, https://github.com/dickerdackel/tinyecs
-Project-URL: bugtracker, https://github.com/DickerDackel/tinyecs/issues
-Project-URL: docs, https://tinyecs.readthedocs.io/
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Games/Entertainment
-Classifier: Topic :: Software Development :: Libraries :: pygame
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pgcooldown
-Dynamic: license-file