trianglengin 1.0.6__py3-none-any.whl

trianglengin/core/environment/game_state.py

@@ -0,0 +1,217 @@
+# trianglengin/core/environment/game_state.py
+import copy
+import logging
+import random
+from typing import TYPE_CHECKING
+
+from trianglengin.config.env_config import EnvConfig
+from trianglengin.core.environment.action_codec import (
+    ActionType,
+    decode_action,
+)
+from trianglengin.core.environment.grid.grid_data import GridData
+from trianglengin.core.environment.logic.actions import get_valid_actions
+
+# Import calculate_reward and execute_placement from step logic
+from trianglengin.core.environment.logic.step import calculate_reward, execute_placement
+from trianglengin.core.environment.shapes import logic as ShapeLogic
+
+if TYPE_CHECKING:
+    from trianglengin.core.structs.shape import Shape
+
+
+log = logging.getLogger(__name__)
+
+
+class GameState:
+    """
+    Represents the mutable state of the game environment.
+    """
+
+    def __init__(
+        self, config: EnvConfig | None = None, initial_seed: int | None = None
+    ):
+        self.env_config: EnvConfig = config if config else EnvConfig()
+        self._rng = random.Random(initial_seed)
+        self.grid_data: GridData = GridData(self.env_config)
+        self.shapes: list[Shape | None] = [None] * self.env_config.NUM_SHAPE_SLOTS
+        self._game_score: float = 0.0
+        self._game_over: bool = False
+        self._game_over_reason: str | None = None
+        self.current_step: int = 0
+        self._valid_actions_cache: set[ActionType] | None = None
+        self.reset()
+
+    def reset(self) -> None:
+        """Resets the game to an initial state."""
+        self.grid_data.reset()
+        self.shapes = [None] * self.env_config.NUM_SHAPE_SLOTS
+        self._game_score = 0.0
+        self._game_over = False
+        self._game_over_reason = None
+        self.current_step = 0
+        self._valid_actions_cache = None
+        ShapeLogic.refill_shape_slots(self, self._rng)  # Initial fill
+        if not self.valid_actions():  # Check if initial state is game over
+            self._game_over = True
+            self._game_over_reason = "No valid actions available at start."
+            log.warning(self._game_over_reason)
+
+    def step(self, action_index: ActionType) -> tuple[float, bool]:
+        """
+        Performs one game step based on the chosen action.
+        Handles placement, line clearing, scoring, refilling, and game over checks.
+        Returns: (reward, done)
+        Raises: ValueError if action is invalid or placement fails.
+        """
+        if self.is_over():
+            log.warning("Attempted to step in a game that is already over.")
+            return 0.0, True
+
+        # Check action validity before execution
+        current_valid_actions = self.valid_actions()
+        if action_index not in current_valid_actions:
+            log.error(
+                f"Invalid action {action_index} provided. Valid: {current_valid_actions}"
+            )
+            raise ValueError("Action is not in the set of valid actions")
+
+        shape_idx, r, c = decode_action(action_index, self.env_config)
+
+        # --- Execute Placement and Get Stats ---
+        try:
+            # execute_placement now only returns counts and raises error on failure
+            cleared_count, placed_count = execute_placement(self, shape_idx, r, c)
+        except (ValueError, IndexError) as e:
+            # Catch errors from execute_placement (e.g., invalid placement attempt)
+            log.critical(
+                f"Critical error during placement execution: {e}", exc_info=True
+            )
+            # Force game over with a penalty
+            self.force_game_over(f"Placement execution error: {e}")
+            # Return penalty, game is over
+            return calculate_reward(0, 0, True, self.env_config), True
+
+        # --- Refill shapes IF AND ONLY IF all slots are now empty ---
+        if all(s is None for s in self.shapes):
+            log.debug("All shape slots empty after placement, triggering refill.")
+            ShapeLogic.refill_shape_slots(self, self._rng)
+            # Refill might make new actions available, so clear cache before final check
+            self._valid_actions_cache = None
+        else:
+            # Invalidate cache anyway as grid state or shapes list changed
+            self._valid_actions_cache = None
+
+        self.current_step += 1
+
+        # --- Final Game Over Check ---
+        # Check if any valid actions exist *after* placement and potential refill.
+        # Calling valid_actions() populates the cache and returns the set.
+        has_valid_moves_now = bool(self.valid_actions())
+
+        # Update the game over state based on the check
+        is_final_step_game_over = not has_valid_moves_now
+        if is_final_step_game_over and not self._game_over:
+            self._game_over = True
+            self._game_over_reason = "No valid actions available after step."
+            log.info(f"Game over at step {self.current_step}: {self._game_over_reason}")
+        # Note: If game was already over, self._game_over remains True
+
+        # --- Calculate Reward ---
+        # Reward depends on placement/clear counts and the final game over state for THIS step
+        reward = calculate_reward(
+            placed_count=placed_count,
+            cleared_count=cleared_count,
+            is_game_over=self._game_over,  # Use the definitive game over state
+            config=self.env_config,
+        )
+
+        # Return the calculated reward and the definitive game over status
+        return reward, self._game_over
+
+    def valid_actions(self, force_recalculate: bool = False) -> set[ActionType]:
+        """
+        Returns a set of valid encoded action indices for the current state.
+        Uses a cache for performance unless force_recalculate is True.
+        """
+        if not force_recalculate and self._valid_actions_cache is not None:
+            return self._valid_actions_cache
+
+        # If game is already marked as over, no need to calculate, return empty set
+        if self._game_over:
+            if (
+                self._valid_actions_cache is None
+            ):  # Ensure cache is set if accessed after forced over
+                self._valid_actions_cache = set()
+            return set()
+
+        # Calculate fresh valid actions
+        current_valid_actions = get_valid_actions(self)
+        # Update cache before returning
+        self._valid_actions_cache = current_valid_actions
+        return current_valid_actions
+
+    def is_over(self) -> bool:
+        """Checks if the game is over by checking for valid actions."""
+        if self._game_over:  # If already marked, return true
+            return True
+        # If not marked, check if valid actions exist. This call populates cache.
+        has_valid_actions = bool(self.valid_actions())
+        if not has_valid_actions:
+            # If no actions found, mark game as over now
+            self._game_over = True
+            if not self._game_over_reason:  # Set reason if not already set
+                self._game_over_reason = "No valid actions available."
+            log.info(
+                f"Game determined over by is_over() check: {self._game_over_reason}"
+            )
+            return True
+        # If actions exist, game is not over
+        return False
+
+    def get_outcome(self) -> float:
+        """Returns terminal outcome: -1.0 for loss, 0.0 for ongoing."""
+        return -1.0 if self.is_over() else 0.0
+
+    def game_score(self) -> float:
+        """Returns the current accumulated score."""
+        return self._game_score
+
+    def get_game_over_reason(self) -> str | None:
+        """Returns the reason why the game ended, if it's over."""
+        return self._game_over_reason
+
+    def force_game_over(self, reason: str) -> None:
+        """Forces the game to end immediately."""
+        self._game_over = True
+        self._game_over_reason = reason
+        self._valid_actions_cache = set()  # Ensure cache is cleared
+        log.warning(f"Game forced over: {reason}")
+
+    def copy(self) -> "GameState":
+        """Creates a deep copy for simulations (e.g., MCTS)."""
+        new_state = GameState.__new__(GameState)
+        memo = {id(self): new_state}
+        new_state.env_config = self.env_config
+        new_state._rng = random.Random()
+        new_state._rng.setstate(self._rng.getstate())
+        new_state.grid_data = copy.deepcopy(self.grid_data, memo)
+        new_state.shapes = [s.copy() if s else None for s in self.shapes]
+        new_state._game_score = self._game_score
+        new_state._game_over = self._game_over
+        new_state._game_over_reason = self._game_over_reason
+        new_state.current_step = self.current_step
+        new_state._valid_actions_cache = (
+            self._valid_actions_cache.copy()
+            if self._valid_actions_cache is not None
+            else None
+        )
+        return new_state
+
+    def __str__(self) -> str:
+        shape_strs = [str(s.color) if s else "None" for s in self.shapes]
+        status = "Over" if self.is_over() else "Ongoing"
+        return (
+            f"GameState(Step:{self.current_step}, Score:{self.game_score():.1f}, "
+            f"Status:{status}, Shapes:[{', '.join(shape_strs)}])"
+        )

