pyguara 0.2.0__tar.gz

pyguara-0.2.0/.gitignore

@@ -0,0 +1,181 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be added to the global gitignore or merged into this project gitignore.  For a PyCharm
+#  project, it is recommended to ignore these files.
+.idea/
+
+# UV specific
+.uv/
+
+# Project specific
+*.profile
+*.stats
+*.prof
+
+# Game specific
+saves/
+logs/
+*.log
+
+# Configuration runtime files
+temp/
+screenshots/
+
+# OS specific
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db

pyguara-0.2.0/LICENSE

@@ -0,0 +1,8 @@
+The MIT License (MIT)
+Copyright © 2026 Wedeueis Braz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

pyguara-0.2.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: pyguara
+Version: 0.2.0
+Summary: Python game engine featuring a event and data driven archictecture.
+Author-email: Wedeueis Braz <wedeueisbraz@gmail.com>
+License-File: LICENSE
+Keywords: 2d,action-rpg,data-driven,event-driven,game-engine
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1.7
+Requires-Dist: dataclasses-json>=0.6.0
+Requires-Dist: msgpack>=1.1.2
+Requires-Dist: pillow>=12.1.0
+Requires-Dist: pygame-ce>=2.5.6
+Requires-Dist: pymunk>=7.2.0
+Provides-Extra: benchmark
+Requires-Dist: memory-profiler>=0.61.0; extra == 'benchmark'
+Requires-Dist: py-spy>=0.3.0; extra == 'benchmark'
+Requires-Dist: pytest-benchmark>=4.0.0; extra == 'benchmark'
+Provides-Extra: dev
+Requires-Dist: build>=0.10.0; extra == 'dev'
+Requires-Dist: imgui>=2.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pillow>=11.3.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
+Requires-Dist: pytest-benchmark>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.14.0; extra == 'dev'
+Requires-Dist: syrupy>=4.9.1; extra == 'dev'
+Requires-Dist: tox>=4.0.0; extra == 'dev'
+Requires-Dist: twine>=4.0.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
+Requires-Dist: mkdocs-mermaid2-plugin>=0.6.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
+Requires-Dist: pymdown-extensions>=10.0.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# PyGuara
+
+**PyGuara** is a modern, modular, and high-performance 2D game engine for Python 3.12+. It features a robust Entity-Component-System (ECS) architecture, a native Dependency Injection (DI) container, and a decoupled event-driven design, making it suitable for scalable and maintainable game development.
+
+> **Note:** This project is currently in **Pre-Alpha**. APIs are subject to change.
+
+[![CI](https://github.com/Wedeueis/pyguara/actions/workflows/ci.yml/badge.svg)](https://github.com/Wedeueis/pyguara/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/Wedeueis/pyguara/graph/badge.svg?token=YOUR_CODECOV_TOKEN)](https://codecov.io/gh/Wedeueis/pyguara)
+[![PyPI version](https://badge.fury.io/py/pyguara.svg)](https://badge.fury.io/py/pyguara)
+[![Python versions](https://img.shields.io/pypi/pyversions/pyguara.svg)](https://pypi.org/project/pyguara/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![License](https://img.shields.io/github/license/Wedeueis/pyguara)](https://github.com/Wedeueis/pyguara/blob/main/LICENSE)
+
+## 🚀 Key Features
+
+*   **⚡ Performance-First ECS**:
+    *   Optimized `EntityManager` using **Inverted Indexes** for $O(1)$ component queries.
+    *   Cache-friendly data layout designed to minimize Python overhead.
+*   **💉 Native Dependency Injection**:
+    *   Built-in `DIContainer` supporting **Singleton**, **Transient**, and **Scoped** lifetimes.
+    *   Automatic dependency resolution via Python type hints.
+*   **🎨 Decoupled Rendering Pipeline**:
+    *   Backend-agnostic design (currently supporting `pygame-ce`).
+    *   Support for **Z-sorting**, **Batching**, and efficient draw call management.
+*   **📢 Event-Driven Architecture**:
+    *   Protocol-based event system for loose coupling between subsystems (Input, Physics, AI).
+*   **🤖 Integrated AI & Physics**:
+    *   Built-in Finite State Machines (FSM), Steering Behaviors, and Blackboard patterns.
+    *   Physics integration via `pymunk`.
+
+## 🛠️ Installation
+
+PyGuara requires **Python 3.12** or higher.
+
+### Using `uv` (Recommended)
+
+```bash
+# Clone the repository
+git clone https://github.com/Wedeueis/pyguara
+cd pyguara
+
+# Sync dependencies
+uv sync
+```
+
+### Using `pip`
+
+```bash
+pip install -e .[dev]
+```
+
+## 🎮 Quick Start
+
+To run the default example scene included with the engine:
+
+```bash
+python main.py
+```
+
+### Creating a Basic Scene
+
+Here is a minimal example of how to define a scene using PyGuara's ECS:
+
+```python
+from pyguara.scene.base import Scene
+from pyguara.common.components import Transform
+from pyguara.graphics.components.sprite import Sprite
+from pyguara.common.types import Vector2
+
+class MyGameScene(Scene):
+    def on_enter(self) -> None:
+        print("Welcome to PyGuara!")
+
+        # Create an entity
+        player = self.entity_manager.create_entity("player")
+
+        # Add components
+        player.add_component(Transform(position=Vector2(100, 100)))
+        player.add_component(Sprite(texture_path="assets/player.png"))
+
+    def update(self, dt: float) -> None:
+        # Game logic goes here
+        pass
+```
+
+## 🏗️ Architecture Overview
+
+The codebase is organized to enforce separation of concerns:
+
+*   `pyguara/ecs/`: The core Entity-Component-System implementation.
+*   `pyguara/di/`: The Dependency Injection container.
+*   `pyguara/events/`: The event dispatching system.
+*   `pyguara/graphics/`: Rendering protocols, pipelines, and backends.
+*   `pyguara/physics/`: Physics engine integration (Pymunk).
+*   `pyguara/application/`: Application lifecycle and bootstrapping.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please ensure you adhere to the project's code quality standards.
+
+1.  **Install development dependencies**:
+    ```bash
+    uv sync --extra dev
+    ```
+2.  **Run tests**:
+    ```bash
+    pytest
+    ```
+3.  **Run linters**:
+    ```bash
+    ruff check .
+    mypy pyguara
+    ```
+
+## 📄 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## ✍️ Author
+
+Developed by **Wedeueis Braz**.

pyguara-0.2.0/README.md

@@ -0,0 +1,121 @@
+# PyGuara
+
+**PyGuara** is a modern, modular, and high-performance 2D game engine for Python 3.12+. It features a robust Entity-Component-System (ECS) architecture, a native Dependency Injection (DI) container, and a decoupled event-driven design, making it suitable for scalable and maintainable game development.
+
+> **Note:** This project is currently in **Pre-Alpha**. APIs are subject to change.
+
+[![CI](https://github.com/Wedeueis/pyguara/actions/workflows/ci.yml/badge.svg)](https://github.com/Wedeueis/pyguara/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/Wedeueis/pyguara/graph/badge.svg?token=YOUR_CODECOV_TOKEN)](https://codecov.io/gh/Wedeueis/pyguara)
+[![PyPI version](https://badge.fury.io/py/pyguara.svg)](https://badge.fury.io/py/pyguara)
+[![Python versions](https://img.shields.io/pypi/pyversions/pyguara.svg)](https://pypi.org/project/pyguara/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![License](https://img.shields.io/github/license/Wedeueis/pyguara)](https://github.com/Wedeueis/pyguara/blob/main/LICENSE)
+
+## 🚀 Key Features
+
+*   **⚡ Performance-First ECS**:
+    *   Optimized `EntityManager` using **Inverted Indexes** for $O(1)$ component queries.
+    *   Cache-friendly data layout designed to minimize Python overhead.
+*   **💉 Native Dependency Injection**:
+    *   Built-in `DIContainer` supporting **Singleton**, **Transient**, and **Scoped** lifetimes.
+    *   Automatic dependency resolution via Python type hints.
+*   **🎨 Decoupled Rendering Pipeline**:
+    *   Backend-agnostic design (currently supporting `pygame-ce`).
+    *   Support for **Z-sorting**, **Batching**, and efficient draw call management.
+*   **📢 Event-Driven Architecture**:
+    *   Protocol-based event system for loose coupling between subsystems (Input, Physics, AI).
+*   **🤖 Integrated AI & Physics**:
+    *   Built-in Finite State Machines (FSM), Steering Behaviors, and Blackboard patterns.
+    *   Physics integration via `pymunk`.
+
+## 🛠️ Installation
+
+PyGuara requires **Python 3.12** or higher.
+
+### Using `uv` (Recommended)
+
+```bash
+# Clone the repository
+git clone https://github.com/Wedeueis/pyguara
+cd pyguara
+
+# Sync dependencies
+uv sync
+```
+
+### Using `pip`
+
+```bash
+pip install -e .[dev]
+```
+
+## 🎮 Quick Start
+
+To run the default example scene included with the engine:
+
+```bash
+python main.py
+```
+
+### Creating a Basic Scene
+
+Here is a minimal example of how to define a scene using PyGuara's ECS:
+
+```python
+from pyguara.scene.base import Scene
+from pyguara.common.components import Transform
+from pyguara.graphics.components.sprite import Sprite
+from pyguara.common.types import Vector2
+
+class MyGameScene(Scene):
+    def on_enter(self) -> None:
+        print("Welcome to PyGuara!")
+
+        # Create an entity
+        player = self.entity_manager.create_entity("player")
+
+        # Add components
+        player.add_component(Transform(position=Vector2(100, 100)))
+        player.add_component(Sprite(texture_path="assets/player.png"))
+
+    def update(self, dt: float) -> None:
+        # Game logic goes here
+        pass
+```
+
+## 🏗️ Architecture Overview
+
+The codebase is organized to enforce separation of concerns:
+
+*   `pyguara/ecs/`: The core Entity-Component-System implementation.
+*   `pyguara/di/`: The Dependency Injection container.
+*   `pyguara/events/`: The event dispatching system.
+*   `pyguara/graphics/`: Rendering protocols, pipelines, and backends.
+*   `pyguara/physics/`: Physics engine integration (Pymunk).
+*   `pyguara/application/`: Application lifecycle and bootstrapping.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please ensure you adhere to the project's code quality standards.
+
+1.  **Install development dependencies**:
+    ```bash
+    uv sync --extra dev
+    ```
+2.  **Run tests**:
+    ```bash
+    pytest
+    ```
+3.  **Run linters**:
+    ```bash
+    ruff check .
+    mypy pyguara
+    ```
+
+## 📄 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## ✍️ Author
+
+Developed by **Wedeueis Braz**.

pyguara-0.2.0/pyguara/ai/ai_system.py

@@ -0,0 +1,29 @@
+"""Systems for updating AI logic."""
+
+from pyguara.ai.components import AIComponent
+from pyguara.ecs.manager import EntityManager
+
+
+class AISystem:
+    """Updates AI decision making (FSMs/Trees)."""
+
+    def __init__(self, entity_manager: EntityManager):
+        """Initialize the AI system for all Entities."""
+        self.manager = entity_manager
+
+    def update(self, dt: float) -> None:
+        """Update all AI components."""
+        # Query entities with AI
+        for entity in self.manager.get_entities_with(AIComponent):
+            ai: AIComponent = entity.ai_component  # Using __getattr__ magic
+
+            if not ai.enabled:
+                continue
+
+            # Update FSM if present
+            if ai.fsm:
+                ai.fsm.update(dt)
+
+            # (Future) Update Behavior Tree if present
+            # if ai.behavior_tree:
+            #     ai.behavior_tree.tick(dt)

pyguara-0.2.0/pyguara/ai/blackboard.py

@@ -0,0 +1,32 @@
+"""Blackboard system for sharing data between AI nodes and states."""
+
+from typing import Any, Dict
+
+
+class Blackboard:
+    """
+    A shared memory container for AI decision making.
+
+    Allows different parts of an AI (e.g., nodes in a Behavior Tree or states
+    in an FSM) to read and write shared data without tight coupling.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the blackboard."""
+        self._data: Dict[str, Any] = {}
+
+    def set(self, key: str, value: Any) -> None:
+        """Set a value in the blackboard."""
+        self._data[key] = value
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Retrieve a value from the blackboard."""
+        return self._data.get(key, default)
+
+    def has(self, key: str) -> bool:
+        """Check if a key exists."""
+        return key in self._data
+
+    def clear(self) -> None:
+        """Clear all data."""
+        self._data.clear()

pyguara-0.2.0/pyguara/ai/components.py

@@ -0,0 +1,76 @@
+"""ECS components for AI."""
+
+from dataclasses import dataclass, field
+from typing import Optional, List
+
+from pyguara.common.types import Vector2
+from pyguara.ai.blackboard import Blackboard
+from pyguara.ai.fsm import StateMachine
+from pyguara.ecs.component import BaseComponent
+
+
+@dataclass
+class AIComponent(BaseComponent):
+    """
+    Component that holds the AI brain (FSM or Behavior Tree).
+
+    Attributes:
+        blackboard: Shared memory for this agent.
+        fsm: Optional Finite State Machine.
+        enabled: Whether AI logic should run.
+    """
+
+    blackboard: Blackboard = field(default_factory=Blackboard)
+    fsm: Optional[StateMachine] = None
+    enabled: bool = True
+
+    def __post_init__(self) -> None:
+        """Call superclass init after initialization."""
+        super().__init__()
+
+
+@dataclass
+class SteeringAgent(BaseComponent):
+    """
+    Component that defines movement capabilities.
+
+    Attributes:
+        max_speed: Maximum movement speed.
+        max_force: Maximum steering force (turn speed/acceleration).
+        mass: Used to calculate acceleration (Force / Mass).
+    """
+
+    max_speed: float = 200.0
+    max_force: float = 500.0
+    mass: float = 1.0
+
+    def __post_init__(self) -> None:
+        """Call superclass init after initialization."""
+        super().__init__()
+
+
+@dataclass
+class Navigator(BaseComponent):
+    """
+    Component that handles pathfollowing.
+
+    Attributes:
+        path: Current list of waypoints.
+        current_index: Which waypoint we are moving toward.
+        reach_threshold: How close to get before switching to next waypoint.
+    """
+
+    path: List[Vector2] = field(default_factory=list)
+    current_index: int = 0
+    reach_threshold: float = 5.0
+
+    def set_path(self, path: List[Vector2]) -> None:
+        """Set the path defined by a list of vectors."""
+        self.path = path
+        self.current_index = 0
+
+    def get_current_target(self) -> Optional[Vector2]:
+        """Return the current imediate destination."""
+        if 0 <= self.current_index < len(self.path):
+            return self.path[self.current_index]
+        return None

pyguara-0.2.0/pyguara/ai/fsm.py

@@ -0,0 +1,82 @@
+"""Finite State Machine (FSM) implementation."""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Optional
+
+from pyguara.ai.blackboard import Blackboard
+from pyguara.ecs.entity import Entity
+
+
+class State(ABC):
+    """Abstract base class for FSM states."""
+
+    def __init__(self, entity: Entity, blackboard: Blackboard):
+        """Initialize the state of an entity and a Blackboard."""
+        self.entity = entity
+        self.blackboard = blackboard
+
+    @abstractmethod
+    def on_enter(self) -> None:
+        """Call when entering this state."""
+        pass
+
+    @abstractmethod
+    def on_exit(self) -> None:
+        """Call when exiting this state."""
+        pass
+
+    @abstractmethod
+    def update(self, dt: float) -> Optional[str]:
+        """
+        Update the state logic.
+
+        Returns:
+            Name of the next state to transition to, or None to stay.
+        """
+        pass
+
+
+class StateMachine:
+    """Manages states and transitions for an entity."""
+
+    def __init__(self, entity: Entity, blackboard: Blackboard):
+        """Initialize the State Machine of an entity and a Blackboard."""
+        self.entity = entity
+        self.blackboard = blackboard
+        self._states: Dict[str, State] = {}
+        self._current_state: Optional[State] = None
+        self._current_state_name: str = ""
+
+    def add_state(self, name: str, state: State) -> None:
+        """Register a state instance."""
+        self._states[name] = state
+
+    def set_initial_state(self, name: str) -> None:
+        """Set the starting state."""
+        if name in self._states:
+            self._current_state = self._states[name]
+            self._current_state_name = name
+            self._current_state.on_enter()
+
+    def update(self, dt: float) -> None:
+        """Update current state and handle transitions."""
+        if not self._current_state:
+            return
+
+        # Update returns potential transition
+        next_state_name = self._current_state.update(dt)
+
+        if next_state_name and next_state_name != self._current_state_name:
+            self._transition_to(next_state_name)
+
+    def _transition_to(self, name: str) -> None:
+        """Execute transition logic."""
+        if name not in self._states:
+            return
+
+        if self._current_state:
+            self._current_state.on_exit()
+
+        self._current_state = self._states[name]
+        self._current_state_name = name
+        self._current_state.on_enter()