trianglengin 2.0.1__cp312-cp312-macosx_11_0_arm64.whl

trianglengin/ui/app.py

@@ -0,0 +1,107 @@
+# File: src/trianglengin/ui/app.py
+import logging
+
+# UI imports are now direct as dependencies are required
+import pygame
+
+# Use absolute imports from core engine
+from trianglengin.config import EnvConfig
+from trianglengin.game_interface import GameState
+from trianglengin.ui import config as ui_config
+from trianglengin.ui import interaction, visualization
+
+logger = logging.getLogger(__name__)
+
+
+class Application:
+    """Main application integrating visualization and interaction for trianglengin."""
+
+    def __init__(self, mode: str = "play") -> None:
+        self.display_config = ui_config.DisplayConfig()  # Use UI config
+        self.env_config = EnvConfig()  # Use core EnvConfig
+        self.mode = mode
+
+        pygame.init()
+        pygame.font.init()
+        self.screen = self._setup_screen()
+        self.clock = pygame.time.Clock()
+        self.fonts = visualization.load_fonts()  # From ui.visualization
+
+        if self.mode in ["play", "debug"]:
+            # GameState comes from the core engine
+            self.game_state = GameState(self.env_config)
+            # Visualizer and InputHandler come from the UI package
+            self.visualizer = visualization.Visualizer(
+                self.screen,
+                self.display_config,
+                self.env_config,
+                self.fonts,
+            )
+            self.input_handler = interaction.InputHandler(
+                self.game_state, self.visualizer, self.mode, self.env_config
+            )
+        else:
+            logger.error(f"Unsupported application mode: {self.mode}")
+            raise ValueError(f"Unsupported application mode: {self.mode}")
+
+        self.running = True
+
+    def _setup_screen(self) -> pygame.Surface:
+        """Initializes the Pygame screen."""
+        screen = pygame.display.set_mode(
+            (
+                self.display_config.SCREEN_WIDTH,
+                self.display_config.SCREEN_HEIGHT,
+            ),
+            pygame.RESIZABLE,
+        )
+        pygame.display.set_caption(f"Triangle Engine - {self.mode.capitalize()} Mode")
+        return screen
+
+    def run(self) -> None:
+        """Main application loop."""
+        logger.info(f"Starting application in {self.mode} mode.")
+        while self.running:
+            self.clock.tick(self.display_config.FPS)
+
+            if self.input_handler:
+                self.running = self.input_handler.handle_input()
+                if not self.running:
+                    break
+            else:
+                # Basic event handling if input_handler fails (shouldn't happen)
+                for event in pygame.event.get():
+                    if event.type == pygame.QUIT:
+                        self.running = False
+                    if event.type == pygame.KEYDOWN and event.key == pygame.K_ESCAPE:
+                        self.running = False
+                    if event.type == pygame.VIDEORESIZE and self.visualizer:
+                        try:
+                            w, h = max(320, event.w), max(240, event.h)
+                            self.visualizer.screen = pygame.display.set_mode(
+                                (w, h), pygame.RESIZABLE
+                            )
+                            self.visualizer.layout_rects = None
+                        except pygame.error as e:
+                            logger.error(f"Error resizing window: {e}")
+                if not self.running:
+                    break
+
+            if (
+                self.mode in ["play", "debug"]
+                and self.visualizer
+                and self.game_state
+                and self.input_handler
+            ):
+                interaction_render_state = (
+                    self.input_handler.get_render_interaction_state()
+                )
+                self.visualizer.render(
+                    self.game_state,
+                    self.mode,
+                    **interaction_render_state,
+                )
+                pygame.display.flip()
+
+        logger.info("Application loop finished.")
+        pygame.quit()

trianglengin/ui/cli.py

