trianglengin 2.0.1__cp312-cp312-musllinux_1_2_i686.whl

trianglengin/cpp/grid_data.h

@@ -0,0 +1,78 @@
+// File: src/trianglengin/cpp/grid_data.h
+#ifndef TRIANGLENGIN_CPP_GRID_DATA_H
+#define TRIANGLENGIN_CPP_GRID_DATA_H
+
+#pragma once
+
+#include <vector>
+#include <set>
+#include <map>
+#include <tuple>
+#include <memory>
+#include <optional>
+#include <string>
+#include <stdexcept>
+
+#include "config.h"
+#include "structs.h"
+
+namespace trianglengin::cpp
+{
+  using Line = std::vector<Coord>;
+  using LineFs = std::set<Coord>;
+  using LineFsSet = std::set<LineFs>;
+  using CoordMap = std::map<Coord, LineFsSet>;
+
+  class GridData
+  {
+  public:
+    // Constructor takes config by const reference but stores by value
+    explicit GridData(const EnvConfigCpp &config);
+
+    void reset();
+    bool is_valid(int r, int c) const;
+    bool is_death(int r, int c) const;
+    bool is_occupied(int r, int c) const;
+    std::optional<int> get_color_id(int r, int c) const;
+    bool is_up(int r, int c) const;
+
+    const std::vector<std::vector<bool>> &get_occupied_grid() const { return occupied_grid_; }
+    const std::vector<std::vector<int8_t>> &get_color_id_grid() const { return color_id_grid_; }
+    const std::vector<std::vector<bool>> &get_death_grid() const { return death_grid_; }
+    std::vector<std::vector<bool>> &get_occupied_grid_mut() { return occupied_grid_; }
+    std::vector<std::vector<int8_t>> &get_color_id_grid_mut() { return color_id_grid_; }
+
+    const std::vector<Line> &get_lines() const { return lines_; }
+    const CoordMap &get_coord_to_lines_map() const { return coord_to_lines_map_; }
+
+    int rows() const { return rows_; }
+    int cols() const { return cols_; }
+
+    // Copy constructor
+    GridData(const GridData &other);
+    // Copy assignment operator
+    GridData &operator=(const GridData &other);
+
+    // Default move constructor/assignment should work now
+    GridData(GridData &&other) noexcept = default;
+    GridData &operator=(GridData &&other) noexcept = default;
+
+  private:
+    EnvConfigCpp config_; // Store config by value now
+    int rows_;
+    int cols_;
+    std::vector<std::vector<bool>> occupied_grid_;
+    std::vector<std::vector<int8_t>> color_id_grid_;
+    std::vector<std::vector<bool>> death_grid_;
+
+    std::vector<Line> lines_;
+    CoordMap coord_to_lines_map_;
+
+    void precompute_lines();
+    bool is_live(int r, int c) const;
+    std::optional<Coord> get_neighbor(int r, int c, const std::string &direction, bool backward) const;
+  };
+
+} // namespace trianglengin::cpp
+
+#endif // TRIANGLENGIN_CPP_GRID_DATA_H

trianglengin/cpp/grid_logic.cpp

