trianglengin 2.0.6__cp310-cp310-win32.whl → 2.0.7__cp310-cp310-win32.whl

trianglengin/cpp/bindings.cpp

@@ -1,13 +1,14 @@
+
 // 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 <pybind11/functional.h>
 #include <vector>
 #include <stdexcept>
-#include <cstring>  // For memcpy with int8_t
-#include <optional> // Include optional
+#include <cstring>
+#include <optional>
 
 #include "game_state.h"
 #include "config.h"
@@ -138,6 +139,7 @@ PYBIND11_MODULE(trianglengin_cpp, m)
       .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_last_cleared_triangles", &tg::GameStateCpp::get_last_cleared_triangles) // Added binding
       .def("get_game_over_reason", &tg::GameStateCpp::get_game_over_reason)
       .def("get_shapes_cpp", [](const tg::GameStateCpp &gs)
            {
@@ -154,7 +156,6 @@ PYBIND11_MODULE(trianglengin_cpp, m)
             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];
@@ -169,7 +170,6 @@ PYBIND11_MODULE(trianglengin_cpp, m)
             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));
             }
@@ -182,7 +182,6 @@ PYBIND11_MODULE(trianglengin_cpp, m)
             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];
@@ -191,13 +190,11 @@ PYBIND11_MODULE(trianglengin_cpp, m)
             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));
             }

trianglengin/cpp/game_state.cpp

@@ -1,10 +1,11 @@
+
 // File: src/trianglengin/cpp/game_state.cpp
 #include "game_state.h"
 #include "grid_logic.h"
 #include "shape_logic.h"
 #include <stdexcept>
 #include <numeric>
-#include <iostream>  // Keep iostream if other debug logs might be added later, or remove if not needed
+#include <iostream>
 #include <algorithm> // For std::min
 
 namespace trianglengin::cpp
@@ -12,10 +13,11 @@ namespace trianglengin::cpp
 
   GameStateCpp::GameStateCpp(const EnvConfigCpp &config, unsigned int initial_seed)
       : config_(config),
-        grid_data_(config_), // Initialize GridData with config
+        grid_data_(config_),
         shapes_(config_.num_shape_slots),
         score_(0.0),
         current_step_(0),
+        last_cleared_triangles_(0), // Initialize added member
         game_over_(false),
         rng_(initial_seed)
   {
@@ -24,17 +26,17 @@ namespace trianglengin::cpp
 
   // --- Explicit Copy Constructor ---
   GameStateCpp::GameStateCpp(const GameStateCpp &other)
-      : config_(other.config_),                           // Copy config
-        grid_data_(other.grid_data_),                     // Use GridData's copy constructor
-        shapes_(other.shapes_),                           // Copy vector of optional shapes
-        score_(other.score_),                             // Copy score
-        current_step_(other.current_step_),               // Copy step
-        game_over_(other.game_over_),                     // Copy game over flag
-        game_over_reason_(other.game_over_reason_),       // Copy reason
-        valid_actions_cache_(other.valid_actions_cache_), // Copy the optional cache
-        rng_(other.rng_)                                  // Copy the RNG state
+      : config_(other.config_),
+        grid_data_(other.grid_data_),
+        shapes_(other.shapes_),
+        score_(other.score_),
+        current_step_(other.current_step_),
+        last_cleared_triangles_(other.last_cleared_triangles_), // Copy added member
+        game_over_(other.game_over_),
+        game_over_reason_(other.game_over_reason_),
+        valid_actions_cache_(other.valid_actions_cache_),
+        rng_(other.rng_)
   {
-    // No additional logic needed if members handle their own copying well
   }
 
   // --- Explicit Copy Assignment Operator ---
@@ -43,14 +45,15 @@ namespace trianglengin::cpp
     if (this != &other)
     {
       config_ = other.config_;
-      grid_data_ = other.grid_data_; // Use GridData's copy assignment
+      grid_data_ = other.grid_data_;
       shapes_ = other.shapes_;
       score_ = other.score_;
       current_step_ = other.current_step_;
+      last_cleared_triangles_ = other.last_cleared_triangles_; // Copy added member
       game_over_ = other.game_over_;
       game_over_reason_ = other.game_over_reason_;
-      valid_actions_cache_ = other.valid_actions_cache_; // Copy the optional cache
-      rng_ = other.rng_;                                 // Copy the RNG state
+      valid_actions_cache_ = other.valid_actions_cache_;
+      rng_ = other.rng_;
     }
     return *this;
   }
@@ -61,6 +64,7 @@ namespace trianglengin::cpp
     std::fill(shapes_.begin(), shapes_.end(), std::nullopt);
     score_ = 0.0;
     current_step_ = 0;
+    last_cleared_triangles_ = 0; // Reset added member
     game_over_ = false;
     game_over_reason_ = std::nullopt;
     valid_actions_cache_ = std::nullopt;