trianglengin/core/environment/grid/README.md

@@ -0,0 +1,46 @@
+
+# Environment Grid Submodule (`trianglengin.core.environment.grid`)
+
+## Purpose and Architecture
+
+This submodule manages the game's grid structure and related logic. It defines the triangular cells, their properties, relationships, and operations like placement validation and line clearing.
+
+-   **Cell Representation:** The actual state (occupied, death, color) is managed within `GridData` using NumPy arrays. The orientation (`is_up`) is implicit from the coordinates `(r + c) % 2 != 0`.
+-   **Grid Data Structure:** The [`GridData`](grid_data.py) class holds the grid state using efficient `numpy` arrays (`_occupied_np`, `_death_np`, `_color_id_np`). It initializes death zones based on the `PLAYABLE_RANGE_PER_ROW` setting in `EnvConfig`. It retrieves precomputed potential lines and a coordinate-to-line mapping from the [`line_cache`](line_cache.py) module during initialization.
+-   **Line Cache:** The [`line_cache`](line_cache.py) module precomputes **maximal** continuous lines (as coordinate tuples) of playable cells in the three directions (Horizontal, Diagonal TL-BR, Diagonal BL-TR). A maximal line is the longest possible continuous segment of playable cells in a given direction. It also creates a map from coordinates to the maximal lines they belong to (`_coord_to_lines_map`). This computation is done once per grid configuration (based on dimensions, playable ranges) and cached for efficiency. The `is_live` check within this module uses `PLAYABLE_RANGE_PER_ROW`.
+-   **Grid Logic:** The [`logic.py`](logic.py) module (exposed as `GridLogic`) contains functions operating on `GridData`. This includes:
+    -   Checking if a shape can be placed (`can_place`), including matching triangle orientations and checking against death zones.
+    -   Checking for and clearing completed lines (`check_and_clear_lines`) using the precomputed coordinate map for efficiency. It checks if *all* cells within a candidate maximal line (with a minimum length, typically 2) are occupied before marking it for clearing.
+-   **Grid Features:** Note: Any functions related to calculating scalar metrics (heights, holes, bumpiness) are expected to be handled outside this core engine library, likely in a separate features module or project.
+
+## Exposed Interfaces
+
+-   **Classes:**
+    -   `GridData`: Holds the grid state using NumPy arrays and cached line information.
+        -   `__init__(config: EnvConfig)`
+        -   `reset()`
+        -   `valid(r: int, c: int) -> bool`
+        -   `is_death(r: int, c: int) -> bool`
+        -   `is_occupied(r: int, c: int) -> bool`
+        -   `get_color_id(r: int, c: int) -> Optional[int]`
+        -   `__deepcopy__(memo)`
+-   **Modules/Namespaces:**
+    -   `logic` (often imported as `GridLogic`):
+        -   `can_place(grid_data: GridData, shape: Shape, r: int, c: int) -> bool`
+        -   `check_and_clear_lines(grid_data: GridData, newly_occupied_coords: Set[Tuple[int, int]]) -> Tuple[int, Set[Tuple[int, int]], Set[frozenset[Tuple[int, int]]]]` **(Returns: lines_cleared_count, unique_coords_cleared_set, set_of_cleared_lines_coord_sets)**
+    -   `line_cache`:
+        -   `get_precomputed_lines_and_map(config: EnvConfig) -> Tuple[List[Line], CoordMap]`
+
+## Dependencies
+
+-   **[`trianglengin.config`](../../../config/README.md)**:
+    -   `EnvConfig`: Used by `GridData` initialization and logic functions (specifically `PLAYABLE_RANGE_PER_ROW`).
+-   **[`trianglengin.structs`](../../../structs/README.md)**:
+    -   Uses `Shape`, `NO_COLOR_ID`.
+-   **`numpy`**:
+    -   Used extensively in `GridData`.
+-   **Standard Libraries:** `typing`, `logging`, `numpy`, `copy`.
+
+---
+
+**Note:** Please keep this README updated when changing the grid structure, cell properties, placement rules, or line clearing logic. Accurate documentation is crucial for maintainability.