@@ -0,0 +1,125 @@
+
+#include "grid_logic.h"
+#include <stdexcept> // For potential errors, though can_place returns bool
+
+namespace trianglengin::cpp::grid_logic
+{
+
+  bool can_place(const GridData &grid_data, const ShapeCpp &shape, int r, int c)
+  {
+    if (shape.triangles.empty())
+    {
+      return false; // Cannot place an empty shape
+    }
+
+    for (const auto &tri_data : shape.triangles)
+    {
+      int dr, dc;
+      bool shape_is_up;
+      std::tie(dr, dc, shape_is_up) = tri_data;
+
+      int target_r = r + dr;
+      int target_c = c + dc;
+
+      // 1. Check bounds
+      if (!grid_data.is_valid(target_r, target_c))
+      {
+        return false;
+      }
+
+      // 2. Check death zone
+      if (grid_data.is_death(target_r, target_c))
+      {
+        return false;
+      }
+
+      // 3. Check occupancy
+      if (grid_data.is_occupied(target_r, target_c))
+      {
+        return false;
+      }
+
+      // 4. Check orientation match
+      bool grid_is_up = grid_data.is_up(target_r, target_c);
+      if (shape_is_up != grid_is_up)
+      {
+        return false;
+      }
+    }
+    // If all checks passed for all triangles
+    return true;
+  }
+
+  std::tuple<int, std::set<Coord>, LineFsSet> check_and_clear_lines(
+      GridData &grid_data,
+      const std::set<Coord> &newly_occupied_coords)
+  {
+    if (newly_occupied_coords.empty())
+    {
+      return {0, {}, {}};
+    }
+
+    const auto &coord_map = grid_data.get_coord_to_lines_map();
+    LineFsSet candidate_lines;
+
+    // 1. Find all maximal lines potentially affected by the new placements
+    for (const auto &coord : newly_occupied_coords)
+    {
+      auto it = coord_map.find(coord);
+      if (it != coord_map.end())
+      {
+        // Add all lines associated with this coordinate to the candidates
+        candidate_lines.insert(it->second.begin(), it->second.end());
+      }
+    }
+
+    LineFsSet lines_to_clear;
+    std::set<Coord> coords_to_clear;
+
+    // 2. Check each candidate line for completion
+    for (const auto &line_fs : candidate_lines)
+    {
+      if (line_fs.size() < 2)
+        continue; // Should not happen based on precomputation filter
+
+      bool line_complete = true;
+      for (const auto &coord : line_fs)
+      {
+        // A line is complete if ALL its coordinates are occupied
+        if (!grid_data.is_occupied(std::get<0>(coord), std::get<1>(coord)))
+        {
+          line_complete = false;
+          break;
+        }
+      }
+
+      if (line_complete)
+      {
+        lines_to_clear.insert(line_fs);
+        // Add coordinates from this completed line to the set to be cleared
+        coords_to_clear.insert(line_fs.begin(), line_fs.end());
+      }
+    }
+
+    // 3. Clear the identified coordinates
+    if (!coords_to_clear.empty())
+    {
+      auto &occupied_grid = grid_data.get_occupied_grid_mut();
+      auto &color_grid = grid_data.get_color_id_grid_mut();
+      for (const auto &coord : coords_to_clear)
+      {
+        int r = std::get<0>(coord);
+        int c = std::get<1>(coord);
+        // Ensure we don't try to clear out-of-bounds (shouldn't happen)
+        if (grid_data.is_valid(r, c))
+        {
+          occupied_grid[r][c] = false;
+          color_grid[r][c] = NO_COLOR_ID;
+        }
+      }
+    }
+
+    return {static_cast<int>(lines_to_clear.size()), coords_to_clear, lines_to_clear};
+  }
+
+} // namespace trianglengin::cpp::grid_logic

trianglengin/cpp/grid_logic.h

@@ -0,0 +1,30 @@
+// File: src/trianglengin/cpp/grid_logic.h
+#ifndef TRIANGLENGIN_CPP_GRID_LOGIC_H
+#define TRIANGLENGIN_CPP_GRID_LOGIC_H
+
+#pragma once
+
+#include <set>
+#include <tuple>
+#include <vector>
+
+#include "grid_data.h" // Needs GridData definition
+#include "structs.h"   // Needs ShapeCpp, Coord, LineFsSet definitions
+
+namespace trianglengin::cpp
+{
+
+  // Forward declare GameStateCpp if needed by functions here
+  class GameStateCpp;
+
+  namespace grid_logic
+  {
+    bool can_place(const GridData &grid_data, const ShapeCpp &shape, int r, int c);
+
+    std::tuple<int, std::set<Coord>, LineFsSet>
+    check_and_clear_lines(GridData &grid_data, const std::set<Coord> &newly_occupied_coords);
+
+  } // namespace grid_logic
+} // namespace trianglengin::cpp
+
+#endif // TRIANGLENGIN_CPP_GRID_LOGIC_H

trianglengin/cpp/shape_logic.cpp

