trianglengin 1.0.6__py3-none-any.whl

tests/conftest.py

@@ -0,0 +1,108 @@
+# File: trianglengin/tests/conftest.py
+import random
+from typing import TYPE_CHECKING
+
+import numpy as np
+import pytest
+
+# Import directly from the library being tested
+from trianglengin.config import EnvConfig
+from trianglengin.core.environment import GameState
+from trianglengin.core.structs import Shape
+from trianglengin.visualization.core.colors import Color
+
+if TYPE_CHECKING:
+    from trianglengin.core.environment.grid import GridData
+
+
+# Use default NumPy random number generator
+rng = np.random.default_rng()
+
+# Default color for fixture shapes
+DEFAULT_TEST_COLOR: Color = (100, 100, 100)
+
+
+@pytest.fixture(scope="session")
+def default_env_config() -> EnvConfig:
+    """Provides the default EnvConfig used in the specification (session-scoped)."""
+    return EnvConfig()
+
+
+@pytest.fixture
+def game_state(default_env_config: EnvConfig) -> GameState:
+    """Provides a fresh GameState instance for testing."""
+    return GameState(config=default_env_config, initial_seed=123)
+
+
+@pytest.fixture
+def game_state_with_fixed_shapes() -> GameState:
+    """
+    Provides a game state with predictable initial shapes on a 3x3 grid.
+    """
+    # Create a specific 3x3 config for this fixture
+    config_3x3 = EnvConfig(
+        ROWS=3,
+        COLS=3,
+        PLAYABLE_RANGE_PER_ROW=[(0, 3), (0, 3), (0, 3)],  # Full 3x3 is playable
+        NUM_SHAPE_SLOTS=3,
+    )
+    gs = GameState(config=config_3x3, initial_seed=456)
+
+    # Override the random shapes with fixed ones for testing placement/refill
+    fixed_shapes = [
+        Shape([(0, 0, False)], DEFAULT_TEST_COLOR),  # Single down
+        Shape([(0, 0, True)], DEFAULT_TEST_COLOR),  # Single up
+        Shape(
+            [(0, 0, False), (1, 0, False)], DEFAULT_TEST_COLOR
+        ),  # Two downs (vertical)
+    ]
+    assert len(fixed_shapes) == gs.env_config.NUM_SHAPE_SLOTS
+
+    # Assign copies of the shapes to the game state
+    gs.shapes = [shape.copy() for shape in fixed_shapes]
+
+    # Force recalculation of valid actions after manually setting shapes
+    gs.valid_actions(force_recalculate=True)
+    return gs
+
+
+@pytest.fixture
+def simple_shape() -> Shape:
+    """Provides a simple 3-triangle connected shape (Down, Up, Down)."""
+    triangles = [(0, 0, False), (0, 1, True), (1, 1, False)]
+    color = (255, 0, 0)
+    return Shape(triangles, color)
+
+
+@pytest.fixture
+def grid_data(default_env_config: EnvConfig) -> "GridData":
+    """Provides a fresh GridData instance using the default config."""
+    from trianglengin.core.environment.grid import GridData
+
+    return GridData(config=default_env_config)
+
+
+@pytest.fixture
+def game_state_almost_full(default_env_config: EnvConfig) -> GameState:
+    """
+    Provides a game state (default config) where only a few placements are possible.
+    Grid is filled completely, then specific spots are made empty.
+    """
+    gs = GameState(config=default_env_config, initial_seed=987)
+    playable_mask = ~gs.grid_data._death_np
+    gs.grid_data._occupied_np[playable_mask] = True
+    empty_spots = [(0, 4), (0, 5)]  # Example empty spots
+    for r_empty, c_empty in empty_spots:
+        if (
+            gs.grid_data.valid(r_empty, c_empty)
+            and not gs.grid_data._death_np[r_empty, c_empty]
+        ):
+            gs.grid_data._occupied_np[r_empty, c_empty] = False
+            gs.grid_data._color_id_np[r_empty, c_empty] = -1
+    return gs
+
+
+@pytest.fixture
+def fixed_rng() -> random.Random:
+    """Provides a Random instance with a fixed seed."""
+    return random.Random(12345)

tests/core/__init__.py

@@ -0,0 +1,2 @@
+# File: trianglengin/tests/core/__init__.py
+# This file can be empty

tests/core/environment/README.md