trianglengin/core/environment/grid/__init__.py

@@ -0,0 +1,18 @@
+# trianglengin/core/environment/grid/__init__.py
+"""
+Modules related to the game grid structure and logic.
+
+Provides:
+- GridData: Class representing the grid state.
+- logic: Module containing grid-related logic (placement, line clearing).
+- line_cache: Module for caching precomputed lines.
+
+See GridData documentation: [grid_data.py](grid_data.py)
+See Grid Logic documentation: [logic.py](logic.py)
+See Line Cache documentation: [line_cache.py](line_cache.py)
+"""
+
+from . import line_cache, logic
+from .grid_data import GridData
+
+__all__ = ["GridData", "logic", "line_cache"]

trianglengin/core/environment/grid/grid_data.py

@@ -0,0 +1,140 @@
+# File: trianglengin/core/environment/grid/grid_data.py
+import logging
+
+import numpy as np
+
+from trianglengin.config.env_config import EnvConfig
+from trianglengin.core.environment.grid.line_cache import (
+    CoordMap,
+    Line,
+    get_precomputed_lines_and_map,
+)
+
+log = logging.getLogger(__name__)
+
+
+class GridData:
+    """Stores and manages the state of the game grid."""
+
+    __slots__ = (
+        "config",
+        "rows",
+        "cols",
+        "_occupied_np",
+        "_color_id_np",
+        "_death_np",
+        "_lines",
+        "_coord_to_lines_map",
+    )
+
+    def __init__(self, config: EnvConfig):
+        """
+        Initializes the grid based on the provided configuration.
+        Death zones are set based on PLAYABLE_RANGE_PER_ROW.
+
+        Args:
+            config: The environment configuration dataclass.
+        """
+        self.config: EnvConfig = config
+        self.rows: int = config.ROWS
+        self.cols: int = config.COLS
+
+        self._occupied_np: np.ndarray = np.full(
+            (self.rows, self.cols), False, dtype=bool
+        )
+        self._color_id_np: np.ndarray = np.full(
+            (self.rows, self.cols), -1, dtype=np.int8
+        )
+        # Initialize all as death, then mark playable area as not death
+        self._death_np: np.ndarray = np.full((self.rows, self.cols), True, dtype=bool)
+
+        for r in range(self.rows):
+            start_col, end_col = config.PLAYABLE_RANGE_PER_ROW[r]
+            if start_col < end_col:  # Ensure valid range
+                self._death_np[r, start_col:end_col] = False  # Mark playable cols
+
+        # Get Precomputed Lines and Map from Cache
+        self._lines: list[Line]
+        self._coord_to_lines_map: CoordMap
+        self._lines, self._coord_to_lines_map = get_precomputed_lines_and_map(config)
+
+        log.debug(
+            f"GridData initialized: {self.rows}x{self.cols}, "
+            f"{np.sum(self._death_np)} death cells, "
+            f"{len(self._lines)} precomputed lines, "
+            f"{len(self._coord_to_lines_map)} mapped coords."
+        )
+
+    def reset(self) -> None:
+        """Resets the grid to an empty state (occupied and colors)."""
+        self._occupied_np.fill(False)
+        self._color_id_np.fill(-1)
+        log.debug("GridData reset.")
+
+    def is_empty(self) -> bool:
+        """Checks if the grid has any occupied cells (excluding death zones)."""
+        # Consider only non-death cells for emptiness check
+        playable_mask = ~self._death_np
+        return not self._occupied_np[playable_mask].any()
+
+    def valid(self, r: int, c: int) -> bool:
+        """Checks if the coordinates (r, c) are within the grid bounds."""
+        return 0 <= r < self.rows and 0 <= c < self.cols
+
+    def is_death(self, r: int, c: int) -> bool:
+        """
+        Checks if the cell (r, c) is a death zone.
+
+        Raises:
+            IndexError: If (r, c) is out of bounds.
+        """
+        if not self.valid(r, c):
+            raise IndexError(
+                f"Coordinates ({r},{c}) out of bounds ({self.rows}x{self.cols})."
+            )
+        return bool(self._death_np[r, c])
+
+    def is_occupied(self, r: int, c: int) -> bool:
+        """
+        Checks if the cell (r, c) is occupied by a triangle piece.
+        Returns False for death zones, regardless of the underlying array value.
+
+        Raises:
+            IndexError: If (r, c) is out of bounds.
+        """
+        if not self.valid(r, c):
+            raise IndexError(
+                f"Coordinates ({r},{c}) out of bounds ({self.rows}x{self.cols})."
+            )
+        if self._death_np[r, c]:
+            return False
+        return bool(self._occupied_np[r, c])
+
+    def get_color_id(self, r: int, c: int) -> int | None:
+        """
+        Gets the color ID of the triangle at (r, c).
+
+        Returns None if the cell is empty, a death zone, or out of bounds.
+        """
+        if not self.valid(r, c) or self._death_np[r, c] or not self._occupied_np[r, c]:
+            return None
+        return int(self._color_id_np[r, c])
+
+    def __deepcopy__(self, memo):
+        """Custom deepcopy implementation."""
+        new_grid = GridData.__new__(GridData)
+        memo[id(self)] = new_grid
+
+        new_grid.config = self.config
+        new_grid.rows = self.rows
+        new_grid.cols = self.cols
+        new_grid._occupied_np = self._occupied_np.copy()
+        new_grid._color_id_np = self._color_id_np.copy()
+        new_grid._death_np = self._death_np.copy()
+
+        # Lines list and map are obtained from cache, but need copying for the instance
+        new_grid._lines, new_grid._coord_to_lines_map = get_precomputed_lines_and_map(
+            self.config
+        )
+
+        return new_grid

