trianglengin 2.0.4__pp310-pypy310_pp73-macosx_11_0_arm64.whl → 2.0.7__pp310-pypy310_pp73-macosx_11_0_arm64.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
@@ -16,18 +17,54 @@ namespace trianglengin::cpp
         shapes_(config_.num_shape_slots),
         score_(0.0),
         current_step_(0),
+        last_cleared_triangles_(0), // Initialize added member
         game_over_(false),
         rng_(initial_seed)
   {
     reset();
   }
 
+  // --- Explicit Copy Constructor ---
+  GameStateCpp::GameStateCpp(const GameStateCpp &other)
+      : 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_)
+  {
+  }
+
+  // --- Explicit Copy Assignment Operator ---
+  GameStateCpp &GameStateCpp::operator=(const GameStateCpp &other)
+  {
+    if (this != &other)
+    {
+      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_;
+    }
+    return *this;
+  }
+
   void GameStateCpp::reset()
   {
     grid_data_.reset();
     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;
@@ -37,29 +74,25 @@ namespace trianglengin::cpp
 
   void GameStateCpp::check_initial_state_game_over()
   {
-    get_valid_actions(true); // This calls calculate_valid_actions_internal
-    if (!game_over_ && valid_actions_cache_ && valid_actions_cache_->empty())
-    {
-      force_game_over("No valid actions available at start.");
-      // REMOVED C++ Log: std::cerr << "[GameStateCpp::check_initial_state_game_over] Forced game over: No valid actions at start." << std::endl;
-    }
+    get_valid_actions(true);
   }
 
   std::tuple<double, bool> GameStateCpp::step(Action action)
   {
+    last_cleared_triangles_ = 0; // Reset before potential clearing
+
     if (game_over_)
     {
       return {0.0, true};
     }
 
     const auto &valid_actions = get_valid_actions();
+
     if (valid_actions.find(action) == valid_actions.end())
     {
-      // Invalid action detected
       force_game_over("Invalid action provided: " + std::to_string(action));
-      // Apply penalty to score *before* returning
       score_ += config_.penalty_game_over;
-      return {config_.penalty_game_over, true}; // Return penalty and done=true
+      return {config_.penalty_game_over, true};
     }
 
     int shape_idx, r, c;
@@ -69,17 +102,15 @@ namespace trianglengin::cpp
     }
     catch (const std::out_of_range &e)
     {
-      // Error during decoding (should be caught by valid_actions check, but defensive)
       force_game_over("Failed to decode action: " + std::to_string(action));
-      score_ += config_.penalty_game_over; // Apply penalty
+      score_ += config_.penalty_game_over;
       return {config_.penalty_game_over, true};
     }
 
     if (shape_idx < 0 || shape_idx >= static_cast<int>(shapes_.size()) || !shapes_[shape_idx].has_value())
     {
-      // Action references invalid slot (should be caught by valid_actions check)
       force_game_over("Action references invalid/empty shape slot: " + std::to_string(shape_idx));
-      score_ += config_.penalty_game_over; // Apply penalty
+      score_ += config_.penalty_game_over;
       return {config_.penalty_game_over, true};
     }
 
@@ -87,9 +118,8 @@ namespace trianglengin::cpp
 
     if (!grid_logic::can_place(grid_data_, shape_to_place, r, c))
     {
-      // Should not happen if valid_actions is correct
       force_game_over("Placement check failed for valid action (logic error?). Action: " + std::to_string(action));
-      score_ += config_.penalty_game_over; // Apply penalty
+      score_ += config_.penalty_game_over;
       return {config_.penalty_game_over, true};
     }
 
@@ -108,7 +138,7 @@ namespace trianglengin::cpp
       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));
-        score_ += config_.penalty_game_over; // Apply penalty
+        score_ += config_.penalty_game_over;
         return {config_.penalty_game_over, true};
       }
       occupied_grid[target_r][target_c] = true;
@@ -125,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;
@@ -143,9 +174,8 @@ namespace trianglengin::cpp
 
     // --- Update State & Check Game Over ---
     current_step_++;