@@ -0,0 +1,100 @@
+// File: src/trianglengin/cpp/shape_logic.cpp
+#include "shape_logic.h"
+#include "game_state.h" // Include full definition for implementation
+#include <stdexcept>
+#include <algorithm>
+
+namespace trianglengin::cpp::shape_logic
+{
+  // --- Shape Templates (Keep as defined previously) ---
+  const std::vector<std::vector<TriangleData>> PREDEFINED_SHAPE_TEMPLATES_CPP = {
+      {{0, 0, true}},
+      {{0, 0, true}},
+      {{0, 0, true}, {1, 0, false}},
+      {{0, 0, true}, {1, 0, false}},
+      {{0, 0, false}},
+      {{0, 0, true}, {0, 1, false}},
+      {{0, 0, true}, {0, 1, false}},
+      {{0, 0, false}, {0, 1, true}},
+      {{0, 0, false}, {0, 1, true}},
+      {{0, 0, true}, {0, 1, false}, {0, 2, true}},
+      {{0, 0, false}, {0, 1, true}, {0, 2, false}},
+      {{0, 0, true}, {0, 1, false}, {0, 2, true}, {1, 0, false}},
+      {{0, 0, true}, {0, 1, false}, {0, 2, true}, {1, 2, false}},
+      {{0, 0, false}, {0, 1, true}, {1, 0, true}, {1, 1, false}},
+      {{0, 0, true}, {0, 2, true}, {1, 0, false}, {1, 1, true}, {1, 2, false}},
+      {{0, 0, true}, {1, -2, false}, {1, -1, true}, {1, 0, false}},
+      {{0, 0, true}, {0, 1, false}, {1, 0, false}, {1, 1, true}},
+      {{0, 0, true}, {0, 1, false}, {1, 0, false}, {1, 1, true}, {1, 2, false}},
+      {{0, 0, true}, {0, 1, false}, {0, 2, true}, {1, 0, false}, {1, 1, true}},
+      {{0, 0, true}, {0, 1, false}, {0, 2, true}, {1, 0, false}, {1, 2, false}},
+      {{0, 0, true}, {0, 1, false}, {0, 2, true}, {1, 1, true}, {1, 2, false}},
+      {{0, 0, true}, {0, 2, true}, {1, 0, false}, {1, 1, true}, {1, 2, false}},
+      {{0, 0, true}, {0, 1, false}, {1, 0, false}, {1, 1, true}, {1, 2, false}},
+      {{0, 0, false}, {0, 1, true}, {1, 1, false}},
+      {{0, 0, true}, {1, -1, true}, {1, 0, false}},
+      {{0, 0, true}, {1, 0, false}, {1, 1, true}},
+      {{0, 0, true}, {1, -1, true}, {1, 0, false}, {1, 1, true}},
+      {{0, 0, true}, {1, -1, true}, {1, 0, false}},
+      {{0, 0, false}, {0, 1, true}, {0, 2, false}, {1, 1, false}},
+      {{0, 0, false}, {0, 1, true}, {1, 1, false}},
+      {{0, 0, true}, {0, 1, false}, {1, 0, false}},
+  };
+
+  const std::vector<ColorCpp> SHAPE_COLORS_CPP = {
+      {220, 40, 40}, {60, 60, 220}, {40, 200, 40}, {230, 230, 40}, {240, 150, 20}, {140, 40, 140}, {40, 200, 200}, {200, 100, 180}, {100, 180, 200}};
+  const std::vector<int> SHAPE_COLOR_IDS_CPP = {0, 1, 2, 3, 4, 5, 6, 7, 8};
+
+} // namespace trianglengin::cpp::shape_logic
+
+namespace trianglengin::cpp::shape_logic
+{
+
+  ShapeCpp generate_random_shape(
+      std::mt19937 &rng,
+      const std::vector<ColorCpp> &available_colors,
+      const std::vector<int> &available_color_ids)
+  {
+    if (PREDEFINED_SHAPE_TEMPLATES_CPP.empty() || available_colors.empty() || available_colors.size() != available_color_ids.size())
+    {
+      throw std::runtime_error("Shape templates or colors are not properly initialized.");
+    }
+
+    std::uniform_int_distribution<size_t> template_dist(0, PREDEFINED_SHAPE_TEMPLATES_CPP.size() - 1);
+    size_t template_index = template_dist(rng);
+    const auto &chosen_template = PREDEFINED_SHAPE_TEMPLATES_CPP[template_index];
+
+    std::uniform_int_distribution<size_t> color_dist(0, available_colors.size() - 1);
+    size_t color_index = color_dist(rng);
+    const auto &chosen_color = available_colors[color_index];
+    int chosen_color_id = available_color_ids[color_index];
+
+    return ShapeCpp(chosen_template, chosen_color, chosen_color_id);
+  }
+
+  void refill_shape_slots(GameStateCpp &game_state, std::mt19937 &rng)
+  {
+    bool needs_refill = true;
+    // Use the public getter to access shapes
+    for (const auto &shape_opt : game_state.get_shapes())
+    {
+      if (shape_opt.has_value())
+      {
+        needs_refill = false;
+        break;
+      }
+    }
+
+    if (!needs_refill)
+      return;
+
+    // Use the mutable getter to modify shapes
+    auto &shapes_ref = game_state.get_shapes_mut();
+    for (size_t i = 0; i < shapes_ref.size(); ++i)
+    {
+      shapes_ref[i] = generate_random_shape(rng, SHAPE_COLORS_CPP, SHAPE_COLOR_IDS_CPP);
+    }
+    game_state.invalidate_action_cache();
+  }
+
+} // namespace trianglengin::cpp::shape_logic

trianglengin/cpp/shape_logic.h

