trianglengin 2.0.1__pp310-pypy310_pp73-win_amd64.whl

trianglengin/__init__.py

@@ -0,0 +1,35 @@
+# Core engine exports
+from .config import EnvConfig
+from .game_interface import (
+    GameState,
+    Shape,
+)
+from .utils import ActionType, geometry
+
+__all__ = [
+    # Core Interface & Config
+    "GameState",
+    "Shape",
+    "EnvConfig",
+    # Utilities & Types
+    "utils",
+    "geometry",
+    "ActionType",
+]
+
+# Attempt to import the C++ module to make its version accessible (optional)
+try:
+    from . import trianglengin_cpp as _cpp_module
+
+    __version__ = _cpp_module.__version__
+except ImportError:
+    # If C++ module not found (e.g., during docs build without compilation)
+    # Try getting version from package metadata if installed
+    try:
+        from importlib.metadata import version
+
+        __version__ = version("trianglengin")
+    except ImportError:
+        __version__ = "unknown"  # Fallback
+    except Exception:
+        __version__ = "unknown (C++ module not found, package metadata failed)"

trianglengin/config/README.md

@@ -0,0 +1,38 @@
+
+
+# Core Configuration Module (`trianglengin.config`)
+
+## Purpose
+
+This module defines the core configuration settings for the `trianglengin` game engine, independent of any UI components.
+
+-   **[`env_config.py`](env_config.py):** Defines the `EnvConfig` Pydantic model. This class holds parameters crucial to the game simulation itself, such as:
+    -   Grid dimensions (`ROWS`, `COLS`).
+    -   Playable area definition (`PLAYABLE_RANGE_PER_ROW`).
+    -   Number of shape preview slots (`NUM_SHAPE_SLOTS`).
+    -   Reward/penalty values used by the C++ engine (`REWARD_PER_PLACED_TRIANGLE`, `REWARD_PER_CLEARED_TRIANGLE`, `REWARD_PER_STEP_ALIVE`, `PENALTY_GAME_OVER`).
+
+## Usage
+
+An instance of `EnvConfig` is typically created and passed to the `trianglengin.game_interface.GameState` wrapper during initialization. The wrapper then passes these settings to the underlying C++ engine.
+
+```python
+from trianglengin import GameState, EnvConfig
+
+# Use default configuration
+default_config = EnvConfig()
+game = GameState(config=default_config)
+
+# Use custom configuration
+custom_config = EnvConfig(ROWS=10, COLS=10, PLAYABLE_RANGE_PER_ROW=[(0,10)]*10)
+custom_game = GameState(config=custom_config)
+```
+
+## Dependencies
+
+-   **`pydantic`**: Used for data validation and settings management.
+-   **Standard Libraries:** `typing`.
+
+---
+
+**Note:** Configuration related to display or interactive UI elements (like screen size, FPS, fonts) is handled separately in the optional `trianglengin.ui.config` module.

trianglengin/config/__init__.py

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

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,62 @@
+# File: src/trianglengin/config/env_config.py
+
+from pydantic import BaseModel, Field, ValidationInfo, 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(  # Use List, Tuple
+        default=[(3, 12), (2, 13), (1, 14), (0, 15), (0, 15), (1, 14), (2, 13), (3, 12)]
+    )
+    NUM_SHAPE_SLOTS: int = Field(default=3, gt=0)
+
+    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)
+
+    @field_validator("PLAYABLE_RANGE_PER_ROW")
+    @classmethod
+    def check_playable_range_length(
+        cls,
+        v: list[tuple[int, int]],
+        info: ValidationInfo,  # Use List, Tuple
+    ) -> list[tuple[int, int]]:  # Use List, Tuple
+        """Validates PLAYABLE_RANGE_PER_ROW."""
+        rows = info.data.get("ROWS")
+        cols = info.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})."
+                )
+        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 = max(
+                (end for _, end in self.PLAYABLE_RANGE_PER_ROW), default=0
+            )
+            if max_end_col > self.COLS:
+                raise ValueError(
+                    f"COLS ({self.COLS}) must be >= max end_col ({max_end_col})"
+                )
+        return self

trianglengin/core/__init__.py

@@ -0,0 +1,10 @@
+# File: src/trianglengin/core/__init__.py
+# This module is now significantly smaller.
+# It might only contain the environment submodule placeholder if needed,
+# or be empty if environment is fully represented by game_interface.
+# Let's keep it minimal for now.
+
+# No submodules left to export directly from here in the new structure.
+# The main __init__.py exports the GameState interface.
+
+__all__: list[str] = []  # No public exports from this level anymore

