pyguara 0.2.0__py3-none-any.whl

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/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/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/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()

pyguara/ai/pathfinding/astar.py

@@ -0,0 +1,58 @@
+"""Generic A* pathfinding algorithm implementation."""
+
+import heapq
+from typing import Dict, List, Optional, Tuple
+
+from pyguara.ai.pathfinding.core import Graph, Heuristic, Node
+
+
+class AStarPathfinder:
+    """Generic A* solver for any graph type."""
+
+    def find_path(
+        self, graph: Graph[Node], start: Node, goal: Node, heuristic: Heuristic[Node]
+    ) -> Optional[List[Node]]:
+        """
+        Calculate the shortest path from start to goal.
+
+        Optimized to reduce heap operations.
+        """
+        frontier: List[Tuple[float, Node]] = []
+        heapq.heappush(frontier, (0, start))
+
+        came_from: Dict[Node, Optional[Node]] = {start: None}
+        cost_so_far: Dict[Node, float] = {start: 0.0}
+
+        while frontier:
+            _, current = heapq.heappop(frontier)
+
+            if current == goal:
+                break
+
+            for next_node in graph.get_neighbors(current):
+                new_cost = cost_so_far[current] + graph.cost(current, next_node)
+
+                if next_node not in cost_so_far or new_cost < cost_so_far[next_node]:
+                    cost_so_far[next_node] = new_cost
+                    priority = new_cost + heuristic.estimate(next_node, goal)
+                    heapq.heappush(frontier, (priority, next_node))
+                    came_from[next_node] = current
+
+        return self._reconstruct_path(came_from, start, goal)
+
+    def _reconstruct_path(
+        self, came_from: Dict[Node, Optional[Node]], start: Node, goal: Node
+    ) -> Optional[List[Node]]:
+        """Rebuild the path from the came_from map."""
+        if goal not in came_from:
+            return None
+
+        current: Optional[Node] = goal
+        path = []
+
+        while current is not None:
+            path.append(current)
+            current = came_from[current]
+
+        path.reverse()
+        return path

pyguara/ai/pathfinding/core.py

@@ -0,0 +1,29 @@
+"""Core abstractions for pathfinding protocols."""
+
+from typing import Protocol, Iterator, TypeVar, Hashable
+
+# Generic type for a Node (invariant for Graphs as they produce and consume)
+Node = TypeVar("Node", bound=Hashable)
+
+# Contravariant type for Heuristics (they only consume nodes)
+NodeContra = TypeVar("NodeContra", bound=Hashable, contravariant=True)
+
+
+class Graph(Protocol[Node]):
+    """Interface for a navigation graph."""
+
+    def get_neighbors(self, node: Node) -> Iterator[Node]:
+        """Yield the neighbors of the given node."""
+        ...
+
+    def cost(self, from_node: Node, to_node: Node) -> float:
+        """Calculate the movement cost between two adjacent nodes."""
+        ...
+
+
+class Heuristic(Protocol[NodeContra]):
+    """Interface for heuristic functions."""
+
+    def estimate(self, current: NodeContra, goal: NodeContra) -> float:
+        """Estimate the remaining cost to the goal (h_score)."""
+        ...

pyguara/ai/pathfinding/grid.py