@@ -0,0 +1,123 @@
+# File: src/trianglengin/ui/cli.py
+import logging
+import random
+import sys
+from typing import Annotated
+
+import numpy as np
+import typer  # Now a required dependency
+
+# Use absolute imports from core engine
+from trianglengin.config import EnvConfig
+
+# Import Application directly
+from trianglengin.ui.app import Application
+
+app = typer.Typer(
+    name="trianglengin",
+    help="Core Triangle Engine - Interactive Modes.",
+    add_completion=False,
+)
+
+LogLevelOption = Annotated[
+    str,
+    typer.Option(
+        "--log-level",
+        "-l",
+        help="Set the logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL).",
+        case_sensitive=False,
+    ),
+]
+
+SeedOption = Annotated[
+    int,
+    typer.Option(
+        "--seed",
+        "-s",
+        help="Random seed for C++ engine initialization.",
+    ),
+]
+
+
+def setup_logging(log_level_str: str) -> None:
+    """Configures root logger based on string level."""
+    log_level_str = log_level_str.upper()
+    log_level_map = {
+        "DEBUG": logging.DEBUG,
+        "INFO": logging.INFO,
+        "WARNING": logging.WARNING,
+        "ERROR": logging.ERROR,
+        "CRITICAL": logging.CRITICAL,
+    }
+    log_level = log_level_map.get(log_level_str, logging.INFO)
+    logging.basicConfig(
+        level=log_level,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        handlers=[logging.StreamHandler(sys.stdout)],
+        force=True,
+    )
+    # Set pygame log level (pygame is now a required dependency)
+
+    logging.getLogger("pygame").setLevel(logging.WARNING)
+    logging.info(f"Root logger level set to {logging.getLevelName(log_level)}")
+
+
+def run_interactive_mode(mode: str, seed: int, log_level: str) -> None:
+    """Runs the interactive application."""
+    setup_logging(log_level)
+    logger = logging.getLogger(__name__)
+    logger.info(f"Running Triangle Engine in {mode.capitalize()} mode...")
+
+    # --- Seeding ---
+    try:
+        random.seed(seed)
+        # Use modern NumPy seeding
+        np.random.default_rng(seed)
+        logger.info(
+            f"Set Python random seed to {seed}. NumPy RNG initialized. C++ engine seeded separately."
+        )
+    except Exception as e:
+        logger.error(f"Error setting Python/NumPy seeds: {e}")
+    # --- End Seeding ---
+
+    try:
+        # Validate core EnvConfig
+        _ = EnvConfig()
+        logger.info("EnvConfig validated.")
+    except Exception as e:
+        logger.critical(f"EnvConfig validation failed: {e}", exc_info=True)
+        sys.exit(1)
+
+    try:
+        # Application is part of the UI package
+        app_instance = Application(mode=mode)
+        app_instance.run()
+    # Keep general exception handling
+    except Exception as e:
+        logger.critical(f"An unhandled error occurred: {e}", exc_info=True)
+        sys.exit(1)
+
+    logger.info("Exiting.")
+    sys.exit(0)
+
+
+@app.command()
+def play(
+    log_level: LogLevelOption = "INFO",
+    seed: SeedOption = 42,
+) -> None:
+    """Run the game in interactive Play mode."""
+    run_interactive_mode(mode="play", seed=seed, log_level=log_level)
+
+
+@app.command()
+def debug(
+    log_level: LogLevelOption = "DEBUG",
+    seed: SeedOption = 42,
+) -> None:
+    """Run the game in interactive Debug mode."""
+    run_interactive_mode(mode="debug", seed=seed, log_level=log_level)
+
+
+if __name__ == "__main__":
+    app()

trianglengin/ui/config.py

@@ -0,0 +1,44 @@
+# src/trianglengin/ui/config.py
+"""
+Configuration specific to display and visualization settings for the UI.
+"""
+
+import pygame  # Direct import
+from pydantic import BaseModel, Field
+
+# Initialize Pygame font module if not already done (safe to call multiple times)
+pygame.font.init()
+
+# Define a placeholder font loading function or load directly here
+# In a real app, this might load from files or use system fonts more robustly.
+try:
+    DEBUG_FONT_DEFAULT = pygame.font.SysFont("monospace", 12)
+except Exception:
+    DEBUG_FONT_DEFAULT = pygame.font.Font(None, 15)  # Fallback default pygame font
+
+
+class DisplayConfig(BaseModel):
+    """Configuration for visualization display settings."""
+
+    # Screen and Layout
+    SCREEN_WIDTH: int = Field(default=1024, gt=0)
+    SCREEN_HEIGHT: int = Field(default=768, gt=0)
+    FPS: int = Field(default=60, gt=0)
+    PADDING: int = Field(default=10, ge=0)
+    HUD_HEIGHT: int = Field(default=30, ge=0)
+    PREVIEW_AREA_WIDTH: int = Field(default=150, ge=50)
+    PREVIEW_PADDING: int = Field(default=5, ge=0)
+    PREVIEW_INNER_PADDING: int = Field(default=3, ge=0)
+    PREVIEW_BORDER_WIDTH: int = Field(default=1, ge=0)
+    PREVIEW_SELECTED_BORDER_WIDTH: int = Field(default=3, ge=0)
+
+    # Fonts
+    # Use default=None and validate/load later if pygame is available
+    DEBUG_FONT: pygame.font.Font | None = Field(default=DEBUG_FONT_DEFAULT)
+
+    class Config:
+        arbitrary_types_allowed = True  # Allow pygame.font.Font
+
+
+# Optional: Create a default instance for easy import elsewhere
+DEFAULT_DISPLAY_CONFIG = DisplayConfig()