trianglengin/core/environment/grid/line_cache.py

@@ -0,0 +1,189 @@
+# File: trianglengin/core/environment/grid/line_cache.py
+import logging
+from typing import Final, cast
+
+import numpy as np
+
+from trianglengin.config.env_config import EnvConfig
+
+log = logging.getLogger(__name__)
+
+# Type aliases
+Coord = tuple[int, int]
+Line = tuple[Coord, ...]
+LineFsSet = set[frozenset[Coord]]
+CoordMap = dict[Coord, LineFsSet]
+ConfigKey = tuple[int, int, tuple[tuple[int, int], ...]]
+CachedData = tuple[list[Line], CoordMap]
+_LINE_CACHE: dict[ConfigKey, CachedData] = {}
+
+# Directions
+HORIZONTAL: Final = "h"
+DIAGONAL_TL_BR: Final = "d1"
+DIAGONAL_BL_TR: Final = "d2"
+
+
+def _create_cache_key(config: EnvConfig) -> ConfigKey:
+    """Creates an immutable cache key from relevant EnvConfig fields."""
+    playable_ranges_tuple: tuple[tuple[int, int], ...] = cast(
+        "tuple[tuple[int, int], ...]",
+        tuple(tuple(item) for item in config.PLAYABLE_RANGE_PER_ROW),
+    )
+    return (
+        config.ROWS,
+        config.COLS,
+        playable_ranges_tuple,
+    )
+
+
+def get_precomputed_lines_and_map(config: EnvConfig) -> CachedData:
+    """
+    Retrieves the precomputed maximal lines and the coordinate-to-lines map
+    for a given configuration, using a cache. Computes if not found.
+    """
+    key = _create_cache_key(config)
+    if key not in _LINE_CACHE:
+        log.info(f"Cache miss for grid config: {key}. Computing maximal lines and map.")
+        # Use the computation function v4
+        _LINE_CACHE[key] = _compute_lines_and_map_v4(config)
+
+    lines, coord_map = _LINE_CACHE[key]
+    # Return copies to prevent modification of the cache
+    return list(lines), {coord: set(lineset) for coord, lineset in coord_map.items()}
+
+
+def _is_live(r: int, c: int, config: EnvConfig, playable_mask: np.ndarray) -> bool:
+    """Checks if a cell is within bounds and the playable range for its row using precomputed mask."""
+    # Bounds check first
+    if not (0 <= r < config.ROWS and 0 <= c < config.COLS):
+        return False
+    # Check precomputed mask and cast to bool for mypy
+    return bool(playable_mask[r, c])
+
+
+def _get_neighbor(
+    r: int, c: int, direction: str, backward: bool, config: EnvConfig
+) -> Coord | None:
+    """
+    Gets the neighbor coordinate in a given direction (forward or backward).
+    Requires config for bounds checking.
+    """
+    is_up = (r + c) % 2 != 0
+
+    if direction == HORIZONTAL:
+        dc = -1 if backward else 1
+        nr, nc = r, c + dc
+    elif direction == DIAGONAL_TL_BR:  # Top-Left to Bottom-Right
+        if backward:  # Moving Up-Left
+            nr, nc = (r - 1, c) if not is_up else (r, c - 1)
+        else:  # Moving Down-Right
+            nr, nc = (r + 1, c) if is_up else (r, c + 1)
+    elif direction == DIAGONAL_BL_TR:  # Bottom-Left to Top-Right
+        if backward:  # Moving Down-Left
+            nr, nc = (r + 1, c) if is_up else (r, c - 1)
+        else:  # Moving Up-Right
+            nr, nc = (r - 1, c) if not is_up else (r, c + 1)
+    else:
+        raise ValueError(f"Unknown direction: {direction}")
+
+    # Return None if neighbor is out of grid bounds (simplifies tracing loops)
+    if not (0 <= nr < config.ROWS and 0 <= nc < config.COLS):
+        return None
+    return (nr, nc)
+
+
+def _compute_lines_and_map_v4(config: EnvConfig) -> CachedData:
+    """
+    Generates all maximal potential horizontal and diagonal lines based on grid geometry
+    and playable ranges. Builds the coordinate map.
+    V4: Use trace-back-then-forward approach for each cell and direction.
+    """
+    rows, cols = config.ROWS, config.COLS
+    maximal_lines_set: set[Line] = set()
+    processed_starts: set[tuple[Coord, str]] = set()
+
+    # --- Determine playable cells based on config ---
+    playable_mask = np.zeros((rows, cols), dtype=bool)
+    for r in range(rows):
+        if r < len(config.PLAYABLE_RANGE_PER_ROW):
+            start_col, end_col = config.PLAYABLE_RANGE_PER_ROW[r]
+            if start_col < end_col:
+                playable_mask[r, start_col:end_col] = True
+    # --- End Playable Mask ---
+
+    for r_init in range(rows):
+        for c_init in range(cols):
+            if not _is_live(r_init, c_init, config, playable_mask):
+                continue
+
+            current_coord = (r_init, c_init)
+
+            for direction in [HORIZONTAL, DIAGONAL_TL_BR, DIAGONAL_BL_TR]:
+                # 1. Trace backwards to find the true start of the segment
+                line_start_coord = current_coord
+                while True:
+                    prev_coord_tuple = _get_neighbor(
+                        line_start_coord[0],
+                        line_start_coord[1],
+                        direction,
+                        backward=True,
+                        config=config,  # Pass config here
+                    )
+                    if prev_coord_tuple and _is_live(
+                        prev_coord_tuple[0], prev_coord_tuple[1], config, playable_mask
+                    ):
+                        line_start_coord = prev_coord_tuple
+                    else:
+                        break  # Found the start or hit boundary/non-playable
+
+                # 2. Check if we've already processed this line from its start
+                if (line_start_coord, direction) in processed_starts:
+                    continue
+
+                # 3. Trace forwards from the true start to build the maximal line
+                current_line: list[Coord] = []
+                trace_coord: Coord | None = line_start_coord
+                while trace_coord and _is_live(
+                    trace_coord[0], trace_coord[1], config, playable_mask
+                ):
+                    current_line.append(trace_coord)
+                    trace_coord = _get_neighbor(
+                        trace_coord[0],
+                        trace_coord[1],
+                        direction,
+                        backward=False,
+                        config=config,  # Pass config here
+                    )
+
+                # 4. Store the maximal line if it's not empty
+                if current_line:
+                    maximal_lines_set.add(tuple(current_line))
+                    # Mark the start coordinate as processed for this direction
+                    processed_starts.add((line_start_coord, direction))
+
+    # --- Build Final List and Map ---
+    final_lines_list = sorted(
+        maximal_lines_set,
+        key=lambda line: (
+            line[0][0],
+            line[0][1],
+            len(line),
+            line,
+        ),  # Sort for deterministic order
+    )
+
+    coord_map: CoordMap = {}
+    for line_tuple in final_lines_list:
+        line_fs = frozenset(line_tuple)  # Use frozenset for map values
+        for coord in line_tuple:
+            if coord not in coord_map:
+                coord_map[coord] = set()
+            coord_map[coord].add(line_fs)
+
+    key = _create_cache_key(config)
+    log.info(
+        f"Computed {len(final_lines_list)} unique maximal lines (v4) "
+        f"and map for {len(coord_map)} coords for config {key}."
+    )
+
+    return final_lines_list, coord_map