@@ -0,0 +1,72 @@
+"""Grid-based graph implementation."""
+
+import math
+from typing import Iterator, Set, Tuple
+
+from pyguara.ai.pathfinding.core import Graph, Heuristic
+
+# GridNode is just an (x, y) tuple for efficiency
+GridNode = Tuple[int, int]
+
+
+class GridGraph(Graph[GridNode]):
+    """A 2D grid graph supporting 4 or 8 directional movement."""
+
+    def __init__(self, width: int, height: int, allow_diagonal: bool = True):
+        """Initialize the grid graph."""
+        self.width = width
+        self.height = height
+        self.allow_diagonal = allow_diagonal
+        self.walls: Set[GridNode] = set()
+        self.weights: dict[GridNode, float] = {}  # For terrain costs
+
+    def in_bounds(self, node: GridNode) -> bool:
+        """Check if node is within grid limits."""
+        x, y = node
+        return 0 <= x < self.width and 0 <= y < self.height
+
+    def is_passable(self, node: GridNode) -> bool:
+        """Check if node is not a wall."""
+        return node not in self.walls
+
+    def get_neighbors(self, node: GridNode) -> Iterator[GridNode]:
+        """Yield valid neighbors."""
+        x, y = node
+        # Standard 4 directions
+        dirs = [(1, 0), (0, 1), (-1, 0), (0, -1)]
+
+        if self.allow_diagonal:
+            # Add diagonals
+            dirs.extend([(1, 1), (1, -1), (-1, 1), (-1, -1)])
+
+        for dx, dy in dirs:
+            next_node = (x + dx, y + dy)
+            if self.in_bounds(next_node) and self.is_passable(next_node):
+                yield next_node
+
+    def cost(self, from_node: GridNode, to_node: GridNode) -> float:
+        """Calculate movement cost, 1.0 orthogonal, 1.414 diagonal."""
+        base_cost = self.weights.get(to_node, 1.0)
+
+        # Heuristic check for diagonal movement
+        dx = abs(from_node[0] - to_node[0])
+        dy = abs(from_node[1] - to_node[1])
+
+        multiplier = 1.414 if (dx + dy) == 2 else 1.0
+        return base_cost * multiplier
+
+
+class ManhattanDistance(Heuristic[GridNode]):
+    """Manhattan distance heuristic (better for 4-way movement)."""
+
+    def estimate(self, current: GridNode, goal: GridNode) -> float:
+        """Estimate the Manhattan distance."""
+        return abs(current[0] - goal[0]) + abs(current[1] - goal[1])
+
+
+class EuclideanDistance(Heuristic[GridNode]):
+    """Euclidean distance heuristic (better for 8-way/any angle)."""
+
+    def estimate(self, current: GridNode, goal: GridNode) -> float:
+        """Estimate the Euclidean distance."""
+        return math.hypot(goal[0] - current[0], goal[1] - current[1])

pyguara/ai/steering.py

@@ -0,0 +1,55 @@
+"""Steering behaviors for autonomous movement."""
+
+from typing import cast
+
+from pyguara.common.components import Transform
+from pyguara.common.types import Vector2
+
+
+class SteeringBehavior:
+    """Calculates forces to move an entity in a natural way."""
+
+    @staticmethod
+    def seek(
+        transform: Transform,
+        target: Vector2,
+        max_speed: float,
+        current_velocity: Vector2,
+    ) -> Vector2:
+        """Calculate steering force to move toward a target."""
+        # FIX: Cast the result of vector math to Vector2
+        desired = cast(Vector2, (target - transform.position).normalized() * max_speed)
+        return desired - current_velocity
+
+    @staticmethod
+    def arrive(
+        transform: Transform,
+        target: Vector2,
+        max_speed: float,
+        current_velocity: Vector2,
+        slowing_radius: float = 100.0,
+    ) -> Vector2:
+        """
+        Calculate steering force to arrive at a target and stop.
+
+        Args:
+            transform: Entity transform.
+            target: Target position.
+            max_speed: Max movement speed.
+            current_velocity: Current entity velocity.
+            slowing_radius: Distance at which to start slowing down.
+        """
+        direction = target - transform.position
+        distance = direction.length
+
+        if distance < 0.1:
+            # Stop completely - return inverse of current velocity to cancel it out
+            return -current_velocity
+
+        if distance < slowing_radius:
+            target_speed = max_speed * (distance / slowing_radius)
+        else:
+            target_speed = max_speed
+
+        desired = cast(Vector2, direction.normalized() * target_speed)
+        return desired - current_velocity

pyguara/app_scene.py