@@ -70,27 +74,24 @@ namespace trianglengin::cpp
 
   void GameStateCpp::check_initial_state_game_over()
   {
-    // Force calculation which updates the cache and potentially the game_over flag
     get_valid_actions(true);
-    // No need to check cache emptiness here, get_valid_actions handles setting the flag
   }
 
   std::tuple<double, bool> GameStateCpp::step(Action action)
   {
+    last_cleared_triangles_ = 0; // Reset before potential clearing
+
     if (game_over_)
     {
       return {0.0, true};
     }
 
-    // Ensure cache is populated before checking the action
-    const auto &valid_actions = get_valid_actions(); // This populates cache if needed
+    const auto &valid_actions = get_valid_actions();
 
-    // Check against the (now guaranteed) populated cache
     if (valid_actions.find(action) == valid_actions.end())
     {
-      // Invalid action detected
       force_game_over("Invalid action provided: " + std::to_string(action));
-      score_ += config_.penalty_game_over; // Apply penalty
+      score_ += config_.penalty_game_over;
       return {config_.penalty_game_over, true};
     }
 
@@ -115,7 +116,6 @@ namespace trianglengin::cpp
 
     const ShapeCpp &shape_to_place = shapes_[shape_idx].value();
 
-    // Re-check placement just before modification (defensive)
     if (!grid_logic::can_place(grid_data_, shape_to_place, r, c))
     {
       force_game_over("Placement check failed for valid action (logic error?). Action: " + std::to_string(action));
@@ -135,7 +135,6 @@ namespace trianglengin::cpp
       std::tie(dr, dc, is_up_ignored) = tri_data;
       int target_r = r + dr;
       int target_c = c + dc;
-      // Bounds check should be implicitly handled by can_place, but double-check
       if (!grid_data_.is_valid(target_r, target_c) || grid_data_.is_death(target_r, target_c))
       {
         force_game_over("Attempted placement out of bounds/death zone during execution. Action: " + std::to_string(action));
@@ -147,7 +146,7 @@ namespace trianglengin::cpp
       newly_occupied_coords.insert({target_r, target_c});
       placed_count++;
     }
-    shapes_[shape_idx] = std::nullopt; // Clear the used shape slot
+    shapes_[shape_idx] = std::nullopt;
 
     // --- Line Clearing ---
     int lines_cleared_count;
@@ -156,6 +155,7 @@ namespace trianglengin::cpp
     std::tie(lines_cleared_count, cleared_coords, cleared_lines_fs) =
         grid_logic::check_and_clear_lines(grid_data_, newly_occupied_coords);
     int cleared_count = static_cast<int>(cleared_coords.size());
+    last_cleared_triangles_ = cleared_count; // Store cleared count
 
     // --- Refill ---
     bool all_slots_empty = true;
@@ -174,8 +174,8 @@ namespace trianglengin::cpp
 
     // --- Update State & Check Game Over ---
     current_step_++;
-    invalidate_action_cache(); // Invalidate cache AFTER state changes
-    get_valid_actions(true);   // Force recalculation AND update game_over_ flag if needed
+    invalidate_action_cache();
+    get_valid_actions(true);
 
     // --- Calculate Reward & Update Score ---
     double reward = 0.0;
@@ -184,23 +184,19 @@ namespace trianglengin::cpp
 
     if (game_over_)
     {
-      // Penalty was applied earlier if game over was due to invalid action this step.
-      // If game over is due to lack of actions *after* this step, no penalty applies here.
+      // Penalty already applied if game over was due to invalid action this step.
     }
     else
     {
       reward += config_.reward_per_step_alive;
     }
-    score_ += reward; // Update score based on calculated reward
+    score_ += reward;
 
-    return {reward, game_over_}; // Return the potentially updated game_over_ flag
+    return {reward, game_over_};
   }
 
-  // --- Simplified is_over ---
   bool GameStateCpp::is_over() const
   {
-    // The game_over_ flag is the single source of truth.
-    // It's updated by step() [via get_valid_actions()] and reset().
     return game_over_;
   }
 
@@ -210,7 +206,7 @@ namespace trianglengin::cpp
     {
       game_over_ = true;
       game_over_reason_ = reason;
-      valid_actions_cache_ = std::set<Action>(); // Clear valid actions on game over
+      valid_actions_cache_ = std::set<Action>();
     }
   }
 
