trianglengin 1.0.6__py3-none-any.whl

trianglengin/app.py

@@ -0,0 +1,110 @@
+import logging
+
+import pygame
+
+# Use internal imports
+from . import config as tg_config
+from . import core as tg_core
+from . import interaction, visualization
+
+logger = logging.getLogger(__name__)
+
+
+class Application:
+    """Main application integrating visualization and interaction for trianglengin."""
+
+    def __init__(self, mode: str = "play"):
+        # Use DisplayConfig from this library now
+        self.display_config = tg_config.DisplayConfig()  # Use DisplayConfig
+        self.env_config = tg_config.EnvConfig()
+        self.mode = mode
+
+        pygame.init()
+        pygame.font.init()
+        self.screen = self._setup_screen()
+        self.clock = pygame.time.Clock()
+        self.fonts = visualization.load_fonts()
+
+        if self.mode in ["play", "debug"]:
+            # Create GameState using trianglengin core
+            self.game_state = tg_core.environment.GameState(self.env_config)
+            # Create Visualizer using trianglengin visualization
+            self.visualizer = visualization.Visualizer(
+                self.screen,
+                self.display_config,
+                self.env_config,
+                self.fonts,  # Pass DisplayConfig
+            )
+            # Create InputHandler using trianglengin interaction
+            self.input_handler = interaction.InputHandler(
+                self.game_state, self.visualizer, self.mode, self.env_config
+            )
+        else:
+            # Handle other modes or raise error if necessary
+            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,
+            ),  # Use DisplayConfig
+            pygame.RESIZABLE,
+        )
+        # Use a generic name or make APP_NAME part of trianglengin config later
+        pygame.display.set_caption(f"Triangle Engine - {self.mode.capitalize()} Mode")
+        return screen
+
+    def run(self):
+        """Main application loop."""
+        logger.info(f"Starting application in {self.mode} mode.")
+        while self.running:
+            self.clock.tick(self.display_config.FPS)  # Use DisplayConfig
+
+            # Handle Input using InputHandler
+            if self.input_handler:
+                self.running = self.input_handler.handle_input()
+                if not self.running:
+                    break
+            else:
+                # Fallback event handling (should not happen in play/debug)
+                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
+
+            # Render using Visualizer
+            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/cli.py

@@ -0,0 +1,134 @@
+import logging
+import sys
+from typing import Annotated
+
+# Removed torch import
+import typer
+
+# Use internal imports
+from .app import Application
+from .config import EnvConfig
+
+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 reproducibility.",
+    ),
+]
+
+
+def setup_logging(log_level_str: str):
+    """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,  # Override existing config
+    )
+    # Keep external libraries less verbose if needed
+    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):
+    """Runs the interactive application."""
+    setup_logging(log_level)
+    logger = logging.getLogger(__name__)
+    logger.info(f"Running Triangle Engine in {mode.capitalize()} mode...")
+
+    # --- UPDATED SEEDING (Removed Torch) ---
+    try:
+        import random
+
+        import numpy as np
+
+        random.seed(seed)
+        # Use default_rng() for NumPy if available, otherwise skip NumPy seeding
+        try:
+            np.random.default_rng(seed)
+            logger.debug("NumPy seeded using default_rng.")
+        except AttributeError:
+            logger.warning("np.random.default_rng not available. Skipping NumPy seed.")
+        except ImportError:
+            logger.warning("NumPy not found. Skipping NumPy seed.")
+
+        # Removed torch.manual_seed(seed)
+        logger.info(f"Set random seeds to {seed}")
+    except ImportError:
+        logger.warning("Could not import all libraries for full seeding.")
+    except Exception as e:
+        logger.error(f"Error setting seeds: {e}")
+    # --- END UPDATED SEEDING ---
+
+    # Validate EnvConfig
+    try:
+        _ = EnvConfig()
+        logger.info("EnvConfig validated.")
+    except Exception as e:
+        logger.critical(f"EnvConfig validation failed: {e}", exc_info=True)
+        sys.exit(1)
+
+    try:
+        app_instance = Application(mode=mode)
+        app_instance.run()
+    except ImportError as e:
+        logger.error(f"Runtime ImportError: {e}")
+        logger.error(
+            "Please ensure all dependencies (including pygame) are installed for trianglengin."
+        )
+        sys.exit(1)
+    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,
+):
+    """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",  # Default to DEBUG for debug mode
+    seed: SeedOption = 42,
+):
+    """Run the game in interactive Debug mode."""
+    run_interactive_mode(mode="debug", seed=seed, log_level=log_level)
+
+
+if __name__ == "__main__":
+    app()