@@ -0,0 +1,132 @@
+"""Main application entry point and engine integration."""
+
+import pygame
+
+from pyguara.common.components import Transform
+from pyguara.common.types import Vector2
+from pyguara.ecs.manager import EntityManager
+from pyguara.events.dispatcher import EventDispatcher
+from pyguara.graphics.backends.pygame.ui_renderer import PygameUIRenderer
+from pyguara.graphics.backends.pygame.pygame_renderer import PygameBackend
+from pyguara.graphics.window import Window, WindowConfig
+from pyguara.graphics.backends.pygame.pygame_window import PygameWindow
+from pyguara.input.manager import InputManager
+from pyguara.physics.backends.pymunk_impl import PymunkEngine
+from pyguara.physics.components import RigidBody, Collider
+from pyguara.physics.physics_system import PhysicsSystem
+from pyguara.physics.types import BodyType, ShapeType
+from pyguara.scene.manager import SceneManager
+from pyguara.game.scenes import GameplayScene
+from pyguara.ui.components import Label, Panel
+from pyguara.ui.manager import UIManager
+
+
+class GameEngine:
+    """Core game engine class managing the main loop and subsystems."""
+
+    def __init__(self) -> None:
+        """Initialize the game engine, window, and subsystems."""
+        # 1. Window System
+        window_config = WindowConfig()
+        pygame_window = PygameWindow()
+        self.window = Window(window_config, pygame_window)
+        self.window.create()
+
+        self.clock = pygame.time.Clock()
+
+        # 2. Core Services
+        self.event_dispatcher = EventDispatcher()
+        self.input_manager = InputManager(self.event_dispatcher)
+
+        # 3. Subsystems
+        self.entity_manager = EntityManager()
+
+        self.physics_engine = PymunkEngine()
+        self.physics_system = PhysicsSystem(self.physics_engine, self.event_dispatcher)
+
+        # 4. Rendering & UI
+        self.world_renderer = PygameBackend(self.window.native_handle)
+        self.ui_renderer = PygameUIRenderer(self.window.native_handle)
+        self.ui_manager = UIManager(self.event_dispatcher)
+
+        # 5. Scene Management
+        self.scene_manager = SceneManager()
+
+        # Initialize Scene
+        game_scene = GameplayScene("game", self.event_dispatcher)
+        self.scene_manager.register(game_scene)
+        self.scene_manager.switch_to("game")
+
+        # Setup Test Entities (Fallback if scene not used)
+        self._setup_world()
+        self._setup_ui()
+
+    def _setup_world(self) -> None:
+        """Create initial game entities (Test)."""
+        player = self.entity_manager.create_entity("player_test")
+        player.add_component(Transform(position=Vector2(100, 100)))
+        player.add_component(RigidBody(body_type=BodyType.DYNAMIC, mass=1.0))
+        # Fixed dimensions
+        player.add_component(Collider(shape_type=ShapeType.BOX, dimensions=[32, 32]))
+
+        floor = self.entity_manager.create_entity("floor_test")
+        floor.add_component(Transform(position=Vector2(640, 600)))
+        floor.add_component(RigidBody(body_type=BodyType.STATIC))
+        floor.add_component(Collider(shape_type=ShapeType.BOX, dimensions=[1280, 50]))
+
+    def _setup_ui(self) -> None:
+        """Configure the initial UI layout (Test)."""
+        panel = Panel(position=Vector2(10, 200), size=Vector2(200, 50))
+        self.ui_manager.add_element(panel)
+
+        self.fps_label = Label("Engine FPS: 0", position=Vector2(10, 10))
+        panel.add_child(self.fps_label)
+
+    def run(self) -> None:
+        """Start the main game loop."""
+        while self.window.is_open:
+            dt = self.clock.tick(60) / 1000.0
+
+            # 1. Process Input
+            for event in self.window.poll_events():
+                self.input_manager.process_event(event)
+
+            # 2. Update Logic
+            self.update(dt)
+
+            # 3. Render
+            self.render()
+
+        self.window.close()
+
+    def update(self, dt: float) -> None:
+        """Update game state."""
+        # Update Global UI
+        self.ui_manager.update(dt)
+        self.fps_label.set_text(f"Engine FPS: {self.clock.get_fps():.0f}")
+
+        # Update Global Physics (Test entities)
+        physics_entities = list(
+            self.entity_manager.get_entities_with(Transform, RigidBody)
+        )
+        self.physics_system.update(physics_entities, dt)
+
+        # Update Scenes
+        self.scene_manager.update(dt)
+
+    def render(self) -> None:
+        """Render the current frame."""
+        # self.window.clear(Color(30, 30, 30))
+
+        # Render Scene
+        self.scene_manager.render(self.world_renderer, self.ui_renderer)
+
+        # Render Global UI
+        self.ui_manager.render(self.ui_renderer)
+
+        self.window.present()
+
+
+if __name__ == "__main__":
+    app = GameEngine()
+    app.run()