@@ -221,10 +217,8 @@ namespace trianglengin::cpp
 
   const std::set<Action> &GameStateCpp::get_valid_actions(bool force_recalculate)
   {
-    // If game is over, always return the cached empty set
     if (game_over_)
     {
-      // Ensure cache is empty if game_over is true
       if (!valid_actions_cache_.has_value() || !valid_actions_cache_->empty())
       {
         valid_actions_cache_ = std::set<Action>();
@@ -232,23 +226,18 @@ namespace trianglengin::cpp
       return *valid_actions_cache_;
     }
 
-    // If not forcing and cache exists, return it
     if (!force_recalculate && valid_actions_cache_.has_value())
     {
       return *valid_actions_cache_;
     }
 
-    // Otherwise, calculate (which updates the mutable cache)
     calculate_valid_actions_internal();
 
-    // Check if the calculation resulted in no valid actions, triggering game over
     if (!game_over_ && valid_actions_cache_->empty())
     {
-      // Set the game over flag HERE, as this is the definitive check after calculation
       force_game_over("No valid actions available.");
     }
 
-    // Return the calculated (and potentially now empty) cache
     return *valid_actions_cache_;
   }
 
@@ -257,11 +246,8 @@ namespace trianglengin::cpp
     valid_actions_cache_ = std::nullopt;
   }
 
-  // calculate_valid_actions_internal remains const, modifies mutable cache
   void GameStateCpp::calculate_valid_actions_internal() const
   {
-    // This function should NOT set game_over_ directly.
-    // It just calculates the set. The caller (get_valid_actions) checks if empty.
     std::set<Action> valid_actions;
     for (int shape_idx = 0; shape_idx < static_cast<int>(shapes_.size()); ++shape_idx)
     {
@@ -270,7 +256,6 @@ namespace trianglengin::cpp
       const ShapeCpp &shape = shapes_[shape_idx].value();
       for (int r = 0; r < config_.rows; ++r)
       {
-        // Optimization: Check only within playable range? No, C++ can_place handles death zones.
         for (int c = 0; c < config_.cols; ++c)
         {
           if (grid_logic::can_place(grid_data_, shape, r, c))
@@ -280,13 +265,13 @@ namespace trianglengin::cpp
         }
       }
     }
-    valid_actions_cache_ = std::move(valid_actions); // Update the mutable cache
+    valid_actions_cache_ = std::move(valid_actions);
   }
 
   int GameStateCpp::get_current_step() const { return current_step_; }
+  int GameStateCpp::get_last_cleared_triangles() const { return last_cleared_triangles_; } // Added implementation
   std::optional<std::string> GameStateCpp::get_game_over_reason() const { return game_over_reason_; }
 
-  // Python-facing copy method uses the C++ copy constructor
   GameStateCpp GameStateCpp::copy() const
   {
     return GameStateCpp(*this);
@@ -301,13 +286,14 @@ namespace trianglengin::cpp
       bool was_occupied = occupied_grid[r][c];
       occupied_grid[r][c] = !was_occupied;
       color_grid[r][c] = was_occupied ? NO_COLOR_ID : DEBUG_COLOR_ID;
+      last_cleared_triangles_ = 0; // Reset cleared count after manual toggle
       if (!was_occupied)
       {
         // Check for line clears only if a cell becomes occupied
-        grid_logic::check_and_clear_lines(grid_data_, {{r, c}});
+        auto clear_result = grid_logic::check_and_clear_lines(grid_data_, {{r, c}});
+        last_cleared_triangles_ = static_cast<int>(std::get<1>(clear_result).size());
       }
-      invalidate_action_cache(); // Always invalidate after manual change
-      // Force recalculation of valid actions and game over state after toggle
+      invalidate_action_cache();
       get_valid_actions(true);
     }
   }
@@ -324,18 +310,14 @@ namespace trianglengin::cpp
       shapes_[i] = std::nullopt;
     }
     invalidate_action_cache();
