1.3.0 Release

Author: Jonathan Crum

pecs_framework/component.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 from beartype.typing import TypeVar
+from beartype.typing import TypedDict
+from beartype.typing import Any
 
 from pecs_framework._types import Bases, Namespace
 from pecs_framework.events import EntityEvent

pecs_framework/domain.py

@@ -1,22 +1,36 @@
 from __future__ import annotations
 from beartype.typing import TYPE_CHECKING
 from beartype.typing import Any
+from beartype.typing import TypedDict
 
 from uuid import uuid1
 from collections import OrderedDict
+import json
 
 if TYPE_CHECKING:
+    from pecs_framework.component import Component
     from pecs_framework.engine import Engine
-    from pecs_framework.query import ComponentQuery
     from pecs_framework.prefab import EntityTemplate
+    from pecs_framework.query import ComponentQuery
 
-from pecs_framework.entities import Entity
+from pathlib import Path
+from pecs_framework.entity import Entity
 from pecs_framework.query import Query
 from rich.console import Console
 
 
 console = Console()
 
+class ComponentDict(TypedDict):
+    comp_id: str
+    cbit: int
+    data: dict[str, Any]
+
+
+class EntityDict(TypedDict):
+    alias: str | None
+    components: list[ComponentDict]
+
 
 class EntityRegistry:
 
@@ -171,6 +185,9 @@ def create_uid() -> str:
 
     def __init__(self, engine: Engine) -> None:
         self.engine = engine
+        self.reset()
+
+    def reset(self) -> None:
         self.entities = EntityRegistry(self)
         self.queries: list[Query] = []
 
@@ -202,3 +219,70 @@ def create_query(
     def candidate(self, entity: Entity) -> None:
         for query in self.queries:
             query.candidate(entity)
+
+    def save(self, directory: Path, filename: str) -> None:
+        output: dict[str, EntityDict] = {}
+
+        for entity in self.entities:
+            output[entity.eid] = {
+                "alias": self.entities.get_alias_for_entity(entity.eid),
+                "components": [],
+            }
+
+            for component in entity.components.values():
+                component_data = serialize_component(component)
+                output[entity.eid]["components"].append(component_data)
+
+        write_to_file(directory, filename, output)
+
+    def load(self, directory: Path, filename: str) -> None:
+        if loaded_data := load_from_file(directory, filename):
+            for eid, entity_data in loaded_data.items():
+                alias = entity_data["alias"]
+                component_data = entity_data["components"]
+
+                entity = self.entities.create(alias=alias, entity_id=eid)
+
+                for component_datum in component_data:
+                    self.engine.components.attach(
+                        entity,
+                        component_datum["comp_id"],
+                        {k: v for k, v in component_datum["data"].items()},
+                    )
+
+
+def write_to_file(
+    directory: Path,
+    filename: str,
+    data_dict: dict[str, EntityDict],
+) -> None:
+    if not filename.endswith(".json"):
+        filename = filename + ".json"
+    with open(Path(directory, filename), "+w") as file:
+        file.write(json.dumps(data_dict, indent=4))
+
+
+def load_from_file(directory: Path, filename: str) -> dict[str, EntityDict]:
+    if not (filename.endswith(".json")):
+        filename = filename + ".json"
+    with open(Path(directory, filename), "+r") as file:
+        return json.loads(file.read())
+
+
+def serialize_component(component: Component) -> ComponentDict:
+    """
+    Serialization should provide all of the necessary information needed to
+    rebuild what is set up in `setup_ecs` anew, with the state that the
+    components were in when they were serialized.
+    """
+    comp_id = component.__class__.comp_id
+    cbit = component.__class__.cbit
+    instance_data = vars(component)
+
+    del instance_data["_entity_id"]
+
+    return {
+        "comp_id": comp_id,
+        "cbit": cbit,
+        "data": instance_data,
+    }

pecs_framework/engine.py

@@ -11,11 +11,11 @@
 
 from pecs_framework.component import ComponentMeta, Component
 from pecs_framework.domain import Domain, EntityRegistry
-from pecs_framework.entities import add_component
-from pecs_framework.entities import add_component_type
-from pecs_framework.entities import Entity
-from pecs_framework.entities import has_component
-from pecs_framework.entities import remove_component
+from pecs_framework.entity import add_component
+from pecs_framework.entity import add_component_type
+from pecs_framework.entity import Entity
+from pecs_framework.entity import has_component
+from pecs_framework.entity import remove_component
 from pecs_framework.prefab import PrefabBuilder
 
 

pecs_framework/entities/__init__.py

@@ -1,15 +1,17 @@
 from __future__ import annotations
+from beartype import beartype
 from beartype.typing import TYPE_CHECKING
 from beartype.typing import Any
 from beartype.typing import cast
+from collections import OrderedDict
 
 if TYPE_CHECKING:
     from pecs_framework._types import CompId
     from pecs_framework.domain import Domain
     from .entity import Entity
 
 import json
-
+from pecs_framework.events import EventData, EntityEvent
 from pecs_framework.utils import has_bit
 from pecs_framework.utils import subtract_bit
 from pecs_framework.utils import add_bit
@@ -18,6 +20,97 @@
 from pecs_framework.component import CT
 
 
+class Entity:
+
+    @beartype
+    def __init__(self, domain, entity_id: str = '') -> None:
+        self.domain = domain
+        self.eid = entity_id
+        self.cbits: int = 0
+        self.components: OrderedDict[CompId, Component] = OrderedDict()
+        self.qeligible: bool = True
+
+    def __getitem__(self, component: type[CT] | str) -> CT:
+        if isinstance(component, str):
+            _component = self.domain.engine.components.get_type(component)
+        else:
+            _component = component
+        return cast(CT, get_component(self, _component))
+
+    def fire_event(
+        self,
+        event: str,
+        data: dict[str, Any] | EventData | None = None
+    ) -> EntityEvent:
+        """
+        Fire an event to all subscribed components attached to this entity.
+
+        The event name should be a simple, snake-cased string. Subscribed
+        components must implement a handler method that takes in an
+        `EntityEvent` and returns that event.
+
+        ## Example
+
+        ```py
+        @dataclass
+        class Health(Component):
+            '''Representation of an Entity's health.'''
+            maximum: int = 100
+            current: int = field(init=False)
+
+            def __post_init__(self) -> None:
+                self.current = self.maximum
+
+            def on_damage_taken(self, evt: EntityEvent) -> EntityEvent:
+                damage = evt.data.amount
+                self.current -= damage
+                evt.handle()
+                return evt
+        ```
+        """
+        if data and isinstance(data, EventData):
+            data = data.record
+        elif data and isinstance(data, dict):
+            data = EventData(**data).record
+        else:
+            data = {}
+        evt = EntityEvent(event, data)
+
+        for component in self.components.values():
+            component.handle_event(evt)
+            if evt.prevented:
+                return evt
+        return evt
+
+    def on_component_added(self):
+        pass
+
+    def on_component_removed(self):
+        pass
+
+    def on_entity_destroyed(self):
+        pass
+
+    def _on_component_added(self):
+        candidacy(self.domain, self)
+        self.on_component_added()
+
+    def _on_component_removed(self):
+        candidacy(self.domain, self)
+        self.on_component_removed()
+
+    def _on_entity_destroyed(self):
+        to_delete = []
+        for component in self.components.values():
+            to_delete.append(component)
+
+        for component in to_delete:
+            self.components[component.comp_id]._entity_id = ''
+            del self.components[component.comp_id]
+
+        self.on_entity_destroyed()
+
+
 def add_component_type(
     entity: Entity,
     component: ComponentMeta,