-    valid_actions_cache_ = std::nullopt;
-    get_valid_actions(true); // Force recalculation and update game_over_ if needed
-    // game_over_ flag is now definitive
+    invalidate_action_cache();
+    get_valid_actions(true);
 
     // --- Calculate Reward & Update Score ---
     double reward = 0.0;
@@ -154,37 +184,24 @@ namespace trianglengin::cpp
 
     if (game_over_)
     {
-      reward += config_.penalty_game_over;
+      // 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_};
   }
 
   bool GameStateCpp::is_over() const
   {
-    if (game_over_)
-      return true;
-    // If cache exists, use it. Otherwise, calculate.
-    if (valid_actions_cache_.has_value())
-      return valid_actions_cache_->empty();
-    // Need to remove const to calculate and potentially set game_over_
-    const_cast<GameStateCpp *>(this)->calculate_valid_actions_internal();
-    // Check game_over_ again as calculate might have set it
-    if (game_over_)
-      return true;
-    // Now the cache should exist
-    return valid_actions_cache_->empty();
+    return game_over_;
   }
 
   void GameStateCpp::force_game_over(const std::string &reason)
   {
-    // This function only sets the flags and reason.
-    // Score update should happen in the context where the game over is triggered (e.g., step).
     if (!game_over_)
     {
       game_over_ = true;
@@ -208,17 +225,19 @@ namespace trianglengin::cpp
       }
       return *valid_actions_cache_;
     }
+
     if (!force_recalculate && valid_actions_cache_.has_value())
     {
       return *valid_actions_cache_;
     }
+
     calculate_valid_actions_internal();
-    // Check if game should end *after* calculating actions
+
     if (!game_over_ && valid_actions_cache_->empty())
     {
       force_game_over("No valid actions available.");
-      // REMOVED C++ Log: std::cerr << "[GameStateCpp::get_valid_actions] Forced game over: No valid actions found after calculation." << std::endl;
     }
+
     return *valid_actions_cache_;
   }
 
@@ -227,19 +246,9 @@ namespace trianglengin::cpp
     valid_actions_cache_ = std::nullopt;
   }
 
-  // Make this non-const so it can modify the cache
-  void GameStateCpp::calculate_valid_actions_internal() const // Keep const for now, use mutable cache
+  void GameStateCpp::calculate_valid_actions_internal() const
   {
-    if (game_over_)
-    {
-      valid_actions_cache_ = std::set<Action>();
-      // REMOVED C++ Log: std::cerr << "[GameStateCpp::calculate_valid_actions_internal] Game already over. Returning empty set." << std::endl;
-      return;
-    }
     std::set<Action> valid_actions;
-    int can_place_true_count = 0; // Counter for debugging
-    int attempts_count = 0;       // Counter for total placement checks
-
     for (int shape_idx = 0; shape_idx < static_cast<int>(shapes_.size()); ++shape_idx)
     {
       if (!shapes_[shape_idx].has_value())
@@ -247,46 +256,25 @@ namespace trianglengin::cpp
       const ShapeCpp &shape = shapes_[shape_idx].value();
       for (int r = 0; r < config_.rows; ++r)
       {
-        const auto &[start_c, end_c] = config_.playable_range_per_row[r];
-        for (int c = start_c; c < end_c; ++c)
+        for (int c = 0; c < config_.cols; ++c)
         {
-          attempts_count++;                                                       // Increment attempt counter
-          bool can_place_result = grid_logic::can_place(grid_data_, shape, r, c); // Store result
-          if (can_place_result)
+          if (grid_logic::can_place(grid_data_, shape, r, c))
           {
             valid_actions.insert(encode_action(shape_idx, r, c));
-            can_place_true_count++; // Increment counter
           }
         }
       }
     }
-    // REMOVED C++ Log:
-    // std::cerr << "[GameStateCpp::calculate_valid_actions_internal] Step: " << current_step_
-    //           << ", Attempts: " << attempts_count
-    //           << ", CanPlaceTrue: " << can_place_true_count
-    //           << ", ValidActionsFound: " << valid_actions.size()
-    //           << std::endl;
-
-    // Use 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_; }
 
   GameStateCpp GameStateCpp::copy() const
   {
-    GameStateCpp newState = *this;
-    // Copy the cache state explicitly
-    if (this->valid_actions_cache_.has_value())
-    {
-      newState.valid_actions_cache_ = this->valid_actions_cache_;
-    }
-    else
-    {
-      newState.valid_actions_cache_ = std::nullopt;
-    }
-    return newState;
+    return GameStateCpp(*this);
   }
 
   void GameStateCpp::debug_toggle_cell(int r, int c)
@@ -298,31 +286,31 @@ 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
+      invalidate_action_cache();
+      get_valid_actions(true);
     }
   }
 
   void GameStateCpp::debug_set_shapes(const std::vector<std::optional<ShapeCpp>> &new_shapes)
   {
-    // Overwrite the current shapes with the provided ones.
-    // Ensure the size matches the number of slots.
     size_t num_to_copy = std::min(new_shapes.size(), shapes_.size());
     for (size_t i = 0; i < num_to_copy; ++i)
     {
       shapes_[i] = new_shapes[i];
     }
-    // Fill remaining slots with nullopt if new_shapes is shorter
     for (size_t i = num_to_copy; i < shapes_.size(); ++i)
     {
       shapes_[i] = std::nullopt;
     }
-    // Invalidate cache as valid actions will change
     invalidate_action_cache();
+    get_valid_actions(true);
   }
 
   Action GameStateCpp::encode_action(int shape_idx, int r, int c) const