pyguara/application/__init__.py

@@ -0,0 +1,6 @@
+"""Application domain."""
+
+from pyguara.application.application import Application
+from pyguara.application.bootstrap import create_application, create_sandbox_application
+
+__all__ = ["Application", "create_application", "create_sandbox_application"]

pyguara/application/application.py

@@ -0,0 +1,100 @@
+"""Main application runtime."""
+
+import pygame
+
+from pyguara.config.manager import ConfigManager
+from pyguara.di.container import DIContainer
+from pyguara.events.dispatcher import EventDispatcher
+from pyguara.graphics.protocols import UIRenderer, IRenderer
+from pyguara.graphics.window import Window
+from pyguara.input.manager import InputManager
+from pyguara.scene.base import Scene
+from pyguara.scene.manager import SceneManager
+from pyguara.ui.manager import UIManager
+
+
+class Application:
+    """The main runtime loop coordinator."""
+
+    def __init__(self, container: DIContainer) -> None:
+        """Initialize Application with a DI container."""
+        self._container = container
+        self._is_running = False
+
+        # Resolve Core Dependencies
+        self._window = container.get(Window)
+        self._event_dispatcher = container.get(EventDispatcher)
+        self._input_manager = container.get(InputManager)
+        self._scene_manager = container.get(SceneManager)
+        self._config_manager = container.get(ConfigManager)
+        self._ui_manager = container.get(UIManager)
+
+        # Retrieve Renderer
+        self._world_renderer = container.get(IRenderer)  # type: ignore[type-abstract]
+        self._ui_renderer = container.get(UIRenderer)  # type: ignore[type-abstract]
+
+        self._scene_manager.set_container(container)
+
+        self._clock = pygame.time.Clock()
+
+    def run(self, starting_scene: Scene) -> None:
+        """Execute the main game loop."""
+        print(f"[Application] Starting with scene: {starting_scene.name}")
+
+        self._scene_manager.register(starting_scene)
+        self._scene_manager.switch_to(starting_scene.name)
+
+        self._is_running = True
+        target_fps = self._config_manager.config.display.fps_target
+
+        # Force an initial event pump to show the window immediately
+        pygame.event.pump()
+
+        while self._is_running and self._window.is_open:
+            # 1. Time
+            dt = self._clock.tick(target_fps) / 1000.0
+
+            # 2. Input
+            self._process_input()
+
+            # 3. Update
+            self._update(dt)
+
+            # 4. Render
+            self._render()
+
+        self.shutdown()
+
+    def _process_input(self) -> None:
+        """Poll system events."""
+        # This call is CRITICAL. It keeps the OS window responsive.
+        for event in self._window.poll_events():
+            if hasattr(event, "type") and event.type == pygame.QUIT:
+                self._is_running = False
+
+            # Dispatch to input manager
+            self._input_manager.process_event(event)
+
+    def _update(self, dt: float) -> None:
+        """Update game logic."""
+        # 1. Process background thread events (CRITICAL FIX)
+        # We call the dispatcher to flush any pending queued events
+        self._event_dispatcher.process_queue()
+
+        # 2. Update UI
+        self._ui_manager.update(dt)
+
+        # 3. Update Scene (Physics, Logic)
+        self._scene_manager.update(dt)
+
+    def _render(self) -> None:
+        """Render frame."""
+        self._window.clear()
+        self._scene_manager.render(self._world_renderer, self._ui_renderer)
+        self._ui_manager.render(self._ui_renderer)
+        self._window.present()
+
+    def shutdown(self) -> None:
+        """Close Application."""
+        print("[Application] Shutting down...")
+        self._window.close()