trianglengin 1.0.6__py3-none-any.whl

trianglengin/core/environment/grid/logic.py

@@ -0,0 +1,131 @@
+# File: trianglengin/core/environment/grid/logic.py
+import logging
+from typing import TYPE_CHECKING, Final
+
+from trianglengin.core.structs.constants import NO_COLOR_ID
+
+if TYPE_CHECKING:
+    from trianglengin.core.environment.grid.grid_data import GridData
+    from trianglengin.core.structs.shape import Shape
+
+
+log = logging.getLogger(__name__)
+
+# Minimum length a line must have to be eligible for clearing
+MIN_LINE_LENGTH_TO_CLEAR: Final = 2
+
+
+def can_place(grid_data: "GridData", shape: "Shape", r: int, c: int) -> bool:
+    """
+    Checks if a shape can be placed at the specified (r, c) top-left position.
+
+    Args:
+        grid_data: The current grid state.
+        shape: The shape to place.
+        r: Target row for the shape's origin (relative 0,0).
+        c: Target column for the shape's origin (relative 0,0).
+
+    Returns:
+        True if the placement is valid, False otherwise.
+    """
+    if not shape or not shape.triangles:
+        log.warning("Attempted to check placement for an empty or invalid shape.")
+        return False
+
+    for dr, dc, is_up_shape in shape.triangles:
+        place_r, place_c = r + dr, c + dc
+
+        # 1. Check bounds
+        if not grid_data.valid(place_r, place_c):
+            return False
+
+        # 2. Check death zone
+        if grid_data.is_death(place_r, place_c):
+            return False
+
+        # 3. Check occupancy
+        if grid_data.is_occupied(place_r, place_c):
+            return False
+
+        # 4. Check orientation match
+        is_up_grid = (place_r + place_c) % 2 != 0
+        if is_up_shape != is_up_grid:
+            return False
+
+    return True
+
+
+def 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]]]]:
+    """
+    Checks for completed lines involving the newly occupied coordinates and clears them.
+
+    Uses the precomputed coordinate-to-lines map for efficiency. Only checks
+    maximal lines that contain at least one of the newly occupied cells.
+
+    Args:
+        grid_data: The grid data object (will be modified if lines are cleared).
+        newly_occupied_coords: A set of (r, c) tuples that were just filled.
+
+    Returns:
+        A tuple containing:
+        - lines_cleared_count (int): The number of maximal lines cleared.
+        - unique_coords_cleared_set (set[tuple[int, int]]): A set of unique (r, c)
+          coordinates of all triangles that were cleared.
+        - set_of_cleared_lines_coord_sets (set[frozenset[tuple[int, int]]]): A set
+          containing the frozensets of coordinates for each cleared maximal line.
+    """
+    if not newly_occupied_coords:
+        return 0, set(), set()
+
+    # Find all candidate maximal lines that include any of the new coordinates
+    candidate_lines_fs: set[frozenset[tuple[int, int]]] = set()
+    for r_new, c_new in newly_occupied_coords:
+        # Check if the coordinate exists in the precomputed map
+        if (r_new, c_new) in grid_data._coord_to_lines_map:
+            candidate_lines_fs.update(grid_data._coord_to_lines_map[(r_new, c_new)])
+
+    if not candidate_lines_fs:
+        return 0, set(), set()
+
+    cleared_lines_fs: set[frozenset[tuple[int, int]]] = set()
+    unique_coords_cleared: set[tuple[int, int]] = set()
+
+    # Check each candidate line for completion
+    for line_fs in candidate_lines_fs:
+        line_coords = tuple(line_fs)  # Convert back for iteration/indexing if needed
+
+        # --- Added Check: Ensure line has minimum length ---
+        if len(line_coords) < MIN_LINE_LENGTH_TO_CLEAR:
+            continue
+        # --- End Added Check ---
+
+        # Check if ALL coordinates in this line are now occupied
+        is_line_complete = True
+        for r_line, c_line in line_coords:
+            # Use is_occupied which correctly handles death zones
+            if not grid_data.is_occupied(r_line, c_line):
+                is_line_complete = False
+                break  # No need to check further coords in this line
+
+        if is_line_complete:
+            cleared_lines_fs.add(line_fs)
+            unique_coords_cleared.update(line_coords)
+
+    # If any lines were completed, clear the cells
+    if unique_coords_cleared:
+        log.debug(
+            f"Clearing {len(cleared_lines_fs)} lines involving {len(unique_coords_cleared)} unique cells."
+        )
+        for r_clear, c_clear in unique_coords_cleared:
+            # Check bounds just in case, though precomputed lines should be valid
+            if grid_data.valid(r_clear, c_clear):
+                grid_data._occupied_np[r_clear, c_clear] = False
+                grid_data._color_id_np[r_clear, c_clear] = NO_COLOR_ID
+            else:
+                log.warning(
+                    f"Attempted to clear out-of-bounds coordinate ({r_clear}, {c_clear}) from line."
+                )
+
+    return len(cleared_lines_fs), unique_coords_cleared, cleared_lines_fs