@@ -330,7 +318,7 @@ namespace trianglengin::cpp
     int grid_size = config_.rows * config_.cols;
     if (shape_idx < 0 || shape_idx >= config_.num_shape_slots || r < 0 || r >= config_.rows || c < 0 || c >= config_.cols)
     {
-      throw std::out_of_range("encode_action arguments out of range.");
+      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
 
@@ -27,14 +27,22 @@ namespace trianglengin::cpp
   public:
     explicit GameStateCpp(const EnvConfigCpp &config, unsigned int initial_seed);
 
+    // --- Rule of 5 ---
+    ~GameStateCpp() = default;                                        // Default destructor
+    GameStateCpp(const GameStateCpp &other);                          // Copy constructor
+    GameStateCpp &operator=(const GameStateCpp &other);               // Copy assignment operator
+    GameStateCpp(GameStateCpp &&other) noexcept = default;            // Default move constructor
+    GameStateCpp &operator=(GameStateCpp &&other) noexcept = default; // Default move assignment operator
+
     void reset();
     std::tuple<double, bool> step(Action action);
     bool is_over() const;
     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;
+    GameStateCpp copy() const; // Keep Python-facing copy method
     void debug_toggle_cell(int r, int c);
     void invalidate_action_cache(); // Moved to public
     // Debug method to force shapes into slots
@@ -46,6 +54,8 @@ namespace trianglengin::cpp
     const std::vector<std::optional<ShapeCpp>> &get_shapes() const { return shapes_; }
     std::vector<std::optional<ShapeCpp>> &get_shapes_mut() { return shapes_; }
     const EnvConfigCpp &get_config() const { return config_; }
+    // Expose RNG state for copying if needed (or handle seeding in copy)
+    std::mt19937 get_rng_state() const { return rng_; }
 
   private:
     EnvConfigCpp config_;
@@ -53,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/cpp/grid_data.cpp

@@ -44,7 +44,7 @@ namespace trianglengin::cpp
     precompute_lines();
   }
 
-  // Copy constructor: Copy the config_ member
+  // Copy constructor: Explicitly copy all members
   GridData::GridData(const GridData &other)
       : config_(other.config_), // Copy config value
         rows_(other.rows_),
@@ -55,9 +55,11 @@ namespace trianglengin::cpp
         lines_(other.lines_),
         coord_to_lines_map_(other.coord_to_lines_map_)
   {
+    // All members are copyable, default member-wise copy is sufficient here,
+    // but being explicit ensures correctness if members change later.
   }
 