trianglengin/config/__init__.py

@@ -0,0 +1,9 @@
+# trianglengin/config/__init__.py
+"""
+Shared configuration models for the Triangle Engine.
+"""
+
+from .display_config import DEFAULT_DISPLAY_CONFIG, DisplayConfig
+from .env_config import EnvConfig
+
+__all__ = ["EnvConfig", "DisplayConfig", "DEFAULT_DISPLAY_CONFIG"]

trianglengin/config/display_config.py

@@ -0,0 +1,47 @@
+# trianglengin/config/display_config.py
+"""
+Configuration specific to display and visualization settings.
+"""
+
+import pygame
+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 (Store font objects directly or paths/names)
+    # Using Field(default=...) requires the default value to be simple.
+    # For complex objects like fonts, use default_factory or initialize in __init__.
+    # For simplicity here, we'll assign the pre-loaded font.
+    # Consider using default_factory=lambda: pygame.font.SysFont(...)
+    DEBUG_FONT: pygame.font.Font = 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/config/env_config.py

@@ -0,0 +1,103 @@
+# File: trianglengin/config/env_config.py
+from pydantic import (
+    BaseModel,
+    Field,
+    computed_field,
+    field_validator,
+    model_validator,
+)
+
+
+class EnvConfig(BaseModel):
+    """Configuration for the game environment (Pydantic model)."""
+
+    ROWS: int = Field(default=8, gt=0)
+    COLS: int = Field(default=15, gt=0)
+    PLAYABLE_RANGE_PER_ROW: list[tuple[int, int]] = Field(
+        default=[
+            (3, 12),  # 9 cols, centered in 15
+            (2, 13),  # 11 cols
+            (1, 14),  # 13 cols
+            (0, 15),  # 15 cols
+            (0, 15),  # 15 cols
+            (1, 14),  # 13 cols
+            (2, 13),  # 11 cols
+            (3, 12),  # 9 cols
+        ]
+    )
+    NUM_SHAPE_SLOTS: int = Field(default=3, gt=0)
+
+    # --- Reward System Constants (v3) ---
+    REWARD_PER_PLACED_TRIANGLE: float = Field(default=0.01)
+    REWARD_PER_CLEARED_TRIANGLE: float = Field(default=0.5)
+    REWARD_PER_STEP_ALIVE: float = Field(default=0.005)
+    PENALTY_GAME_OVER: float = Field(default=-10.0)
+    # --- End Reward System Constants ---
+
+    @field_validator("PLAYABLE_RANGE_PER_ROW")
+    @classmethod
+    def check_playable_range_length(
+        cls, v: list[tuple[int, int]], info
+    ) -> list[tuple[int, int]]:
+        """Validates PLAYABLE_RANGE_PER_ROW."""
+        # Pydantic v2 uses 'values' in validator context
+        data = getattr(info, "data", None) or getattr(info, "values", {})
+
+        rows = data.get("ROWS")
+        cols = data.get("COLS")
+
+        if rows is None or cols is None:
+            return v
+
+        if len(v) != rows:
+            raise ValueError(
+                f"PLAYABLE_RANGE_PER_ROW length ({len(v)}) must equal ROWS ({rows})"
+            )
+
+        for i, (start, end) in enumerate(v):
+            if not (0 <= start < cols):
+                raise ValueError(
+                    f"Row {i}: start_col ({start}) out of bounds [0, {cols})."
+                )
+            if not (start < end <= cols):
+                raise ValueError(
+                    f"Row {i}: end_col ({end}) invalid. Must be > start_col ({start}) and <= COLS ({cols})."
+                )
+            # Allow zero width ranges (rows that are entirely death zones)
+            # if end - start <= 0:
+            #     raise ValueError(
+            #         f"Row {i}: Playable range width must be positive ({start}, {end})."
+            #     )
+
+        return v
+
+    @model_validator(mode="after")
+    def check_cols_sufficient_for_ranges(self) -> "EnvConfig":
+        """Ensure COLS is large enough for the specified ranges."""
+        if hasattr(self, "PLAYABLE_RANGE_PER_ROW") and self.PLAYABLE_RANGE_PER_ROW:
+            max_end_col = 0
+            for _, end in self.PLAYABLE_RANGE_PER_ROW:
+                max_end_col = max(max_end_col, end)
+
+            if max_end_col > self.COLS:
+                raise ValueError(
+                    f"COLS ({self.COLS}) must be >= the maximum end_col in PLAYABLE_RANGE_PER_ROW ({max_end_col})"
+                )
+        return self
+
+    @computed_field  # type: ignore[misc]
+    @property
+    def ACTION_DIM(self) -> int:
+        """Total number of possible actions (shape_slot * row * col)."""
+        # Ensure attributes exist before calculating
+        if (
+            hasattr(self, "NUM_SHAPE_SLOTS")
+            and hasattr(self, "ROWS")
+            and hasattr(self, "COLS")
+        ):
+            return self.NUM_SHAPE_SLOTS * self.ROWS * self.COLS
+        return 0  # Should not happen with pydantic defaults
+
+
+# Ensure model is rebuilt after computed_field definition
+EnvConfig.model_rebuild(force=True)