trianglengin/cpp/CMakeLists.txt

@@ -0,0 +1,42 @@
+
+cmake_minimum_required(VERSION 3.14)
+project(trianglengin_cpp LANGUAGES CXX)
+
+# Locate Pybind11 using variables passed from setup.py (pybind11_DIR)
+find_package(pybind11 CONFIG REQUIRED)
+
+# Sources
+set(TRIANGLENGIN_SOURCES
+    bindings.cpp
+    game_state.cpp
+    grid_data.cpp
+    grid_logic.cpp
+    shape_logic.cpp
+    # Add other .cpp files if needed
+)
+
+# Build the pybind11 module
+pybind11_add_module(trianglengin_cpp MODULE ${TRIANGLENGIN_SOURCES})
+
+# C++17 Standard
+target_compile_features(trianglengin_cpp PRIVATE cxx_std_17)
+
+# Include directories (current source dir for headers)
+target_include_directories(trianglengin_cpp PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
+
+# Optimisation flags and visibility
+if(MSVC)
+  target_compile_options(trianglengin_cpp PRIVATE /O2 /W4) # Add warning level
+else()
+  target_compile_options(trianglengin_cpp PRIVATE -O3 -DNDEBUG -Wall -Wextra -pedantic) # Add warnings
+  # Symbol visibility for non-Apple Unix-like systems
+  if(NOT APPLE)
+    target_compile_options(trianglengin_cpp PRIVATE -fvisibility=hidden)
+  endif()
+endif()
+
+# Output directory is set via CMAKE_LIBRARY_OUTPUT_DIRECTORY in setup.py
+
+# --- Status Messages ---
+message(STATUS "pybind11 Include Dirs: ${pybind11_INCLUDE_DIRS}")
+message(STATUS "Building C++ extension for Trianglengin version ${TRIANGLENGIN_VERSION_INFO}")

trianglengin/cpp/bindings.cpp

@@ -0,0 +1,211 @@
+// File: src/trianglengin/cpp/bindings.cpp
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+#include <pybind11/operators.h>
+#include <pybind11/numpy.h>
+#include <pybind11/functional.h> // Needed for std::function with optional
+#include <vector>
+#include <stdexcept>
+#include <cstring>  // For memcpy with int8_t
+#include <optional> // Include optional
+
+#include "game_state.h"
+#include "config.h"
+#include "structs.h"
+
+namespace py = pybind11;
+namespace tg = trianglengin::cpp;
+
+// Helper to convert Python EnvConfig to C++ EnvConfigCpp
+tg::EnvConfigCpp python_to_cpp_env_config(const py::object &py_config)
+{
+  tg::EnvConfigCpp cpp_config;
+  try
+  {
+    cpp_config.rows = py_config.attr("ROWS").cast<int>();
+    cpp_config.cols = py_config.attr("COLS").cast<int>();
+    cpp_config.num_shape_slots = py_config.attr("NUM_SHAPE_SLOTS").cast<int>();
+
+    py::list py_ranges = py_config.attr("PLAYABLE_RANGE_PER_ROW").cast<py::list>();
+    cpp_config.playable_range_per_row.clear();
+    cpp_config.playable_range_per_row.reserve(py_ranges.size());
+    for (const auto &item : py_ranges)
+    {
+      py::tuple range_tuple = item.cast<py::tuple>();
+      if (range_tuple.size() != 2)
+        throw std::runtime_error("Playable range tuple must have 2 elements.");
+      cpp_config.playable_range_per_row.emplace_back(range_tuple[0].cast<int>(), range_tuple[1].cast<int>());
+    }
+    if (cpp_config.playable_range_per_row.size() != static_cast<size_t>(cpp_config.rows))
+    {
+      throw std::runtime_error("Mismatch between ROWS and PLAYABLE_RANGE_PER_ROW length.");
+    }
+
+    cpp_config.reward_per_placed_triangle = py_config.attr("REWARD_PER_PLACED_TRIANGLE").cast<double>();
+    cpp_config.reward_per_cleared_triangle = py_config.attr("REWARD_PER_CLEARED_TRIANGLE").cast<double>();
+    cpp_config.reward_per_step_alive = py_config.attr("REWARD_PER_STEP_ALIVE").cast<double>();
+    cpp_config.penalty_game_over = py_config.attr("PENALTY_GAME_OVER").cast<double>();
+    cpp_config.action_dim = cpp_config.num_shape_slots * cpp_config.rows * cpp_config.cols;
+  }
+  catch (const py::error_already_set &e)
+  {
+    throw std::runtime_error(std::string("Error accessing EnvConfig attributes: ") + e.what());
+  }
+  catch (const std::exception &e)
+  {
+    throw std::runtime_error(std::string("Error converting EnvConfig: ") + e.what());
+  }
+  return cpp_config;
+}
+
+// Helper to convert C++ optional<ShapeCpp> to Python tuple or None
+py::object cpp_shape_to_python(const std::optional<tg::ShapeCpp> &shape_opt)
+{
+  if (!shape_opt)
+    return py::none();
+  const auto &shape = shape_opt.value();
+  py::list triangles_py;
+  for (const auto &tri : shape.triangles)
+  {
+    triangles_py.append(py::make_tuple(std::get<0>(tri), std::get<1>(tri), std::get<2>(tri)));
+  }
+  py::tuple color_py = py::make_tuple(std::get<0>(shape.color), std::get<1>(shape.color), std::get<2>(shape.color));
+  return py::make_tuple(triangles_py, color_py, shape.color_id);
+}
+
+// Helper to convert Python tuple (or None) to C++ optional<ShapeCpp>
+std::optional<tg::ShapeCpp> python_to_cpp_shape(const py::object &shape_py)
+{
+  if (shape_py.is_none())
+  {
+    return std::nullopt;
+  }
+  try
+  {
+    py::tuple shape_tuple = shape_py.cast<py::tuple>();
+    if (shape_tuple.size() != 3)
+    {
+      throw std::runtime_error("Shape tuple must have 3 elements (triangles, color, id).");
+    }
+
+    py::list tris_py = shape_tuple[0].cast<py::list>();
+    py::tuple color_py = shape_tuple[1].cast<py::tuple>();
+    int id_py = shape_tuple[2].cast<int>();
+
+    std::vector<tg::TriangleData> tris_cpp;
+    tris_cpp.reserve(tris_py.size());
+    for (const auto &tri_item : tris_py)
+    {
+      py::tuple tri_tuple = tri_item.cast<py::tuple>();
+      if (tri_tuple.size() != 3)
+      {
+        throw std::runtime_error("Triangle tuple must have 3 elements (dr, dc, is_up).");
+      }
+      tris_cpp.emplace_back(tri_tuple[0].cast<int>(), tri_tuple[1].cast<int>(), tri_tuple[2].cast<bool>());
+    }
+
+    if (color_py.size() != 3)
+    {
+      throw std::runtime_error("Color tuple must have 3 elements (r, g, b).");
+    }
+    tg::ColorCpp color_cpp = {color_py[0].cast<int>(), color_py[1].cast<int>(), color_py[2].cast<int>()};
+
+    return tg::ShapeCpp(std::move(tris_cpp), color_cpp, id_py);
+  }
+  catch (const py::error_already_set &e)
+  {
+    throw std::runtime_error(std::string("Error converting Python shape to C++: ") + e.what());
+  }
+  catch (const std::exception &e)
+  {
+    throw std::runtime_error(std::string("Error converting Python shape to C++: ") + e.what());
+  }
+}
+
+PYBIND11_MODULE(trianglengin_cpp, m)
+{
+  m.doc() = "C++ core module for Trianglengin";
+
+  py::class_<tg::GameStateCpp>(m, "GameStateCpp")
+      .def(py::init([](const py::object &py_config, unsigned int seed)
+                    {
+                 tg::EnvConfigCpp cpp_config = python_to_cpp_env_config(py_config);
+                 return std::make_unique<tg::GameStateCpp>(cpp_config, seed); }),
+           py::arg("config"), py::arg("initial_seed"))
+      .def("reset", &tg::GameStateCpp::reset)
+      .def("step", &tg::GameStateCpp::step, py::arg("action"))
+      .def("is_over", &tg::GameStateCpp::is_over)
+      .def("get_score", &tg::GameStateCpp::get_score)
+      .def("get_valid_actions", &tg::GameStateCpp::get_valid_actions, py::arg("force_recalculate") = false, py::return_value_policy::reference_internal)
+      .def("get_current_step", &tg::GameStateCpp::get_current_step)
+      .def("get_game_over_reason", &tg::GameStateCpp::get_game_over_reason)
+      .def("get_shapes_cpp", [](const tg::GameStateCpp &gs)
+           {
+            py::list shapes_list;
+            for(const auto& shape_opt : gs.get_shapes()) {
+                shapes_list.append(cpp_shape_to_python(shape_opt));
+            }
+            return shapes_list; })
+      .def("get_grid_occupied_flat", [](const tg::GameStateCpp &gs)
+           {
+            const auto& grid = gs.get_grid_data().get_occupied_grid();
+            size_t rows = grid.size();
+            size_t cols = (rows > 0) ? grid[0].size() : 0;
+            py::array_t<bool> result({rows, cols});
+            auto buf = result.request();
+            bool *ptr = static_cast<bool *>(buf.ptr);
+            // Manual copy for std::vector<bool>
+            for (size_t r = 0; r < rows; ++r) {
+                for (size_t c = 0; c < cols; ++c) {
+                    ptr[r * cols + c] = grid[r][c];
+                }
+            }
+            return result; })
+      .def("get_grid_colors_flat", [](const tg::GameStateCpp &gs)
+           {
+            const auto& grid = gs.get_grid_data().get_color_id_grid();
+            size_t rows = grid.size();
+            size_t cols = (rows > 0) ? grid[0].size() : 0;
+            py::array_t<int8_t> result({rows, cols});
+            auto buf = result.request();
+            int8_t *ptr = static_cast<int8_t *>(buf.ptr);
+             // memcpy is fine for int8_t
+             for (size_t r = 0; r < rows; ++r) {
+                std::memcpy(ptr + r * cols, grid[r].data(), cols * sizeof(int8_t));
+            }
+            return result; })
+      .def("get_grid_death_flat", [](const tg::GameStateCpp &gs)
+           {
+            const auto& grid = gs.get_grid_data().get_death_grid();
+            size_t rows = grid.size();
+            size_t cols = (rows > 0) ? grid[0].size() : 0;
+            py::array_t<bool> result({rows, cols});
+            auto buf = result.request();
+            bool *ptr = static_cast<bool *>(buf.ptr);
+            // Manual copy for std::vector<bool>
+             for (size_t r = 0; r < rows; ++r) {
+                for (size_t c = 0; c < cols; ++c) {
+                    ptr[r * cols + c] = grid[r][c];
+                }
+            }
+            return result; })
+      .def("copy", &tg::GameStateCpp::copy)
+      .def("debug_toggle_cell", &tg::GameStateCpp::debug_toggle_cell, py::arg("r"), py::arg("c"))
+      // Add binding for debug_set_shapes
+      .def("debug_set_shapes", [](tg::GameStateCpp &gs, const py::list &shapes_py)
+           {
+            std::vector<std::optional<tg::ShapeCpp>> shapes_cpp;
+            shapes_cpp.reserve(shapes_py.size());
+            for(const auto& shape_item_handle : shapes_py) {
+                // Cast handle to object before passing to conversion function
+                py::object shape_item = py::reinterpret_borrow<py::object>(shape_item_handle);
+                shapes_cpp.push_back(python_to_cpp_shape(shape_item));
+            }
+            gs.debug_set_shapes(shapes_cpp); }, py::arg("new_shapes"), "Sets the shapes in the preview slots directly (for debugging/testing).");
+
+#ifdef VERSION_INFO
+  m.attr("__version__") = VERSION_INFO;
+#else
+  m.attr("__version__") = "dev";
+#endif
+}

trianglengin/cpp/config.h

@@ -0,0 +1,28 @@
+// File: src/trianglengin/cpp/config.h
+#ifndef TRIANGLENGIN_CPP_CONFIG_H
+#define TRIANGLENGIN_CPP_CONFIG_H
+
+#pragma once
+
+#include <vector>
+#include <tuple>
+#include <cstdint>
+
+namespace trianglengin::cpp
+{
+  struct EnvConfigCpp
+  {
+    int rows = 8;
+    int cols = 15;
+    std::vector<std::tuple<int, int>> playable_range_per_row = {
+        {3, 12}, {2, 13}, {1, 14}, {0, 15}, {0, 15}, {1, 14}, {2, 13}, {3, 12}};
+    int num_shape_slots = 3;
+    double reward_per_placed_triangle = 0.01;
+    double reward_per_cleared_triangle = 0.5;
+    double reward_per_step_alive = 0.005;
+    double penalty_game_over = -10.0;
+    int action_dim = 0;
+  };
+} // namespace trianglengin::cpp
+
+#endif // TRIANGLENGIN_CPP_CONFIG_H