-  // Copy assignment operator: Copy the config_ member
+  // Copy assignment operator: Explicitly copy all members
   GridData &GridData::operator=(const GridData &other)
   {
     if (this != &other)
@@ -103,7 +105,8 @@ namespace trianglengin::cpp
     {
       throw std::out_of_range("Coordinates (" + std::to_string(r) + "," + std::to_string(c) + ") out of bounds.");
     }
-    return !death_grid_[r][c] && occupied_grid_[r][c];
+    // An occupied cell cannot be a death cell by game logic after placement/clearing
+    return occupied_grid_[r][c];
   }
 
   std::optional<int> GridData::get_color_id(int r, int c) const
@@ -190,6 +193,7 @@ namespace trianglengin::cpp
         for (const auto &direction : directions)
         {
           Coord line_start_coord = start_coord;
+          // Find the true start of the line segment in this direction
           while (true)
           {
             auto prev_coord_opt = get_neighbor(std::get<0>(line_start_coord), std::get<1>(line_start_coord), direction, true);
@@ -200,8 +204,11 @@ namespace trianglengin::cpp
             else
               break;
           }
+          // Check if we already processed this line starting from this coordinate and direction
           if (processed_starts.count({line_start_coord, direction}))
             continue;
+
+          // Trace the line forward from the true start
           Line current_line;
           std::optional<Coord> trace_coord_opt = line_start_coord;
           while (trace_coord_opt && is_live(std::get<0>(*trace_coord_opt), std::get<1>(*trace_coord_opt)))
@@ -209,7 +216,9 @@ namespace trianglengin::cpp
             current_line.push_back(*trace_coord_opt);
             trace_coord_opt = get_neighbor(std::get<0>(*trace_coord_opt), std::get<1>(*trace_coord_opt), direction, false);
           }
-          if (current_line.size() >= 2)
+
+          // Store the line if it's long enough and mark it as processed
+          if (current_line.size() >= 2) // Only store lines of length 2 or more
           {
             maximal_lines_set.insert(current_line);
             processed_starts.insert({line_start_coord, direction});
@@ -218,16 +227,20 @@ namespace trianglengin::cpp
       }
     }
 
+    // Convert set to vector and sort for deterministic order
     lines_ = std::vector<Line>(maximal_lines_set.begin(), maximal_lines_set.end());
     std::sort(lines_.begin(), lines_.end(), [](const Line &a, const Line &b)
               {
-            if (a.empty() || b.empty()) return b.empty();
+            if (a.empty() || b.empty()) return b.empty(); // Handle empty lines if they somehow occur
+            // Sort primarily by starting row, then starting column, then size
             if (std::get<0>(a[0]) != std::get<0>(b[0])) return std::get<0>(a[0]) < std::get<0>(b[0]);
             if (std::get<1>(a[0]) != std::get<1>(b[0])) return std::get<1>(a[0]) < std::get<1>(b[0]);
             return a.size() < b.size(); });
 
+    // Build the coordinate-to-lines map
     for (const auto &line_vec : lines_)
     {
+      // Use a set of Coords (LineFs) as the value in the map for efficient lookup
       LineFs line_fs(line_vec.begin(), line_vec.end());
       for (const auto &coord : line_vec)
       {

trianglengin/cpp/grid_data.h

@@ -48,10 +48,9 @@ namespace trianglengin::cpp
     int rows() const { return rows_; }
     int cols() const { return cols_; }
 
-    // Copy constructor
-    GridData(const GridData &other);
-    // Copy assignment operator
-    GridData &operator=(const GridData &other);
+    // --- Explicit Copy Control ---
+    GridData(const GridData &other);            // Copy constructor
+    GridData &operator=(const GridData &other); // Copy assignment operator
 
     // Default move constructor/assignment should work now
     GridData(GridData &&other) noexcept = default;
@@ -75,4 +74,4 @@ namespace trianglengin::cpp
 
 } // namespace trianglengin::cpp
 
-#endif // TRIANGLENGIN_CPP_GRID_DATA_H
+#endif // TRIANGLENGIN_CPP_GRID_DATA_H

trianglengin/cpp/structs.h

@@ -8,7 +8,9 @@
 #include <tuple>
 #include <string>
 #include <cstdint>
-#include <utility> // For std::move
+#include <utility>  // For std::move
+#include <optional> // For optional members
+#include <set>      // For previous valid actions
 
 namespace trianglengin::cpp
 {
@@ -35,6 +37,33 @@ namespace trianglengin::cpp
       return triangles == other.triangles && color == other.color && color_id == other.color_id;
     }
   };