trianglengin/ui/interaction/README.md

@@ -0,0 +1,44 @@
+
+# UI Interaction Module (`trianglengin.ui.interaction`)
+
+**Requires:** `pygame`
+
+## Purpose
+
+This submodule handles user input (keyboard and mouse) for the interactive modes ("play", "debug") provided by the `trianglengin.ui` package. It bridges the gap between raw Pygame events and actions within the game simulation (`GameState` from the core engine).
+
+-   **Event Processing:** [`event_processor.py`](event_processor.py) handles common Pygame events like quitting (QUIT, ESC) and window resizing. It acts as a generator, yielding other events for mode-specific processing.
+-   **Input Handler:** The [`InputHandler`](input_handler.py) class is the main entry point for this submodule.
+    -   It receives Pygame events (via the `event_processor`).
+    -   It **manages interaction-specific state** internally (e.g., `selected_shape_idx`, `hover_grid_coord`, `debug_highlight_coord`).
+    -   It determines the current interaction mode ("play" or "debug") and delegates event handling and hover updates to specific handler functions ([`play_mode_handler.py`](play_mode_handler.py), [`debug_mode_handler.py`](debug_mode_handler.py)).
+    -   It provides the necessary interaction state to the `trianglengin.ui.visualization.Visualizer` for rendering feedback (hover previews, selection highlights).
+-   **Mode-Specific Handlers:** `play_mode_handler.py` and `debug_mode_handler.py` contain the logic specific to each mode, operating on the `InputHandler`'s state and the core `GameState`.
+    -   `play`: Handles selecting shapes, checking placement validity, and triggering `GameState.step` on valid clicks. Updates hover state in the `InputHandler`.
+    -   `debug`: Handles toggling the state of individual triangles directly using `GameState.debug_toggle_cell`. Updates hover state in the `InputHandler`.
+-   **Decoupling:** It separates input handling logic from the core game simulation (`trianglengin`) and rendering (`trianglengin.ui.visualization`), although it needs references to both to function within the UI application.
+
+## Exposed Interfaces
+
+-   **Classes:**
+    -   `InputHandler`:
+        -   `__init__(game_state: GameState, visualizer: Visualizer, mode: str, env_config: EnvConfig)`
+        -   `handle_input() -> bool`: Processes events for one frame, returns `False` if quitting.
+        -   `get_render_interaction_state() -> dict`: Returns interaction state needed by `Visualizer.render`.
+-   **Functions:**
+    -   `process_pygame_events(visualizer: Visualizer) -> Generator[pygame.event.Event, Any, bool]`: Processes common events, yields others.
+    -   `handle_play_click(event: pygame.event.Event, handler: InputHandler)`: Handles clicks in play mode.
+    -   `update_play_hover(handler: InputHandler)`: Updates hover state in play mode.
+    -   `handle_debug_click(event: pygame.event.Event, handler: InputHandler)`: Handles clicks in debug mode.
+    -   `update_debug_hover(handler: InputHandler)`: Updates hover state in debug mode.
+
+## Dependencies
+
+-   **`trianglengin` (core):** `GameState`, `EnvConfig`, `Shape`.
+-   **`trianglengin.ui.visualization`**: `Visualizer`, `coord_mapper`.
+-   **`pygame`**: Relies heavily on Pygame for event handling (`pygame.event`, `pygame.mouse`) and constants (`MOUSEBUTTONDOWN`, `KEYDOWN`, etc.).
+-   **Standard Libraries:** `typing`, `logging`.
+
+---
+
+**Note:** Please keep this README updated when adding new interaction modes, changing input handling logic, or modifying the interfaces between interaction, environment, and visualization.