trianglengin/core/environment/logic/__init__.py

@@ -0,0 +1,3 @@
+# File: trianglengin/trianglengin/core/environment/logic/__init__.py
+# Moved from alphatriangle/environment/logic/__init__.py
+# No code changes needed, only file location.

trianglengin/core/environment/logic/actions.py

@@ -0,0 +1,38 @@
+# trianglengin/core/environment/logic/actions.py
+"""
+Logic for determining valid actions in the game state.
+"""
+
+import logging
+from typing import TYPE_CHECKING  # Changed List to Set
+
+from trianglengin.core.environment.action_codec import ActionType, encode_action
+from trianglengin.core.environment.grid import logic as GridLogic
+
+if TYPE_CHECKING:
+    from trianglengin.core.environment.game_state import GameState
+
+
+logger = logging.getLogger(__name__)
+
+
+def get_valid_actions(state: "GameState") -> set[ActionType]:  # Return Set
+    """
+    Calculates and returns a set of all valid encoded action indices
+    for the current game state.
+    """
+    valid_actions: set[ActionType] = set()  # Use set directly
+    for shape_idx, shape in enumerate(state.shapes):
+        if shape is None:
+            continue
+
+        # Iterate through potential placement locations (r, c)
+        # Optimization: Could potentially limit r, c range based on shape bbox
+        for r in range(state.env_config.ROWS):
+            for c in range(state.env_config.COLS):
+                # Check if placement is valid using GridLogic
+                if GridLogic.can_place(state.grid_data, shape, r, c):
+                    action_index = encode_action(shape_idx, r, c, state.env_config)
+                    valid_actions.add(action_index)  # Add to set
+
+    return valid_actions

trianglengin/core/environment/logic/step.py