+
+  // --- NEW: Structure to hold undo information ---
+  struct StepUndoInfo
+  {
+    // Cells changed by placement or clearing
+    // Stores (row, col, previous_occupied_state, previous_color_id)
+    std::vector<std::tuple<int, int, bool, int8_t>> changed_cells;
+
+    // Info about the shape that was consumed by the step
+    int consumed_shape_slot = -1;
+    std::optional<ShapeCpp> consumed_shape = std::nullopt;
+
+    // Previous game state variables
+    double previous_score = 0.0;
+    int previous_step = 0;
+    bool previous_game_over = false;
+    std::optional<std::string> previous_game_over_reason = std::nullopt;
+
+    // Cache invalidation marker (or potentially the previous cache itself)
+    // Storing the previous cache might be large, maybe just invalidate?
+    // Let's start by just marking that the cache *was* valid before the step.
+    bool was_action_cache_valid = false;
+    // OPTIONAL (more complex): Store the actual previous cache
+    // std::optional<std::set<Action>> previous_valid_actions_cache = std::nullopt;
+  };
+  // --- END NEW ---
+
 } // namespace trianglengin::cpp
 
 #endif // TRIANGLENGIN_CPP_STRUCTS_H

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.4.dist-info → trianglengin-2.0.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trianglengin
-Version: 2.0.4
+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.4.dist-info → trianglengin-2.0.7.dist-info}/RECORD

@@ -1,13 +1,7 @@
-trianglengin-2.0.4.dist-info/RECORD,,
-trianglengin-2.0.4.dist-info/WHEEL,sha256=8UigNX42SJ7Bc2aBUBR_PNKLdWLJBQB8todoqHTAdoY,116
-trianglengin-2.0.4.dist-info/entry_points.txt,sha256=kQEqO_U-MEpMEC0xwOPSucBzQIq2Ny7XwCtFSruZhvY,57
-trianglengin-2.0.4.dist-info/top_level.txt,sha256=YsSWmp_2zM23wRc5TRERHpVCgQuVYieYHDTpnwVQC7Y,13
-trianglengin-2.0.4.dist-info/METADATA,sha256=Ep7c5ldlwGwB_JhzXsgAWju0AHq4k5144Z5dzqmmR6Q,12066
-trianglengin-2.0.4.dist-info/licenses/LICENSE,sha256=So3rgoJp-HgoxkclxZLIBC3pmmTwshN4tUO8KiQ6akc,1077
-trianglengin/trianglengin_cpp.pypy310-pp73-darwin.so,sha256=OeWk67c26OdRho8r9-AuGnswV4K6Yn-dBZfruqmb1GQ,233528
+trianglengin/trianglengin_cpp.pypy310-pp73-darwin.so,sha256=lC_53hyhxt9RfudMdLQgR2lpoRTchQiFniPp3pB9wwI,233528
 trianglengin/__init__.py,sha256=4INnGvOYIjzOyCew7lhX6Irc8_H7QVxWc5jopt9TCZ4,919
 trianglengin/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-trianglengin/game_interface.py,sha256=ijfBH08DU2sHyMH6XZmQbFQZDPGsKlkk3gk3AUt3fmU,9304