trianglengin/ui/interaction/__init__.py

@@ -0,0 +1,19 @@
+# src/trianglengin/ui/interaction/__init__.py
+"""
+Interaction handling module for interactive modes (play/debug).
+"""
+
+# Direct imports - if pygame is missing, these will fail.
+from .debug_mode_handler import handle_debug_click, update_debug_hover
+from .event_processor import process_pygame_events
+from .input_handler import InputHandler
+from .play_mode_handler import handle_play_click, update_play_hover
+
+__all__ = [
+    "InputHandler",
+    "process_pygame_events",
+    "handle_play_click",
+    "update_play_hover",
+    "handle_debug_click",
+    "update_debug_hover",
+]

trianglengin/ui/interaction/debug_mode_handler.py

@@ -0,0 +1,72 @@
+# src/trianglengin/ui/interaction/debug_mode_handler.py
+import logging
+from typing import TYPE_CHECKING
+
+# Imports are now direct
+import pygame
+
+# Use absolute imports for core components
+from trianglengin.ui.visualization import core as vis_core
+
+if TYPE_CHECKING:
+    # Use absolute import for InputHandler as well
+    from trianglengin.game_interface import GameState
+    from trianglengin.ui.interaction.input_handler import InputHandler
+
+logger = logging.getLogger(__name__)
+
+
+def handle_debug_click(event: pygame.event.Event, handler: "InputHandler") -> None:
+    """Handles mouse clicks in debug mode (toggle triangle state via C++)."""
+    if not (event.type == pygame.MOUSEBUTTONDOWN and event.button == 1):
+        return
+
+    game_state: GameState = handler.game_state  # Type hint uses wrapper
+    visualizer = handler.visualizer
+    mouse_pos = handler.mouse_pos
+
+    layout_rects = visualizer.ensure_layout()
+    grid_rect = layout_rects.get("grid")
+    if not grid_rect:
+        logger.error("Grid layout rectangle not available for debug click.")
+        return
+
+    grid_coords = vis_core.coord_mapper.get_grid_coords_from_screen(
+        mouse_pos, grid_rect, game_state.env_config
+    )
+    if not grid_coords:
+        return
+
+    r, c = grid_coords
+    try:
+        # Call the debug toggle method on the wrapper, which calls C++
+        game_state.debug_toggle_cell(r, c)
+        logger.debug(f"Debug: Toggled cell ({r},{c}) via C++ backend.")
+    except Exception as e:
+        logger.error(f"Error calling debug_toggle_cell for ({r},{c}): {e}")
+
+
+def update_debug_hover(handler: "InputHandler") -> None:
+    """Updates the debug highlight position within the InputHandler."""
+    handler.debug_highlight_coord = None
+
+    game_state: GameState = handler.game_state  # Type hint uses wrapper
+    visualizer = handler.visualizer
+    mouse_pos = handler.mouse_pos
+
+    layout_rects = visualizer.ensure_layout()
+    grid_rect = layout_rects.get("grid")
+    if not grid_rect or not grid_rect.collidepoint(mouse_pos):
+        return
+
+    grid_coords = vis_core.coord_mapper.get_grid_coords_from_screen(
+        mouse_pos, grid_rect, game_state.env_config
+    )
+
+    if grid_coords:
+        r, c = grid_coords
+        # Get grid data to check validity and death zone status
+        grid_data_np = game_state.get_grid_data_np()
+        rows, cols = grid_data_np["death"].shape
+        if 0 <= r < rows and 0 <= c < cols and not grid_data_np["death"][r, c]:
+            handler.debug_highlight_coord = grid_coords

trianglengin/ui/interaction/event_processor.py