trianglengin/core/__init__.py

@@ -0,0 +1,8 @@
+# File: trianglengin/trianglengin/core/__init__.py
+"""
+Core game logic components: environment simulation and data structures.
+"""
+
+from . import environment, structs
+
+__all__ = ["environment", "structs"]

trianglengin/core/environment/__init__.py

@@ -0,0 +1,31 @@
+# File: trianglengin/core/environment/__init__.py
+"""
+Environment module defining the game rules, state, actions, and logic.
+"""
+
+from ...config import EnvConfig
+from .action_codec import decode_action, encode_action
+from .game_state import GameState
+from .grid import logic as GridLogic
+from .grid.grid_data import GridData
+from .logic.actions import get_valid_actions
+from .logic.step import calculate_reward, execute_placement
+from .shapes import logic as ShapeLogic
+
+__all__ = [
+    # Core
+    "GameState",
+    "encode_action",
+    "decode_action",
+    # Grid
+    "GridData",
+    "GridLogic",
+    # Shapes
+    "ShapeLogic",
+    # Logic
+    "get_valid_actions",
+    "execute_placement",
+    "calculate_reward",
+    # Config
+    "EnvConfig",
+]

trianglengin/core/environment/action_codec.py

@@ -0,0 +1,37 @@
+from typing import TypeAlias
+
+from ...config import EnvConfig
+
+ActionType: TypeAlias = int
+
+
+def encode_action(shape_idx: int, r: int, c: int, config: EnvConfig) -> ActionType:
+    """Encodes a (shape_idx, r, c) action into a single integer."""
+    if not (0 <= shape_idx < config.NUM_SHAPE_SLOTS):
+        raise ValueError(
+            f"Invalid shape index: {shape_idx}, must be < {config.NUM_SHAPE_SLOTS}"
+        )
+    if not (0 <= r < config.ROWS):
+        raise ValueError(f"Invalid row index: {r}, must be < {config.ROWS}")
+    if not (0 <= c < config.COLS):
+        raise ValueError(f"Invalid column index: {c}, must be < {config.COLS}")
+
+    action_index = shape_idx * (config.ROWS * config.COLS) + r * config.COLS + c
+    return action_index
+
+
+def decode_action(action_index: ActionType, config: EnvConfig) -> tuple[int, int, int]:
+    """Decodes an integer action into (shape_idx, r, c)."""
+    action_dim_int = int(config.ACTION_DIM)  # type: ignore[call-overload]
+    if not (0 <= action_index < action_dim_int):
+        raise ValueError(
+            f"Invalid action index: {action_index}, must be < {action_dim_int}"
+        )
+
+    grid_size = config.ROWS * config.COLS
+    shape_idx = action_index // grid_size
+    remainder = action_index % grid_size
+    r = remainder // config.COLS
+    c = remainder % config.COLS
+
+    return shape_idx, r, c