+trianglengin/game_interface.py,sha256=2zwSGMWg8GJtAXykOKTAwjAhihl9FAcKoz07-zeYNuY,7963
 trianglengin/ui/config.py,sha256=E68Qvbr3dwyhC_Rh_PK-QHWlHOrXFQhAsARZZMoQHNs,1579
 trianglengin/ui/__init__.py,sha256=AVIFYOWoZTt69NnkX0Ht3dEAPMpxQ6WZ8G9tDvxNXvA,558
 trianglengin/ui/README.md,sha256=M-5UU-NKG6qYu1riCUkftRZIwE2Jvf-5qOZ1QGWjPSg,1718
@@ -48,11 +42,17 @@ trianglengin/cpp/grid_logic.h,sha256=O6roOE_U7nbKgAkaMkC8LrEjGDvnL3QiVzOnXunXy9s
 trianglengin/cpp/CMakeLists.txt,sha256=FCUnDHVQhe7PFj9FTQcQiWFgr61b8iJg0m0UH3hGYE4,1328
 trianglengin/cpp/grid_logic.cpp,sha256=8ag6wwdmZuHg8_I-skTI9LOdB84a82IrZAoREq0dkQo,3333
 trianglengin/cpp/config.h,sha256=9Xd-9wTYmFwEuf-ZjrQa5zlXF58MrLhRKU1ygyG2Nmc,715
-trianglengin/cpp/grid_data.cpp,sha256=KH9BbLuhi-_fmKgnT2oPuzHRDo87xFDHiBfpXCwgYsw,6904
-trianglengin/cpp/grid_data.h,sha256=KGOtUQQb7HJnU_LyWIWW5g6S2gJ2u3ewY32qXtoPfcs,2453
-trianglengin/cpp/game_state.h,sha256=MBoAiG617XPtZNGqGPE2PC1pX1dBHuWBGHLJr3iBg6c,2547
-trianglengin/cpp/game_state.cpp,sha256=PL_YUf_3S8yOSfFpICr9zuq5Y_9j3gthaQZ4Th5jA5E,12090
-trianglengin/cpp/structs.h,sha256=v_aL5O5gwXH_qRPGUIkNplr167rgf7gCVlWIJKOLV1U,993
+trianglengin/cpp/grid_data.cpp,sha256=WDdaYN8GIPHxKMNvxSI_oUWa23pVYRt5WhX0N5EMGoU,7773
+trianglengin/cpp/grid_data.h,sha256=j_VDdBCQELg8m_kJ4GIyHstt7ynyLgjHyTcdBPv_AP4,2492
+trianglengin/cpp/game_state.h,sha256=DLAWM3tVMpKMBo1LJjvWCwqeHYAh9aiT27b74dOhnnI,3288
+trianglengin/cpp/game_state.cpp,sha256=qrXPYYnQnlFjbgqY5e85GEldUkjCdusSr-JsFlouGf4,10431
+trianglengin/cpp/structs.h,sha256=yGJp_VatwCHpDAcYJBpsIfEMEG4BQuqdDObqd7nBY7M,2155
 trianglengin/cpp/shape_logic.h,sha256=QvjLAPG5y42FetpXXuCcYrWlcwvKGo7csU8Ch-RmdFs,626
-trianglengin/cpp/bindings.cpp,sha256=B3hfxIF_pBAyVG1QpbBvJT1awy8uJWRJSBNxaNY5_pY,8689
+trianglengin/cpp/bindings.cpp,sha256=gCtvBxKrLRLO0OLXt-nbRn3opVMXftkEQrTkpE9G0Zc,8445
 trianglengin/cpp/shape_logic.cpp,sha256=gF1mgolaNvxpNphwDScNUvOkoq4FuxFASB3n50WI3Bo,4133
+trianglengin-2.0.7.dist-info/RECORD,,
+trianglengin-2.0.7.dist-info/WHEEL,sha256=8UigNX42SJ7Bc2aBUBR_PNKLdWLJBQB8todoqHTAdoY,116
+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/METADATA,sha256=utkuPTxtDnky8-jg8KAa1Ec_bwbAiWnWNerFjjh6BhU,22067
+trianglengin-2.0.7.dist-info/licenses/LICENSE,sha256=So3rgoJp-HgoxkclxZLIBC3pmmTwshN4tUO8KiQ6akc,1077