@@ -0,0 +1,49 @@
+import logging
+from collections.abc import Generator
+from typing import TYPE_CHECKING, Any
+
+# Guard UI imports
+try:
+    import pygame
+except ImportError as e:
+    raise ImportError(
+        "UI components require 'pygame'. Install with 'pip install trianglengin[ui]'."
+    ) from e
+
+if TYPE_CHECKING:
+    # Use internal import relative to UI package
+    from ..visualization.core.visualizer import Visualizer
+
+logger = logging.getLogger(__name__)
+
+
+def process_pygame_events(
+    visualizer: "Visualizer",
+) -> Generator[pygame.event.Event, Any, bool]:
+    """
+    Processes basic Pygame events like QUIT, ESCAPE, VIDEORESIZE.
+    Yields other events for mode-specific handlers.
+    Returns False via StopIteration value if the application should quit, True otherwise.
+    """
+    should_quit = False
+    for event in pygame.event.get():
+        if event.type == pygame.QUIT:
+            logger.info("Received QUIT event.")
+            should_quit = True
+            break
+        if event.type == pygame.KEYDOWN and event.key == pygame.K_ESCAPE:
+            logger.info("Received ESCAPE key press.")
+            should_quit = True
+            break
+        if event.type == pygame.VIDEORESIZE:
+            try:
+                w, h = max(320, event.w), max(240, event.h)
+                visualizer.screen = pygame.display.set_mode((w, h), pygame.RESIZABLE)
+                visualizer.layout_rects = None
+                logger.info(f"Window resized to {w}x{h}")
+            except pygame.error as e:
+                logger.error(f"Error resizing window: {e}")
+            yield event
+        else:
+            yield event
+    return not should_quit

trianglengin/ui/interaction/input_handler.py

@@ -0,0 +1,89 @@
+import logging
+
+# Use absolute imports for core components
+from trianglengin.config import EnvConfig
+from trianglengin.game_interface import GameState, Shape
+
+# Guard UI imports
+try:
+    import pygame
+
+    from ..visualization import Visualizer  # Relative import within UI package
+    from . import debug_mode_handler, event_processor, play_mode_handler  # Relative
+except ImportError as e:
+    raise ImportError(
+        "UI components require 'pygame'. Install with 'pip install trianglengin[ui]'."
+    ) from e
+
+
+logger = logging.getLogger(__name__)
+
+
+class InputHandler:
+    """
+    Handles user input, manages interaction state (selection, hover),
+    and delegates actions to mode-specific handlers. Uses the GameState wrapper.
+    """
+
+    def __init__(
+        self,
+        game_state: GameState,  # Uses the core GameState wrapper
+        visualizer: Visualizer,  # Uses the UI Visualizer
+        mode: str,
+        env_config: EnvConfig,  # Uses the core EnvConfig
+    ):
+        self.game_state = game_state
+        self.visualizer = visualizer
+        self.mode = mode
+        self.env_config = env_config
+
+        # Interaction state managed here
+        self.selected_shape_idx: int = -1
+        self.hover_grid_coord: tuple[int, int] | None = None
+        self.hover_is_valid: bool = False
+        self.hover_shape: Shape | None = None  # Uses the core Shape struct
+        self.debug_highlight_coord: tuple[int, int] | None = None
+        self.mouse_pos: tuple[int, int] = (0, 0)
+
+    def handle_input(self) -> bool:
+        """Processes Pygame events and updates state based on mode. Returns False to quit."""
+        self.mouse_pos = pygame.mouse.get_pos()
+
+        # Reset hover/highlight state each frame before processing events/updates
+        self.hover_grid_coord = None
+        self.hover_is_valid = False
+        self.hover_shape = None
+        self.debug_highlight_coord = None
+
+        running = True
+        event_generator = event_processor.process_pygame_events(self.visualizer)
+        try:
+            while True:
+                event = next(event_generator)
+                # Pass self to handlers so they can modify interaction state
+                if self.mode == "play":
+                    play_mode_handler.handle_play_click(event, self)
+                elif self.mode == "debug":
+                    debug_mode_handler.handle_debug_click(event, self)
+        except StopIteration as e:
+            running = e.value  # False if quit requested
+
+        # Update hover state after processing events
+        if running:
+            if self.mode == "play":
+                play_mode_handler.update_play_hover(self)
+            elif self.mode == "debug":
+                debug_mode_handler.update_debug_hover(self)
+
+        return running
+
+    def get_render_interaction_state(self) -> dict:
+        """Returns interaction state needed by Visualizer.render"""
+        return {
+            "selected_shape_idx": self.selected_shape_idx,
+            "hover_shape": self.hover_shape,
+            "hover_grid_coord": self.hover_grid_coord,
+            "hover_is_valid": self.hover_is_valid,
+            "hover_screen_pos": self.mouse_pos,
+            "debug_highlight_coord": self.debug_highlight_coord,
+        }