@@ -0,0 +1,28 @@
+// File: src/trianglengin/cpp/shape_logic.h
+#ifndef TRIANGLENGIN_CPP_SHAPE_LOGIC_H
+#define TRIANGLENGIN_CPP_SHAPE_LOGIC_H
+
+#pragma once
+
+#include <vector>
+#include <random>
+#include <optional>
+
+#include "structs.h" // Needs ShapeCpp definition
+
+namespace trianglengin::cpp
+{
+
+  // Forward declare GameStateCpp as it's used in function signatures
+  class GameStateCpp;
+
+  namespace shape_logic
+  {
+    std::vector<ShapeCpp> load_shape_templates();
+
+    void refill_shape_slots(GameStateCpp &game_state, std::mt19937 &rng);
+
+  } // namespace shape_logic
+} // namespace trianglengin::cpp
+
+#endif // TRIANGLENGIN_CPP_SHAPE_LOGIC_H

trianglengin/cpp/structs.h

@@ -0,0 +1,40 @@
+// File: src/trianglengin/cpp/structs.h
+#ifndef TRIANGLENGIN_CPP_STRUCTS_H
+#define TRIANGLENGIN_CPP_STRUCTS_H
+
+#pragma once
+
+#include <vector>
+#include <tuple>
+#include <string>
+#include <cstdint>
+#include <utility> // For std::move
+
+namespace trianglengin::cpp
+{
+  using Action = int;
+  using Coord = std::tuple<int, int>;
+  using ColorCpp = std::tuple<int, int, int>;
+  using TriangleData = std::tuple<int, int, bool>;
+
+  const int NO_COLOR_ID = -1;
+  const int DEBUG_COLOR_ID = -2;
+
+  struct ShapeCpp
+  {
+    std::vector<TriangleData> triangles;
+    ColorCpp color;
+    int color_id;
+
+    ShapeCpp() : color_id(NO_COLOR_ID) {}
+    ShapeCpp(std::vector<TriangleData> tris, ColorCpp c, int id)
+        : triangles(std::move(tris)), color(c), color_id(id) {}
+
+    bool operator==(const ShapeCpp &other) const
+    {
+      return triangles == other.triangles && color == other.color && color_id == other.color_id;
+    }
+  };
+} // namespace trianglengin::cpp
+
+#endif // TRIANGLENGIN_CPP_STRUCTS_H

trianglengin/game_interface.py