@@ -0,0 +1,134 @@
+# trianglengin/core/environment/logic/step.py
+import logging
+from typing import TYPE_CHECKING
+
+# Import shapes module itself for ShapeLogic reference if needed later,
+# though direct calls are used here.
+from trianglengin.core.environment.grid import logic as GridLogic
+from trianglengin.core.structs.constants import COLOR_TO_ID_MAP, NO_COLOR_ID
+
+if TYPE_CHECKING:
+    # Keep EnvConfig import for reward calculation
+    from trianglengin.config import EnvConfig
+    from trianglengin.core.environment.game_state import GameState
+    from trianglengin.core.environment.grid.line_cache import Coord
+
+
+logger = logging.getLogger(__name__)
+
+
+def calculate_reward(
+    placed_count: int,
+    cleared_count: int,
+    is_game_over: bool,
+    config: "EnvConfig",
+) -> float:
+    """
+    Calculates the step reward based on the new specification (v3).
+
+    Args:
+        placed_count: Number of triangles successfully placed.
+        cleared_count: Number of unique triangles cleared this step.
+        is_game_over: Boolean indicating if the game ended *after* this step.
+        config: Environment configuration containing reward constants.
+
+    Returns:
+        The calculated step reward.
+    """
+    reward = 0.0
+
+    # 1. Placement Reward
+    reward += placed_count * config.REWARD_PER_PLACED_TRIANGLE
+
+    # 2. Line Clear Reward
+    reward += cleared_count * config.REWARD_PER_CLEARED_TRIANGLE
+
+    # 3. Survival Reward OR Game Over Penalty
+    if is_game_over:
+        # Apply penalty only if game ended THIS step
+        reward += config.PENALTY_GAME_OVER
+    else:
+        reward += config.REWARD_PER_STEP_ALIVE
+
+    logger.debug(
+        f"Calculated Reward: Placement({placed_count * config.REWARD_PER_PLACED_TRIANGLE:.3f}) "
+        f"+ LineClear({cleared_count * config.REWARD_PER_CLEARED_TRIANGLE:.3f}) "
+        f"+ {'GameOver' if is_game_over else 'Survival'}({config.PENALTY_GAME_OVER if is_game_over else config.REWARD_PER_STEP_ALIVE:.3f}) "
+        f"= {reward:.3f}"
+    )
+    return reward
+
+
+def execute_placement(
+    game_state: "GameState", shape_idx: int, r: int, c: int
+) -> tuple[int, int]:
+    """
+    Places a shape, clears lines, and updates grid/score state.
+    Refill logic and reward calculation are handled by the caller (GameState.step).
+
+    Args:
+        game_state: The current game state (will be modified).
+        shape_idx: Index of the shape to place.
+        r: Target row for placement.
+        c: Target column for placement.
+
+    Returns:
+        Tuple[int, int]: (cleared_triangle_count, placed_triangle_count)
+                         Stats needed for reward calculation.
+    Raises:
+        ValueError: If placement is invalid (should be pre-checked).
+        IndexError: If shape_idx is invalid.
+    """
+    if not (0 <= shape_idx < len(game_state.shapes)):
+        raise IndexError(f"Invalid shape index: {shape_idx}")
+
+    shape = game_state.shapes[shape_idx]
+    if not shape:
+        # This case should ideally be prevented by GameState.step checking valid_actions first.
+        logger.error(f"Attempted to place an empty shape slot: {shape_idx}")
+        raise ValueError("Cannot place an empty shape slot.")
+
+    # Check placement validity using GridLogic - raise error if invalid
+    if not GridLogic.can_place(game_state.grid_data, shape, r, c):
+        # This case should ideally be prevented by GameState.step checking valid_actions first.
+        logger.error(
+            f"Invalid placement attempted in execute_placement: Shape {shape_idx} at ({r},{c}). "
+            "This should have been caught earlier."
+        )
+        raise ValueError("Invalid placement location.")
+
+    # --- Place the shape ---
+    placed_coords: set[Coord] = set()
+    placed_count = 0
+    color_id = COLOR_TO_ID_MAP.get(shape.color, NO_COLOR_ID)
+    if color_id == NO_COLOR_ID:
+        # Use default color ID 0 if the test color isn't found
+        logger.warning(
+            f"Shape color {shape.color} not found in COLOR_TO_ID_MAP! Using ID 0."
+        )
+        color_id = 0
+
+    for dr, dc, _ in shape.triangles:
+        tri_r, tri_c = r + dr, c + dc
+        # Assume valid coordinates as can_place passed and raised error otherwise
+        game_state.grid_data._occupied_np[tri_r, tri_c] = True
+        game_state.grid_data._color_id_np[tri_r, tri_c] = color_id
+        placed_coords.add((tri_r, tri_c))
+        placed_count += 1
+
+    game_state.shapes[shape_idx] = None  # Remove shape from slot
+
+    # --- Check and clear lines ---
+    lines_cleared_count, unique_coords_cleared, _ = GridLogic.check_and_clear_lines(
+        game_state.grid_data, placed_coords
+    )
+    cleared_count = len(unique_coords_cleared)
+
+    # --- Update Score ---
+    game_state._game_score += placed_count + cleared_count * 2
+
+    # --- REMOVED REFILL LOGIC ---
+    # --- REMOVED REWARD CALCULATION ---
+
+    # Return stats needed by GameState.step for reward calculation
+    return cleared_count, placed_count

trianglengin/core/environment/shapes/__init__.py