@@ -0,0 +1,47 @@
+# File: trianglengin/trianglengin/core/environment/grid/README.md
+# Environment Grid Submodule (`trianglengin.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 `Triangle` class (defined in [`trianglengin.core.structs`](../../structs/README.md)) represents a single cell, storing its position and orientation (`is_up`). The actual state (occupied, death, color) is managed within `GridData`.
+-   **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 also manages precomputed information about potential lines (sets of coordinates) for efficient clearing checks.
+-   **Grid Logic:** The [`logic.py`](logic.py) module (exposed as `GridLogic`) contains functions operating on `GridData`. This includes:
+    -   Initializing the grid based on `EnvConfig` (defining death zones).
+    -   Precomputing potential lines (`_precompute_lines`) and indexing them (`_initialize_lines_and_index`) for efficient checking.
+    -   Checking if a shape can be placed (`can_place`), **including matching triangle orientations**.
+    -   Checking for and clearing completed lines (`check_and_clear_lines`). **This function does NOT implement gravity.**
+-   **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 the main `alphatriangle` project's features module.
+
+## Exposed Interfaces
+
+-   **Classes:**
+    -   `GridData`: Holds the grid state using NumPy arrays.
+        -   `__init__(config: EnvConfig)`
+        -   `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) -> int`
+        -   `get_occupied_state() -> np.ndarray`
+        -   `get_death_state() -> np.ndarray`
+        -   `get_color_id_state() -> np.ndarray`
+        -   `deepcopy() -> GridData`
+-   **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)**
+
+## Dependencies
+
+-   **[`trianglengin.config`](../../../config/README.md)**:
+    -   `EnvConfig`: Used by `GridData` initialization and logic functions.
+-   **[`trianglengin.core.structs`](../../structs/README.md)**:
+    -   Uses `Triangle`, `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.

tests/core/environment/__init__.py

@@ -0,0 +1,2 @@
+# File: trianglengin/tests/core/environment/__init__.py
+# This file can be empty

tests/core/environment/test_action_codec.py

@@ -0,0 +1,50 @@
+import pytest
+
+# Import directly from the library being tested
+from trianglengin.config import EnvConfig
+from trianglengin.core.environment.action_codec import decode_action, encode_action
+
+# Use fixtures from the local conftest.py
+# Fixtures are implicitly injected by pytest
+
+
+def test_encode_decode_action(default_env_config: EnvConfig):
+    """Test encoding and decoding actions."""
+    config = default_env_config
+    # Test some valid actions
+    actions_to_test = [
+        (0, 0, 0),
+        (config.NUM_SHAPE_SLOTS - 1, config.ROWS - 1, config.COLS - 1),
+        (0, config.ROWS // 2, config.COLS // 2),
+    ]
+    for shape_idx, r, c in actions_to_test:
+        encoded = encode_action(shape_idx, r, c, config)
+        decoded_shape_idx, decoded_r, decoded_c = decode_action(encoded, config)
+        assert (shape_idx, r, c) == (decoded_shape_idx, decoded_r, decoded_c)
+
+
+def test_encode_action_invalid_input(default_env_config: EnvConfig):
+    """Test encoding with invalid inputs."""
+    config = default_env_config
+    with pytest.raises(ValueError):
+        encode_action(-1, 0, 0, config)  # Invalid shape index
+    with pytest.raises(ValueError):
+        encode_action(config.NUM_SHAPE_SLOTS, 0, 0, config)  # Invalid shape index
+    with pytest.raises(ValueError):
+        encode_action(0, -1, 0, config)  # Invalid row
+    with pytest.raises(ValueError):
+        encode_action(0, config.ROWS, 0, config)  # Invalid row
+    with pytest.raises(ValueError):
+        encode_action(0, 0, -1, config)  # Invalid col
+    with pytest.raises(ValueError):
+        encode_action(0, 0, config.COLS, config)  # Invalid col
+
+
+def test_decode_action_invalid_input(default_env_config: EnvConfig):
+    """Test decoding with invalid inputs."""
+    config = default_env_config
+    action_dim = int(config.ACTION_DIM)  # type: ignore[call-overload]
+    with pytest.raises(ValueError):
+        decode_action(-1, config)  # Invalid action index
+    with pytest.raises(ValueError):
+        decode_action(action_dim, config)  # Invalid action index (out of bounds)