@@ -0,0 +1,222 @@
+# File: src/trianglengin/game_interface.py
+import logging
+import random
+from typing import Any, cast  # Import necessary types
+
+import numpy as np
+
+from .config import EnvConfig
+
+try:
+    import trianglengin.trianglengin_cpp as cpp_module
+except ImportError as e:
+    raise ImportError(
+        "Trianglengin C++ extension module ('trianglengin.trianglengin_cpp') not found. "
+        "Ensure the package was built correctly (`pip install -e .`). "
+        f"Original error: {e}"
+    ) from e
+
+
+class Shape:
+    """Python representation of a shape's data returned from C++."""
+
+    def __init__(
+        self,
+        triangles: list[tuple[int, int, bool]],
+        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
+
+    def bbox(self) -> tuple[int, int, int, int]:
+        """Calculates bounding box (min_r, min_c, max_r, max_c) in relative coords."""
+        if not self.triangles:
+            return (0, 0, 0, 0)
+        rows = [t[0] for t in self.triangles]
+        cols = [t[1] for t in self.triangles]
+        return (min(rows), min(cols), max(rows), max(cols))
+
+    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
+            and self.color_id == other.color_id
+        )
+
+    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:
+        return f"Shape(ColorID:{self.color_id}, Tris:{len(self.triangles)})"
+
+    def to_cpp_repr(
+        self,
+    ) -> tuple[list[tuple[int, int, bool]], tuple[int, int, int], int]:
+        """Converts this Python Shape object to the tuple format expected by C++ bindings."""
+        return self.triangles, self.color, self.color_id
+
+
+log = logging.getLogger(__name__)
+
+
+class GameState:
+    """
+    Python wrapper for the C++ GameState implementation.
+    Provides a Pythonic interface to the core game logic.
+    """
+
+    _cpp_state: cpp_module.GameStateCpp  # Add type hint for instance variable
+
+    def __init__(
+        self, config: EnvConfig | None = None, initial_seed: int | None = None
+    ):
+        self.env_config: EnvConfig = config if config else EnvConfig()
+        used_seed = (
+            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}")
+            raise
+        self._cached_shapes: list[Shape | None] | None = None
+        self._cached_grid_data: dict[str, np.ndarray] | None = None
+
+    def reset(self) -> None:
+        """Resets the game to an initial state."""
+        self._cpp_state.reset()
+        self._clear_caches()
+        log.debug("Python GameState wrapper reset.")
+
+    def step(self, action: int) -> tuple[float, bool]:
+        """
+        Performs one game step based on the chosen action index.
+        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 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))
+        )
+
+    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,
+                    )
+                    self._cached_shapes.append(Shape(tris_py, color_py, id_py))
+        return self._cached_shapes
+
+    def get_grid_data_np(self) -> dict[str, np.ndarray]:
+        """
+        Returns the grid state (occupied, colors, death) as NumPy arrays.
+        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()
+            self._cached_grid_data = {
+                "occupied": occupied_np,
+                "color_id": color_id_np,
+                "death": death_np,
+            }
+        return self._cached_grid_data
+
+    @property
+    def current_step(self) -> int:
+        """Returns the current step count."""
+        return cast("int", self._cpp_state.get_current_step())
+
+    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())
+
+    def copy(self) -> "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._cached_shapes = None
+        new_wrapper._cached_grid_data = None
+        return new_wrapper
+
+    def debug_toggle_cell(self, r: int, c: int) -> None:
+        """Toggles the state of a cell via the C++ implementation."""
+        self._cpp_state.debug_toggle_cell(r, c)
+        self._clear_caches()
+
+    def debug_set_shapes(self, shapes: list[Shape | None]) -> None:
+        """
+        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
+
+    def _clear_caches(self) -> None:
+        """Clears Python-level caches."""
+        self._cached_shapes = None
+        self._cached_grid_data = None
+
+    def __str__(self) -> str:
+        shapes_repr = [str(s) if s else "None" for s in self.get_shapes()]
+        status = "Over" if self.is_over() else "Ongoing"
+        return (
+            f"GameState(Step:{self.current_step}, Score:{self.game_score():.1f}, "
+            f"Status:{status}, Shapes:[{', '.join(shapes_repr)}])"
+        )
+
+    @property
+    def cpp_state(self) -> Any:
+        """Returns the underlying C++ GameState object."""
+        return self._cpp_state

trianglengin/ui/README.md

@@ -0,0 +1,35 @@
+
+
+# UI Module (`trianglengin.ui`)
+
+## Purpose
+
+This module provides components for interacting with and visualizing the `trianglengin` game engine using Pygame and Typer. It is included as part of the main package installation.
+
+## Components
+
+-   **[`config.py`](config.py):** Defines `DisplayConfig` for UI-specific settings (screen size, FPS, fonts, colors).
+-   **[`visualization/`](visualization/README.md):** Contains the `Visualizer` class and drawing functions responsible for rendering the game state using Pygame.
+-   **[`interaction/`](interaction/README.md):** Contains the `InputHandler` class and helper functions to process keyboard/mouse input for interactive modes.
+-   **[`app.py`](app.py):** The `Application` class integrates the `GameState` (from the core engine), `Visualizer`, and `InputHandler` to run the interactive application loop.
+-   **[`cli.py`](cli.py):** Defines the command-line interface using Typer, providing the `trianglengin play` and `trianglengin debug` commands.
+
+## Usage
+
+After installing the `trianglengin` package (`pip install trianglengin`), you can run the interactive commands:
+
+```bash
+trianglengin play
+trianglengin debug --seed 123
+```
+
+## Dependencies
+
+-   **`trianglengin` (core):** Uses `GameState`, `EnvConfig`, `Shape`.
+-   **`pygame`**: Required dependency for graphics, event handling, fonts.
+-   **`typer`**: Required dependency for the command-line interface.
+-   **Standard Libraries:** `typing`, `logging`, `sys`, `random`.
+
+---
+
+**Note:** While included, these UI components are designed to be initialized only when running the specific CLI commands (`play`, `debug`) and should not interfere with using the core `trianglengin` library for simulations.

trianglengin/ui/__init__.py

@@ -0,0 +1,21 @@
+# src/trianglengin/ui/__init__.py
+"""
+UI components for the Triangle Engine, including interactive modes
+and visualization. Requires 'pygame' and 'typer'.
+"""
+
+# Directly import the components. Dependencies are now required.
+from .app import Application
+from .cli import app as cli_app
+from .config import DEFAULT_DISPLAY_CONFIG, DisplayConfig
+from .interaction import InputHandler
+from .visualization import Visualizer
+
+__all__ = [
+    "Application",
+    "cli_app",
+    "DisplayConfig",
+    "DEFAULT_DISPLAY_CONFIG",
+    "InputHandler",
+    "Visualizer",
+]