-    // Force recalculation of valid actions and game over state after setting shapes
     get_valid_actions(true);
   }
 
   Action GameStateCpp::encode_action(int shape_idx, int r, int c) const
   {
     int grid_size = config_.rows * config_.cols;
-    // Basic bounds check (more robust check in can_place)
     if (shape_idx < 0 || shape_idx >= config_.num_shape_slots || r < 0 || r >= config_.rows || c < 0 || c >= config_.cols)
     {
-      // This case should ideally not be reached if called after can_place
-      // Return an invalid action index or throw? Let's throw for internal logic errors.
       throw std::out_of_range("encode_action arguments out of range during valid action calculation.");
     }
     return shape_idx * grid_size + r * config_.cols + c;

trianglengin/cpp/game_state.h

@@ -1,4 +1,4 @@
-// File: src/trianglengin/cpp/game_state.h
+
 #ifndef TRIANGLENGIN_CPP_GAME_STATE_H
 #define TRIANGLENGIN_CPP_GAME_STATE_H
 
@@ -40,6 +40,7 @@ namespace trianglengin::cpp
     double get_score() const;
     const std::set<Action> &get_valid_actions(bool force_recalculate = false);
     int get_current_step() const;
+    int get_last_cleared_triangles() const; // Added getter
     std::optional<std::string> get_game_over_reason() const;
     GameStateCpp copy() const; // Keep Python-facing copy method
     void debug_toggle_cell(int r, int c);
@@ -62,6 +63,7 @@ namespace trianglengin::cpp
     std::vector<std::optional<ShapeCpp>> shapes_;
     double score_;
     int current_step_;
+    int last_cleared_triangles_; // Added member
     bool game_over_;
     std::optional<std::string> game_over_reason_;
     mutable std::optional<std::set<Action>> valid_actions_cache_; // Mutable for const getter

trianglengin/game_interface.py

@@ -1,14 +1,13 @@
 # File: src/trianglengin/game_interface.py
 import logging
 import random
-from typing import Any, cast  # Import necessary types
+from typing import Any, cast
 
 import numpy as np
 
 from .config import EnvConfig
 
 try:
-    # Keep the alias for clarity within this file
     import trianglengin.trianglengin_cpp as cpp_module
 except ImportError as e:
     raise ImportError(
@@ -27,7 +26,6 @@ class Shape:
         color: tuple[int, int, int],
         color_id: int,
     ):
-        # Sort triangles for consistent representation and hashing
         self.triangles: list[tuple[int, int, bool]] = sorted(triangles)
         self.color: tuple[int, int, int] = color
         self.color_id: int = color_id
@@ -42,13 +40,11 @@ class Shape:
 
     def copy(self) -> "Shape":
         """Creates a shallow copy."""
-        # Use sorted triangles in the copy as well
         return Shape(list(self.triangles), self.color, self.color_id)
 
     def __eq__(self, other: object) -> bool:
         if not isinstance(other, Shape):
             return NotImplemented
-        # Comparison relies on sorted triangles
         return (
             self.triangles == other.triangles
             and self.color == other.color
@@ -56,7 +52,6 @@ class Shape:
         )
 
     def __hash__(self) -> int:
-        # Hash relies on sorted triangles (converted to tuple)
         return hash((tuple(self.triangles), self.color, self.color_id))
 
     def __str__(self) -> str:
@@ -78,7 +73,7 @@ class GameState:
     Provides a Pythonic interface to the core game logic.
     """
 
-    _cpp_state: cpp_module.GameStateCpp  # Add type hint for instance variable
+    _cpp_state: cpp_module.GameStateCpp
 
     def __init__(
         self, config: EnvConfig | None = None, initial_seed: int | None = None
@@ -88,7 +83,6 @@ class GameState:
             initial_seed if initial_seed is not None else random.randint(0, 2**32 - 1)
         )
         try:
-            # Pass the EnvConfig object directly to the C++ constructor binding
             self._cpp_state = cpp_module.GameStateCpp(self.env_config, used_seed)
         except Exception as e:
             log.exception(f"Failed to initialize C++ GameStateCpp: {e}")
@@ -108,24 +102,19 @@ class GameState:
         Returns: (reward, done)
         """
         try:
-            # The C++ method already returns tuple[double, bool], cast might be redundant
-            # if pybind handles it, but explicit cast helps mypy if stub is missing details.
             reward, done = cast("tuple[float, bool]", self._cpp_state.step(action))
             self._clear_caches()
             return reward, done
         except Exception as e:
             log.exception(f"Error during C++ step execution for action {action}: {e}")
-            # Return penalty and done=True consistent with C++ logic for errors during step
             return self.env_config.PENALTY_GAME_OVER, True
 
     def is_over(self) -> bool:
         """Checks if the game is over."""
-        # C++ returns bool, cast might be redundant but safe for mypy
         return cast("bool", self._cpp_state.is_over())
 
     def game_score(self) -> float:
         """Returns the current accumulated score."""
-        # C++ returns double, cast might be redundant but safe for mypy
         return cast("float", self._cpp_state.get_score())
 
     def get_outcome(self) -> float:
@@ -134,18 +123,14 @@ class GameState:
         Required by MCTS implementations like trimcts.
         """
         if self.is_over():
-            # In this game, the final score is the outcome.
-            # Adjust if a different outcome definition is needed (e.g., +1 win, -1 loss).
             return self.game_score()
         else:
-            # MCTS typically expects 0 for non-terminal states during simulation.
             return 0.0
 
     def valid_actions(self, force_recalculate: bool = False) -> set[int]:
         """
         Returns a set of valid encoded action indices for the current state.
         """
-        # C++ returns std::set<int>, pybind converts to Python set. Cast is safe.
         return cast(
             "set[int]", set(self._cpp_state.get_valid_actions(force_recalculate))
         )
@@ -153,14 +138,12 @@ class GameState:
     def get_shapes(self) -> list[Shape | None]:
         """Returns the list of current shapes in the preview slots."""
         if self._cached_shapes is None:
-            # C++ returns list[Optional[tuple[list[tuple], tuple, int]]]
             shapes_data = self._cpp_state.get_shapes_cpp()
             self._cached_shapes = []
             for data in shapes_data:
                 if data is None:
                     self._cached_shapes.append(None)
                 else:
-                    # Explicitly cast the structure returned by pybind if needed
                     tris_py, color_py, id_py = cast(
                         "tuple[list[tuple[int, int, bool]], tuple[int, int, int], int]",
                         data,
@@ -174,7 +157,6 @@ class GameState:
         Uses cached data if available.
         """
         if self._cached_grid_data is None:
-            # pybind numpy bindings should return np.ndarray directly
             occupied_np = self._cpp_state.get_grid_occupied_flat()
             color_id_np = self._cpp_state.get_grid_colors_flat()
             death_np = self._cpp_state.get_grid_death_flat()
@@ -190,6 +172,10 @@ class GameState:
         """Returns the current step count."""
         return cast("int", self._cpp_state.get_current_step())
 
+    def get_last_cleared_triangles(self) -> int:
+        """Returns the number of triangles cleared in the most recent step."""
+        return cast("int", self._cpp_state.get_last_cleared_triangles())
+
     def get_game_over_reason(self) -> str | None:
         """Returns the reason why the game ended, if it's over."""
         return cast("str | None", self._cpp_state.get_game_over_reason())
@@ -198,7 +184,7 @@ class GameState:
         """Creates a deep copy of the game state."""
         new_wrapper = GameState.__new__(GameState)
         new_wrapper.env_config = self.env_config
-        new_wrapper._cpp_state = self._cpp_state.copy()  # C++ copy handles members
+        new_wrapper._cpp_state = self._cpp_state.copy()
         new_wrapper._cached_shapes = None
         new_wrapper._cached_grid_data = None
         return new_wrapper
@@ -212,10 +198,9 @@ class GameState:
         """
         Directly sets the shapes in the preview slots. For debugging/testing.
         """
-        # Convert Python Shape objects (or None) to the tuple format expected by C++ binding
         shapes_data = [s.to_cpp_repr() if s else None for s in shapes]
         self._cpp_state.debug_set_shapes(shapes_data)
-        self._clear_caches()  # Invalidate caches after changing shapes
+        self._clear_caches()
 
     def _clear_caches(self) -> None:
         """Clears Python-level caches."""

{trianglengin-2.0.6.dist-info → trianglengin-2.0.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trianglengin
-Version: 2.0.6
+Version: 2.0.7
 Summary: High-performance C++/Python engine for a triangle puzzle game.
 Author-email: "Luis Guilherme P. M." <lgpelin92@gmail.com>
 License-Expression: MIT
@@ -57,17 +57,141 @@ It encapsulates:
 
 ---
 
+
+
 ## 🎮 The Ultimate Triangle Puzzle Guide 🧩
 
-*(Game rules remain the same)*
+Get ready to become a Triangle Master! This guide explains everything you need to know to play the game, step-by-step, with lots of details!
+
+### 1. Introduction: Your Mission! 🎯
+
+Your goal is to place colorful shapes onto a special triangular grid. By filling up lines of triangles, you make them disappear and score points! Keep placing shapes and clearing lines for as long as possible to get the highest score before the grid fills up and you run out of moves. Sounds simple? Let's dive into the details!
+
+### 2. The Playing Field: The Grid 🗺️
+
+- **Triangle Cells:** The game board is a grid made of many small triangles. Some point UP (🔺) and some point DOWN (🔻). They alternate like a checkerboard pattern based on their row and column index (specifically, `(row + col) % 2 != 0` means UP).
+- **Shape:** The grid itself is rectangular overall, but the playable area within it is typically shaped like a triangle or hexagon, wider in the middle and narrower at the top and bottom.
+- **Playable Area:** You can only place shapes within the designated playable area.
+- **Death Zones 💀:** Around the edges of the playable area (often at the start and end of rows), some triangles are marked as "Death Zones". You **cannot** place any part of a shape onto these triangles. They are off-limits! Think of them as the boundaries within the rectangular grid.
+
+### 3. Your Tools: The Shapes 🟦🟥🟩
+
+- **Shape Formation:** Each shape is a collection of connected small triangles (🔺 and 🔻). They come in different colors and arrangements. Some might be a single triangle, others might be long lines, L-shapes, or more complex patterns.
+- **Relative Positions:** The triangles within a shape have fixed positions _relative to each other_. When you move the shape, all its triangles move together as one block.
+- **Preview Area:** You will always have **three** shapes available to choose from at any time. These are shown in a special "preview area" on the side of the screen.
+
+### 4. Making Your Move: Placing Shapes 🖱️➡️▦
+
+This is the core action! Here's exactly how to place a shape:
+
+- **Step 4a: Select a Shape:** Look at the three shapes in the preview area. Click on the one you want to place. It should highlight 💡 to show it's selected.
+- **Step 4b: Aim on the Grid:** Move your mouse cursor over the main grid. You'll see a faint "ghost" image of your selected shape following your mouse. This preview helps you aim.
+- **Step 4c: The Placement Rules (MUST Follow!)**
+  - 📏 **Rule 1: Fit Inside Playable Area:** ALL triangles of your chosen shape must land within the playable grid area. No part of the shape can land in a Death Zone 💀.
+  - 🧱 **Rule 2: No Overlap:** ALL triangles of your chosen shape must land on currently _empty_ spaces on the grid. You cannot place a shape on top of triangles that are already filled with color from previous shapes.
+  - 📐 **Rule 3: Orientation Match!** This is crucial!
+    - If a part of your shape is an UP triangle (🔺), it MUST land on an UP space (🔺) on the grid.
+    - If a part of your shape is a DOWN triangle (🔻), it MUST land on a DOWN space (🔻) on the grid.
+    - 🔺➡️🔺 (OK!)
+    - 🔻➡️🔻 (OK!)
+    - 🔺➡️🔻 (INVALID! ❌)
+    - 🔻➡️🔺 (INVALID! ❌)
+  - **Visual Feedback:** The game helps you!
+    - 👍 **Valid Spot:** If the position under your mouse follows ALL three rules, the ghost preview will usually look solid and possibly greenish. This means you _can_ place the shape here.
+    - 👎 **Invalid Spot:** If the position breaks _any_ of the rules (out of bounds, overlaps, wrong orientation), the ghost preview will usually look faded and possibly reddish. This means you _cannot_ place the shape here.
+- **Step 4d: Confirm Placement:** Once you find a **valid** spot (👍), click the left mouse button again. _Click!_ The shape is now placed permanently on the grid! ✨
+
+### 5. Scoring Points: How You Win! 🏆
+
+You score points in two main ways:
+
+- **Placing Triangles:** You get a small number of points for _every single small triangle_ that makes up the shape you just placed. (e.g., placing a 3-triangle shape might give you 3 \* tiny_score points).
+- **Clearing Lines:** This is where the BIG points come from! You get a much larger number of points for _every single small triangle_ that disappears when you clear a line (or multiple lines at once!). See the next section for details!
+
+### 6. Line Clearing Magic! ✨ (The Key to High Scores!)
+
+This is the most exciting part! When you place a shape, the game immediately checks if you've completed any lines. This section explains how the game _finds_ and _clears_ these lines.
+
+- **What Lines Can Be Cleared?** There are **three** types of lines the game looks for:
+
+  - **Horizontal Lines ↔️:** A straight, unbroken line of filled triangles going across a single row.
+  - **Diagonal Lines (Top-Left to Bottom-Right) ↘️:** An unbroken diagonal line of filled triangles stepping down and to the right.
+  - **Diagonal Lines (Bottom-Left to Top-Right) ↗️:** An unbroken diagonal line of filled triangles stepping up and to the right.
+
+- **How Lines are Found: Pre-calculation of Maximal Lines**
 
-*(... Game rules section remains unchanged ...)*
+  - **The Idea:** Instead of checking every possible line combination all the time, the game pre-calculates all *maximal* continuous lines of playable triangles when it starts. A **maximal line** is the longest possible straight segment of *playable* triangles (not in a Death Zone) in one of the three directions (Horizontal, Diagonal ↘️, Diagonal ↗️).
+  - **Tracing:** For every playable triangle on the grid, the game traces outwards in each of the three directions to find the full extent of the continuous playable line passing through that triangle in that direction.
+  - **Storing Maximal Lines:** Only the complete maximal lines found are stored. For example, if tracing finds a playable sequence `A-B-C-D`, only the line `(A,B,C,D)` is stored, not the sub-segments like `(A,B,C)` or `(B,C,D)`. These maximal lines represent the *potential* lines that can be cleared.
+  - **Coordinate Map:** The game also builds a map linking each playable triangle coordinate `(r, c)` to the set of maximal lines it belongs to. This allows for quick lookup.
+
+- **Defining the Paths (Neighbor Logic):** How does the game know which triangle is "next" when tracing? It depends on the current triangle's orientation (🔺 or 🔻) and the direction being traced:
+
+  - **Horizontal ↔️:**
+    - Left Neighbor: `(r, c-1)` (Always in the same row)
+    - Right Neighbor: `(r, c+1)` (Always in the same row)
+  - **Diagonal ↘️ (TL-BR):**
+    - If current is 🔺 (Up): Next is `(r+1, c)` (Down triangle directly below)
+    - If current is 🔻 (Down): Next is `(r, c+1)` (Up triangle to the right)
+  - **Diagonal ↗️ (BL-TR):**
+    - If current is 🔻 (Down): Next is `(r-1, c)` (Up triangle directly above)
+    - If current is 🔺 (Up): Next is `(r, c+1)` (Down triangle to the right)
+
+- **Visualizing the Paths:**
+
+  - **Horizontal ↔️:**
+    ```
+    ... [🔻][🔺][🔻][🔺][🔻][🔺] ...  (Moves left/right in the same row)
+    ```
+  - **Diagonal ↘️ (TL-BR):** (Connects via shared horizontal edges)
+    ```
+    ...[🔺]...
+    ...[🔻][🔺] ...
+    ...     [🔻][🔺] ...
+    ...         [🔻] ...
+    (Path alternates row/col increments depending on orientation)
+    ```
+  - **Diagonal ↗️ (BL-TR):** (Connects via shared horizontal edges)
+    ```
+    ...           [🔺]  ...
+    ...      [🔺][🔻]   ...
+    ... [🔺][🔻]        ...
+    ... [🔻]            ...
+    (Path alternates row/col increments depending on orientation)
+    ```
+
+- **The "Full Line" Rule:** After you place a piece, the game looks at the coordinates `(r, c)` of the triangles you just placed. Using the pre-calculated map, it finds all the *maximal* lines that contain _any_ of those coordinates. For each of those maximal lines (that have at least 2 triangles), it checks: "Is _every single triangle coordinate_ in this maximal line now occupied?" If yes, that line is complete! (Note: Single isolated triangles don't count as clearable lines).
+
+- **The _Poof_! 💨:**
+  - If placing your shape completes one or MORE maximal lines (of any type, length >= 2) simultaneously, all the triangles in ALL completed lines vanish instantly!
+  - The spaces become empty again.
+  - You score points for _every single triangle_ that vanished. Clearing multiple lines at once is the best way to rack up points! 🥳
+
+### 7. Getting New Shapes: The Refill 🪄
+
+- **The Trigger:** The game only gives you new shapes when a specific condition is met.
+- **The Condition:** New shapes appear **only when all three of your preview slots become empty at the exact same time.**
+- **How it Happens:** This usually occurs right after you place your _last_ available shape (the third one).
+- **The Refill:** As soon as the third slot becomes empty, _BAM!_ 🪄 Three brand new, randomly generated shapes instantly appear in the preview slots.
+- **Important:** If you place a shape and only one or two slots are empty, you **do not** get new shapes yet. You must use up all three before the refill happens.
+
+### 8. The End of the Road: Game Over 😭
+
+So, how does the game end?
+
+- **The Condition:** The game is over when you **cannot legally place _any_ of the three shapes currently available in your preview slots anywhere on the grid.**
+- **The Check:** After every move (placing a shape and any resulting line clears), and after any potential shape refill, the game checks: "Is there at least one valid spot on the grid for Shape 1? OR for Shape 2? OR for Shape 3?"
+- **No More Moves:** If the answer is "NO" for all three shapes (meaning none of them can be placed anywhere according to the Placement Rules), then the game immediately ends.
+- **Strategy:** This means you need to be careful! Don't fill up the grid in a way that leaves no room for the types of shapes you might get later. Always try to keep options open! 🤔
+
+That's it! Now you know all the rules. Go forth and conquer the Triangle Puzzle! 🏆
 
 ---
 
 ## Purpose
 
-The primary goal is to provide a self-contained, installable library with a high-performance C++ core and a Python interface for the triangle puzzle game. This allows different RL agent implementations or other applications to build upon a consistent and fast game backend. The interactive UI is included but only initialized when running the specific UI commands.
+The primary goal is to provide a self-contained, installable library for the core logic and basic interactive UI of the triangle puzzle game. This allows different RL agent implementations or other applications to build upon a consistent and well-defined game backend, avoiding code duplication.
+
 
 ## Installation
 

{trianglengin-2.0.6.dist-info → trianglengin-2.0.7.dist-info}/RECORD

@@ -1,18 +1,18 @@
 trianglengin/__init__.py,sha256=VBYKMivxX19prPkxmSCSJJrjFXDVWkQJ9b5kQ6RzvkI,954
-trianglengin/game_interface.py,sha256=7zvt61QGmAuagRfNMpRORhX11sy9NqWM9xWstsEawKY,9540
+trianglengin/game_interface.py,sha256=5NkM-mj--iBCFQzpsR6WQsBZnYRrvEqQl0OQ6UPA0Jg,8184
 trianglengin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-trianglengin/trianglengin_cpp.cp310-win32.pyd,sha256=BcPedX7TCP7AgjzMKeZdX9NOA0fkM42iTqWfnAZ4rfs,241664
-trianglengin/Release/trianglengin_cpp.cp39-win_amd64.pyd,sha256=BcPedX7TCP7AgjzMKeZdX9NOA0fkM42iTqWfnAZ4rfs,241664
+trianglengin/trianglengin_cpp.cp310-win32.pyd,sha256=t3DK8DqPQoX-HB4rIa4qoX0T5UxLwbnTa68YwshOTgU,242176
+trianglengin/Release/trianglengin_cpp.cp39-win_amd64.pyd,sha256=t3DK8DqPQoX-HB4rIa4qoX0T5UxLwbnTa68YwshOTgU,242176
 trianglengin/config/README.md,sha256=zPN8ezwsN5fmH4xCsVSgOZwfyng_TwrCj3MlwEq63Y4,1544
 trianglengin/config/__init__.py,sha256=sdr4D-pSCYmfXY2jOLEjPra2VewDiaWNwx1bWKp0nf8,168
 trianglengin/config/display_config.py,sha256=ivZEGTCuUfmiVU6GJpVpEASFh30AAHSH42PIIi6bPZg,1862
 trianglengin/config/env_config.py,sha256=hJmdAm4HC5SWpAtp7u3tIDWPMKw711rVszwyQWD6-Ys,2421
 trianglengin/core/__init__.py,sha256=LWZkoJctRGUhd5DZUJlPCS7usdQLZyKYkoyWUWO3L4o,470
 trianglengin/cpp/CMakeLists.txt,sha256=vmhTQLRD7LRPbfFlisVVJ9-cCkeM3UMrikIde7TRLWc,1370
-trianglengin/cpp/bindings.cpp,sha256=okdR2NCdxgP_FTgMjwXNbzcaFdERRrvy7m1eB_5FY8g,8899
+trianglengin/cpp/bindings.cpp,sha256=gmJdAVIHsusPC6Hz_2Ya_ItpOZ2Ajl9ZMMJMCKkwVn4,8652
 trianglengin/cpp/config.h,sha256=rZZ6os70igGgA_fp-81fMv9TQMFJb91m6T-KeTOpKAU,742
-trianglengin/cpp/game_state.cpp,sha256=TTwJm-9BBvof2tntAVdQ5fjMSjqAh2F4wFsMkFlgn48,13068
-trianglengin/cpp/game_state.h,sha256=no5D0SP-vijTuL-sObJ4tx06nW0oaX42mzMZn1matL8,3302
+trianglengin/cpp/game_state.cpp,sha256=U8po3NVAuJkq_az1bA7raxkMWK8HHM_zcrEcttb74F8,10771
+trianglengin/cpp/game_state.h,sha256=reZVI6C5Sj-zn7XaVNhKNfJkaIqmlPgAOpIp0hb-Iv8,3371
 trianglengin/cpp/grid_data.cpp,sha256=6iucpVisR1dYayKjSPbjCaYEKaqWaNqGVswyLm6f-zM,8024
 trianglengin/cpp/grid_data.h,sha256=HVH5gqXAuHwDJrC2d7uy_maeS2ulckeGy68TkpL9gNg,2568
 trianglengin/cpp/grid_logic.cpp,sha256=O8CfzMw_3r1fU0Iu3KnapPBi5kC7tSs47yWeaVsIxOw,3457
@@ -51,9 +51,9 @@ trianglengin/ui/visualization/drawing/utils.py,sha256=gtGtt8bgaIvctFA5TEmKqmXNov
 trianglengin/utils/__init__.py,sha256=pnFOkerF1TAz9oCzkNYBw6N56uENsyOiMZzA0cQ2SrA,185
 trianglengin/utils/geometry.py,sha256=nrhr5C3MGO-_xXz96w1B0OJNaATLbc_AeZwoB_O6gsI,2128
 trianglengin/utils/types.py,sha256=N_CjVJISvBP5QG1QYvepgORD0oNpMJlJRCJ9IdgjmWc,241
-trianglengin-2.0.6.dist-info/licenses/LICENSE,sha256=DNjSCXzwafRxA5zjyWccoRXZTDMpTNElFpNVKz4NEpY,1098
-trianglengin-2.0.6.dist-info/METADATA,sha256=p_tcQFMpt0tSbMQ5R9lgaGXnfMvnvjMFSdjyJ1G_TNU,12316
-trianglengin-2.0.6.dist-info/WHEEL,sha256=CNoUkshc3SqngBVkyzktNNHC8941NRkLClTTB1cTnI8,97
-trianglengin-2.0.6.dist-info/entry_points.txt,sha256=kQEqO_U-MEpMEC0xwOPSucBzQIq2Ny7XwCtFSruZhvY,57
-trianglengin-2.0.6.dist-info/top_level.txt,sha256=YsSWmp_2zM23wRc5TRERHpVCgQuVYieYHDTpnwVQC7Y,13
-trianglengin-2.0.6.dist-info/RECORD,,
+trianglengin-2.0.7.dist-info/licenses/LICENSE,sha256=DNjSCXzwafRxA5zjyWccoRXZTDMpTNElFpNVKz4NEpY,1098
+trianglengin-2.0.7.dist-info/METADATA,sha256=4gqlUZG-ggZL28DVboY7EaMwUTVeBKjbb9D6tuZs2hw,22441
+trianglengin-2.0.7.dist-info/WHEEL,sha256=CNoUkshc3SqngBVkyzktNNHC8941NRkLClTTB1cTnI8,97
+trianglengin-2.0.7.dist-info/entry_points.txt,sha256=kQEqO_U-MEpMEC0xwOPSucBzQIq2Ny7XwCtFSruZhvY,57
+trianglengin-2.0.7.dist-info/top_level.txt,sha256=YsSWmp_2zM23wRc5TRERHpVCgQuVYieYHDTpnwVQC7Y,13
+trianglengin-2.0.7.dist-info/RECORD,,