@@ -0,0 +1,19 @@
+"""
+Shapes submodule handling shape generation and management.
+"""
+
+from .logic import (
+    generate_random_shape,
+    get_neighbors,
+    is_shape_connected,
+    refill_shape_slots,
+)
+from .templates import PREDEFINED_SHAPE_TEMPLATES
+
+__all__ = [
+    "generate_random_shape",
+    "refill_shape_slots",
+    "is_shape_connected",
+    "get_neighbors",
+    "PREDEFINED_SHAPE_TEMPLATES",
+]

trianglengin/core/environment/shapes/logic.py

@@ -0,0 +1,84 @@
+# File: trianglengin/trianglengin/core/environment/shapes/logic.py
+import logging
+import random
+from typing import TYPE_CHECKING
+
+from ...structs import SHAPE_COLORS, Shape  # Import from library's structs
+from .templates import PREDEFINED_SHAPE_TEMPLATES
+
+if TYPE_CHECKING:
+    # Use relative import for GameState within the library
+    from ..game_state import GameState
+
+logger = logging.getLogger(__name__)
+
+
+def generate_random_shape(rng: random.Random) -> Shape:
+    """Generates a random shape from predefined templates and colors."""
+    template = rng.choice(PREDEFINED_SHAPE_TEMPLATES)
+    color = rng.choice(SHAPE_COLORS)
+    return Shape(template, color)
+
+
+def refill_shape_slots(game_state: "GameState", rng: random.Random) -> None:
+    """
+    Refills ALL empty shape slots in the GameState, but ONLY if ALL slots are currently empty.
+    This implements batch refilling.
+    """
+    if all(shape is None for shape in game_state.shapes):
+        logger.debug("All shape slots are empty. Refilling all slots.")
+        for i in range(game_state.env_config.NUM_SHAPE_SLOTS):
+            game_state.shapes[i] = generate_random_shape(rng)
+            logger.debug(f"Refilled slot {i} with {game_state.shapes[i]}")
+    else:
+        logger.debug("Not all shape slots are empty. Skipping refill.")
+
+
+def get_neighbors(r: int, c: int, is_up: bool) -> list[tuple[int, int]]:
+    """Gets potential neighbor coordinates for connectivity check."""
+    if is_up:
+        # Up triangle neighbors: (r, c-1), (r, c+1), (r+1, c)
+        return [(r, c - 1), (r, c + 1), (r + 1, c)]
+    else:
+        # Down triangle neighbors: (r, c-1), (r, c+1), (r-1, c)
+        return [(r, c - 1), (r, c + 1), (r - 1, c)]
+
+
+def is_shape_connected(shape: Shape) -> bool:
+    """Checks if all triangles in a shape are connected using BFS."""
+    if not shape.triangles or len(shape.triangles) <= 1:
+        return True
+
+    # --- CORRECTED BFS LOGIC V2 ---
+    # Store the actual triangle tuples (r, c, is_up) in a set for quick lookup
+    all_triangles_set = set(shape.triangles)
+    # Also store just the coordinates for quick neighbor checking
+    all_coords_set = {(r, c) for r, c, _ in shape.triangles}
+
+    start_triangle = shape.triangles[0]  # (r, c, is_up)
+
+    visited: set[tuple[int, int, bool]] = set()
+    queue: list[tuple[int, int, bool]] = [start_triangle]
+    visited.add(start_triangle)
+
+    while queue:
+        current_r, current_c, current_is_up = queue.pop(0)
+
+        # Check neighbors based on the current triangle's orientation
+        for nr, nc in get_neighbors(current_r, current_c, current_is_up):
+            # Check if the neighbor *coordinate* exists in the shape
+            if (nr, nc) in all_coords_set:
+                # Find the full neighbor triangle tuple (r, c, is_up)
+                neighbor_triangle: tuple[int, int, bool] | None = None
+                for tri_tuple in all_triangles_set:
+                    if tri_tuple[0] == nr and tri_tuple[1] == nc:
+                        neighbor_triangle = tri_tuple
+                        break
+
+                # If the neighbor exists in the shape and hasn't been visited
+                if neighbor_triangle and neighbor_triangle not in visited:
+                    visited.add(neighbor_triangle)
+                    queue.append(neighbor_triangle)
+    # --- END CORRECTED BFS LOGIC V2 ---
+
+    return len(visited) == len(all_triangles_set)