trianglengin 1.0.6__tar.gz → 2.0.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. trianglengin-2.0.1/MANIFEST.in +26 -0
  2. trianglengin-2.0.1/PKG-INFO +250 -0
  3. trianglengin-2.0.1/README.md +215 -0
  4. trianglengin-2.0.1/pyproject.toml +132 -0
  5. trianglengin-2.0.1/setup.py +172 -0
  6. trianglengin-2.0.1/src/trianglengin/__init__.py +35 -0
  7. trianglengin-2.0.1/src/trianglengin/config/README.md +38 -0
  8. trianglengin-2.0.1/src/trianglengin/config/__init__.py +8 -0
  9. trianglengin-2.0.1/src/trianglengin/config/env_config.py +62 -0
  10. trianglengin-2.0.1/src/trianglengin/core/__init__.py +10 -0
  11. trianglengin-2.0.1/src/trianglengin/cpp/CMakeLists.txt +42 -0
  12. trianglengin-2.0.1/src/trianglengin/cpp/bindings.cpp +211 -0
  13. trianglengin-2.0.1/src/trianglengin/cpp/config.h +28 -0
  14. trianglengin-2.0.1/src/trianglengin/cpp/game_state.cpp +327 -0
  15. trianglengin-2.0.1/src/trianglengin/cpp/game_state.h +73 -0
  16. trianglengin-2.0.1/src/trianglengin/cpp/grid_data.cpp +239 -0
  17. trianglengin-2.0.1/src/trianglengin/cpp/grid_data.h +78 -0
  18. trianglengin-2.0.1/src/trianglengin/cpp/grid_logic.cpp +125 -0
  19. trianglengin-2.0.1/src/trianglengin/cpp/grid_logic.h +30 -0
  20. trianglengin-2.0.1/src/trianglengin/cpp/shape_logic.cpp +100 -0
  21. trianglengin-2.0.1/src/trianglengin/cpp/shape_logic.h +28 -0
  22. trianglengin-2.0.1/src/trianglengin/cpp/structs.h +40 -0
  23. trianglengin-2.0.1/src/trianglengin/game_interface.py +222 -0
  24. trianglengin-2.0.1/src/trianglengin/ui/README.md +35 -0
  25. trianglengin-2.0.1/src/trianglengin/ui/__init__.py +21 -0
  26. {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/app.py +19 -22
  27. {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/cli.py +29 -40
  28. trianglengin-1.0.6/trianglengin/config/display_config.py → trianglengin-2.0.1/src/trianglengin/ui/config.py +6 -9
  29. {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/interaction/README.md +15 -16
  30. {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/interaction/__init__.py +2 -0
  31. trianglengin-2.0.1/src/trianglengin/ui/interaction/debug_mode_handler.py +72 -0
  32. {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/interaction/event_processor.py +8 -2
  33. {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/interaction/input_handler.py +20 -13
  34. trianglengin-2.0.1/src/trianglengin/ui/interaction/play_mode_handler.py +156 -0
  35. {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/README.md +11 -13
  36. {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/__init__.py +20 -23
  37. {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/core/README.md +15 -16
  38. trianglengin-2.0.1/src/trianglengin/ui/visualization/core/__init__.py +16 -0
  39. {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/core/colors.py +13 -15
  40. {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/core/coord_mapper.py +22 -10
  41. {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/core/fonts.py +11 -1
  42. trianglengin-2.0.1/src/trianglengin/ui/visualization/core/layout.py +77 -0
  43. {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/core/visualizer.py +55 -39
  44. {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/drawing/README.md +9 -5
  45. trianglengin-2.0.1/src/trianglengin/ui/visualization/drawing/__init__.py +43 -0
  46. trianglengin-2.0.1/src/trianglengin/ui/visualization/drawing/grid.py +213 -0
  47. {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/drawing/highlight.py +12 -11
  48. {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/drawing/hud.py +8 -4
  49. {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/drawing/previews.py +44 -35
  50. trianglengin-2.0.1/src/trianglengin/ui/visualization/drawing/shapes.py +46 -0
  51. trianglengin-2.0.1/src/trianglengin/ui/visualization/drawing/utils.py +23 -0
  52. {trianglengin-1.0.6 → trianglengin-2.0.1/src}/trianglengin/utils/geometry.py +13 -24
  53. trianglengin-2.0.1/src/trianglengin.egg-info/PKG-INFO +250 -0
  54. trianglengin-2.0.1/src/trianglengin.egg-info/SOURCES.txt +70 -0
  55. trianglengin-2.0.1/src/trianglengin.egg-info/entry_points.txt +2 -0
  56. trianglengin-2.0.1/src/trianglengin.egg-info/not-zip-safe +1 -0
  57. {trianglengin-1.0.6 → trianglengin-2.0.1/src}/trianglengin.egg-info/top_level.txt +0 -2
  58. trianglengin-2.0.1/tests/conftest.py +113 -0
  59. trianglengin-2.0.1/tests/core/environment/README.md +38 -0
  60. trianglengin-2.0.1/tests/core/environment/test_game_state.py +482 -0
  61. {trianglengin-1.0.6 → trianglengin-2.0.1}/tests/utils/test_geometry.py +25 -54
  62. trianglengin-1.0.6/MANIFEST.in +0 -7
  63. trianglengin-1.0.6/PKG-INFO +0 -367
  64. trianglengin-1.0.6/README.md +0 -311
  65. trianglengin-1.0.6/pyproject.toml +0 -100
  66. trianglengin-1.0.6/tests/conftest.py +0 -108
  67. trianglengin-1.0.6/tests/core/environment/README.md +0 -47
  68. trianglengin-1.0.6/tests/core/environment/test_action_codec.py +0 -50
  69. trianglengin-1.0.6/tests/core/environment/test_game_state.py +0 -483
  70. trianglengin-1.0.6/tests/core/environment/test_grid_data.py +0 -205
  71. trianglengin-1.0.6/tests/core/environment/test_grid_logic.py +0 -362
  72. trianglengin-1.0.6/tests/core/environment/test_shape_logic.py +0 -171
  73. trianglengin-1.0.6/tests/core/environment/test_step.py +0 -372
  74. trianglengin-1.0.6/tests/core/structs/test_shape.py +0 -83
  75. trianglengin-1.0.6/tests/core/structs/test_triangle.py +0 -97
  76. trianglengin-1.0.6/trianglengin/__init__.py +0 -18
  77. trianglengin-1.0.6/trianglengin/config/__init__.py +0 -9
  78. trianglengin-1.0.6/trianglengin/config/env_config.py +0 -103
  79. trianglengin-1.0.6/trianglengin/core/__init__.py +0 -8
  80. trianglengin-1.0.6/trianglengin/core/environment/__init__.py +0 -31
  81. trianglengin-1.0.6/trianglengin/core/environment/action_codec.py +0 -37
  82. trianglengin-1.0.6/trianglengin/core/environment/game_state.py +0 -217
  83. trianglengin-1.0.6/trianglengin/core/environment/grid/README.md +0 -46
  84. trianglengin-1.0.6/trianglengin/core/environment/grid/__init__.py +0 -18
  85. trianglengin-1.0.6/trianglengin/core/environment/grid/grid_data.py +0 -140
  86. trianglengin-1.0.6/trianglengin/core/environment/grid/line_cache.py +0 -189
  87. trianglengin-1.0.6/trianglengin/core/environment/grid/logic.py +0 -131
  88. trianglengin-1.0.6/trianglengin/core/environment/logic/__init__.py +0 -3
  89. trianglengin-1.0.6/trianglengin/core/environment/logic/actions.py +0 -38
  90. trianglengin-1.0.6/trianglengin/core/environment/logic/step.py +0 -134
  91. trianglengin-1.0.6/trianglengin/core/environment/shapes/__init__.py +0 -19
  92. trianglengin-1.0.6/trianglengin/core/environment/shapes/logic.py +0 -84
  93. trianglengin-1.0.6/trianglengin/core/environment/shapes/templates.py +0 -587
  94. trianglengin-1.0.6/trianglengin/core/structs/__init__.py +0 -27
  95. trianglengin-1.0.6/trianglengin/core/structs/constants.py +0 -28
  96. trianglengin-1.0.6/trianglengin/core/structs/shape.py +0 -61
  97. trianglengin-1.0.6/trianglengin/core/structs/triangle.py +0 -48
  98. trianglengin-1.0.6/trianglengin/interaction/debug_mode_handler.py +0 -96
  99. trianglengin-1.0.6/trianglengin/interaction/play_mode_handler.py +0 -141
  100. trianglengin-1.0.6/trianglengin/visualization/core/__init__.py +0 -12
  101. trianglengin-1.0.6/trianglengin/visualization/core/layout.py +0 -101
  102. trianglengin-1.0.6/trianglengin/visualization/drawing/__init__.py +0 -30
  103. trianglengin-1.0.6/trianglengin/visualization/drawing/grid.py +0 -156
  104. trianglengin-1.0.6/trianglengin/visualization/drawing/shapes.py +0 -36
  105. trianglengin-1.0.6/trianglengin.egg-info/PKG-INFO +0 -367
  106. trianglengin-1.0.6/trianglengin.egg-info/SOURCES.txt +0 -76
  107. trianglengin-1.0.6/trianglengin.egg-info/entry_points.txt +0 -2
  108. {trianglengin-1.0.6 → trianglengin-2.0.1}/LICENSE +0 -0
  109. {trianglengin-1.0.6 → trianglengin-2.0.1}/setup.cfg +0 -0
  110. /trianglengin-1.0.6/tests/__init__.py → /trianglengin-2.0.1/src/trianglengin/py.typed +0 -0
  111. {trianglengin-1.0.6 → trianglengin-2.0.1/src}/trianglengin/utils/__init__.py +0 -0
  112. {trianglengin-1.0.6 → trianglengin-2.0.1/src}/trianglengin/utils/types.py +0 -0
  113. {trianglengin-1.0.6 → trianglengin-2.0.1/src}/trianglengin.egg-info/dependency_links.txt +0 -0
  114. {trianglengin-1.0.6 → trianglengin-2.0.1/src}/trianglengin.egg-info/requires.txt +0 -0
  115. {trianglengin-1.0.6/tests/core/structs → trianglengin-2.0.1/tests}/__init__.py +0 -0
  116. {trianglengin-1.0.6 → trianglengin-2.0.1}/tests/core/__init__.py +0 -0
  117. {trianglengin-1.0.6 → trianglengin-2.0.1}/tests/core/environment/__init__.py +0 -0
  118. {trianglengin-1.0.6 → trianglengin-2.0.1}/tests/utils/__init__.py +0 -0
@@ -0,0 +1,26 @@
1
+
2
+ # File: MANIFEST.in
3
+ include README.md
4
+ include LICENSE
5
+ include pyproject.toml
6
+ include setup.py
7
+
8
+ # Include Python source files from src directory
9
+ graft src/trianglengin
10
+ # Include all tests generically
11
+ graft tests
12
+
13
+ # Include C++ source files and CMakeLists.txt
14
+ graft src/trianglengin/cpp
15
+
16
+ # Include the py.typed marker file
17
+ include src/trianglengin/py.typed
18
+
19
+ # Exclude specific files no longer present
20
+ exclude src/trianglengin/config/display_config.py
21
+ exclude src/trianglengin/core/environment/shapes/templates.py
22
+
23
+ # Exclude build artifacts and caches
24
+ global-exclude __pycache__ *.py[co] *.so *.pyd *.dylib *.egg-info CMakeCache.txt CMakeFiles
25
+ prune build
26
+ prune dist
@@ -0,0 +1,250 @@
1
+ Metadata-Version: 2.4
2
+ Name: trianglengin
3
+ Version: 2.0.1
4
+ Summary: High-performance C++/Python engine for a triangle puzzle game.
5
+ Author-email: "Luis Guilherme P. M." <lgpelin92@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/lguibr/trianglengin
8
+ Project-URL: Bug Tracker, https://github.com/lguibr/trianglengin/issues
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Programming Language :: Python :: 3.10
11
+ Classifier: Programming Language :: Python :: 3.11
12
+ Classifier: Programming Language :: C++
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
15
+ Classifier: Topic :: Games/Entertainment :: Puzzle Games
16
+ Classifier: Development Status :: 4 - Beta
17
+ Requires-Python: >=3.10
18
+ Description-Content-Type: text/markdown
19
+ License-File: LICENSE
20
+ Requires-Dist: numpy>=1.20.0
21
+ Requires-Dist: pydantic>=2.0.0
22
+ Requires-Dist: typing_extensions>=4.0.0
23
+ Requires-Dist: pygame>=2.1.0
24
+ Requires-Dist: typer[all]>=0.9.0
25
+ Provides-Extra: dev
26
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
27
+ Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
28
+ Requires-Dist: pytest-mock>=3.0.0; extra == "dev"
29
+ Requires-Dist: ruff; extra == "dev"
30
+ Requires-Dist: mypy; extra == "dev"
31
+ Requires-Dist: build; extra == "dev"
32
+ Requires-Dist: twine; extra == "dev"
33
+ Requires-Dist: codecov; extra == "dev"
34
+ Dynamic: license-file
35
+
36
+
37
+ [![CI Status](https://github.com/lguibr/trianglengin/actions/workflows/ci_cd.yml/badge.svg)](https://github.com/lguibr/trianglengin/actions/workflows/ci_cd.yml)
38
+ [![codecov](https://codecov.io/gh/lguibr/trianglengin/graph/badge.svg?token=YOUR_CODECOV_TOKEN_HERE&flag=trianglengin)](https://codecov.io/gh/lguibr/trianglengin)
39
+ [![PyPI version](https://badge.fury.io/py/trianglengin.svg)](https://badge.fury.io/py/trianglengin)
40
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
41
+ [![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
42
+
43
+ # Triangle Engine (`trianglengin`) v2
44
+ <img src="bitmap.png" alt="trianglengin logo" width="300"/>
45
+
46
+ **Version 2 introduces a high-performance C++ core for the game logic.**
47
+
48
+ This library provides the core components for a triangle puzzle game, suitable for reinforcement learning agents or other applications requiring a fast game engine. Interactive play/debug modes are included.
49
+
50
+ It encapsulates:
51
+
52
+ 1. **Core Game Logic (C++):** High-performance implementation of environment rules, state representation, actions, placement validation, and line clearing. ([`src/trianglengin/cpp/README.md`](src/trianglengin/cpp/README.md))
53
+ 2. **Python Interface:** A Python `GameState` wrapper providing a user-friendly API to interact with the C++ core. ([`src/trianglengin/game_interface.py`](src/trianglengin/game_interface.py))
54
+ 3. **Configuration (Python/Pydantic):** Models for environment settings (`EnvConfig`). ([`src/trianglengin/config/README.md`](src/trianglengin/config/README.md))
55
+ 4. **Utilities (Python):** General helpers, geometry functions, shared types. ([`src/trianglengin/utils/README.md`](src/trianglengin/utils/README.md))
56
+ 5. **UI Components (Python/Pygame/Typer):** Basic visualization, interaction handling, and CLI for interactive modes. ([`src/trianglengin/ui/README.md`](src/trianglengin/ui/README.md))
57
+
58
+ ---
59
+
60
+ ## 🎮 The Ultimate Triangle Puzzle Guide 🧩
61
+
62
+ *(Game rules remain the same)*
63
+
64
+ *(... Game rules section remains unchanged ...)*
65
+
66
+ ---
67
+
68
+ ## Purpose
69
+
70
+ 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.
71
+
72
+ ## Installation
73
+
74
+ **Prerequisites:**
75
+ * A C++ compiler supporting C++17 (e.g., GCC, Clang, MSVC).
76
+ * CMake (version 3.14 or higher).
77
+ * Python (>= 3.10) and Pip.
78
+
79
+ ```bash
80
+ # For standard use (once published or built):
81
+ pip install trianglengin
82
+
83
+ # Building from source (requires compiler and CMake):
84
+ git clone https://github.com/lguibr/trianglengin.git
85
+ cd trianglengin
86
+ pip install .
87
+ ```
88
+ *(Note: `pygame` and `typer` will be installed as core dependencies).*
89
+
90
+ ## Running Interactive Modes
91
+
92
+ After installing, you can run the interactive modes directly:
93
+
94
+ - **Play Mode:**
95
+ ```bash
96
+ trianglengin play [--seed 42] [--log-level INFO]
97
+ ```
98
+ - **Debug Mode:**
99
+ ```bash
100
+ trianglengin debug [--seed 42] [--log-level DEBUG]
101
+ ```
102
+
103
+ ---
104
+
105
+ ## Local Development & Testing
106
+
107
+ These instructions are for developers contributing to `trianglengin`.
108
+
109
+ 1. **Clone the Repository:**
110
+ ```bash
111
+ git clone https://github.com/lguibr/trianglengin.git
112
+ cd trianglengin
113
+ ```
114
+
115
+ 2. **Prerequisites:** Ensure you have a C++17 compiler and CMake installed.
116
+
117
+ 3. **Create and Activate Virtual Environment:** (venv or conda)
118
+ ```bash
119
+ # Example using venv
120
+ python -m venv venv
121
+ source venv/bin/activate # or .\venv\Scripts\activate on Windows
122
+ ```
123
+ **IMPORTANT:** Ensure your virtual environment is activated.
124
+
125
+ 4. **Install Build Dependencies:** (Needed even for core dev)
126
+ ```bash
127
+ pip install pybind11>=2.10 cmake wheel
128
+ ```
129
+
130
+ 5. **Clean Previous Builds (Optional but Recommended):**
131
+ ```bash
132
+ rm -rf build/ src/trianglengin.egg-info/ dist/ src/trianglengin/trianglengin_cpp.*.so src/trianglengin/trianglengin_cpp*.cpp
133
+ ```
134
+
135
+ 6. **Install in Editable Mode with Dev Dependencies:**
136
+ * **Make sure your virtual environment is active!**
137
+ * Run from the project root directory:
138
+ ```bash
139
+ # Installs core, UI, and dev tools
140
+ pip install -e '.[dev]'
141
+ ```
142
+ This command compiles the C++ extension and installs the Python package so changes are reflected immediately. It also installs development tools.
143
+
144
+ 7. **Running Checks:**
145
+ * **Make sure your virtual environment is active!**
146
+ * **Tests & Coverage:**
147
+ ```bash
148
+ pytest tests/ --cov=src/trianglengin --cov-report=xml
149
+ ```
150
+ (Coverage measures core Python code, excluding UI).
151
+ To just run tests: `pytest`
152
+ * **Linting:** `ruff check .`
153
+ * **Formatting:** `ruff format .`
154
+ * **Type Checking:** `mypy src/trianglengin/ tests/`
155
+
156
+ 8. **Troubleshooting Build/Import Errors:**
157
+ * Ensure compiler and CMake are installed and in PATH.
158
+ * Make sure the virtual environment is active *before* running `pip install -e`.
159
+ * Clean previous builds (Step 5).
160
+ * Check `pyproject.toml` and `setup.py` for correct configuration.
161
+ * Verify Pybind11 version compatibility.
162
+
163
+ ---
164
+
165
+ ## Project Structure (v2 - UI Included)
166
+
167
+ ```
168
+ trianglengin/
169
+ ├── .github/workflows/ # GitHub Actions CI/CD
170
+ │ └── ci_cd.yml
171
+ ├── src/ # Source root
172
+ │ └── trianglengin/ # Python package source
173
+ │ ├── __init__.py # Exposes core public API (GameState, EnvConfig, Shape)
174
+ │ ├── game_interface.py # Python GameState wrapper class
175
+ │ ├── py.typed # PEP 561 marker
176
+ │ ├── cpp/ # C++ Core Implementation ([src/trianglengin/cpp/README.md])
177
+ │ │ ├── CMakeLists.txt
178
+ │ │ ├── bindings.cpp
179
+ │ │ ├── config.h
180
+ │ │ ├── structs.h
181
+ │ │ ├── grid_data.h / .cpp
182
+ │ │ ├── grid_logic.h / .cpp
183
+ │ │ ├── shape_logic.h / .cpp
184
+ │ │ └── game_state.h / .cpp
185
+ │ ├── core/ # Core Python components (now minimal/empty)
186
+ │ │ └── __init__.py
187
+ │ ├── utils/ # General Python utilities ([src/trianglengin/utils/README.md])
188
+ │ │ └── ... (geometry.py, types.py)
189
+ │ ├── config/ # Core configuration models ([src/trianglengin/config/README.md])
190
+ │ │ ├── __init__.py
191
+ │ │ └── env_config.py # EnvConfig (Pydantic)
192
+ │ └── ui/ # UI Components ([src/trianglengin/ui/README.md])
193
+ │ ├── __init__.py # Exposes UI API (Application, cli_app, DisplayConfig)
194
+ │ ├── app.py # Interactive mode application runner
195
+ │ ├── cli.py # CLI definition (play/debug)
196
+ │ ├── config.py # DisplayConfig (Pydantic)
197
+ │ ├── interaction/ # User input handling ([src/trianglengin/ui/interaction/README.md])
198
+ │ │ ├── __init__.py
199
+ │ │ ├── event_processor.py
200
+ │ │ ├── input_handler.py
201
+ │ │ ├── play_mode_handler.py
202
+ │ │ └── debug_mode_handler.py
203
+ │ └── visualization/ # Pygame rendering ([src/trianglengin/ui/visualization/README.md])
204
+ │ ├── __init__.py
205
+ │ ├── core/ # Core vis components ([src/trianglengin/ui/visualization/core/README.md])
206
+ │ │ ├── __init__.py
207
+ │ │ ├── colors.py
208
+ │ │ ├── coord_mapper.py
209
+ │ │ ├── fonts.py
210
+ │ │ ├── layout.py # NEW
211
+ │ │ └── visualizer.py
212
+ │ └── drawing/ # Drawing functions ([src/trianglengin/ui/visualization/drawing/README.md])
213
+ │ ├── __init__.py
214
+ │ ├── grid.py
215
+ │ ├── highlight.py
216
+ │ ├── hud.py
217
+ │ ├── previews.py
218
+ │ ├── shapes.py
219
+ │ └── utils.py
220
+ ├── tests/ # Unit/Integration tests (Python) ([tests/README.md])
221
+ │ ├── __init__.py
222
+ │ ├── conftest.py
223
+ │ └── core/environment/
224
+ │ └── test_game_state.py # Tests the Python GameState wrapper
225
+ ├── .gitignore
226
+ ├── pyproject.toml # Build config, dependencies
227
+ ├── setup.py # C++ Extension build script
228
+ ├── README.md # This file
229
+ ├── LICENSE
230
+ └── MANIFEST.in
231
+ ```
232
+
233
+ ## Core Components (v2)
234
+
235
+ - **`trianglengin.cpp` (C++ Core)**: Implements the high-performance game logic (state, grid, shapes, rules). Not directly imported in Python.
236
+ - **`trianglengin.game_interface.GameState` (Python Wrapper)**: The primary Python class for interacting with the game engine. It holds a reference to the C++ game state object and provides methods like `step`, `reset`, `is_over`, `valid_actions`, `get_shapes`, `get_grid_data_np`.
237
+ - **`trianglengin.config.EnvConfig`**: Python Pydantic model for core environment configuration. Passed to C++ core during initialization.
238
+ - **`trianglengin.utils`**: General Python utility functions and types. ([`src/trianglengin/utils/README.md`](src/trianglengin/utils/README.md))
239
+
240
+ ## UI Components (`trianglengin.ui`)
241
+
242
+ - **`trianglengin.ui.config.DisplayConfig`**: Pydantic model for UI display settings.
243
+ - **`trianglengin.ui.visualization`**: Python/Pygame rendering components. Uses data obtained from the `GameState` wrapper. ([`src/trianglengin/ui/visualization/README.md`](src/trianglengin/ui/visualization/README.md))
244
+ - **`trianglengin.ui.interaction`**: Python/Pygame input handling for interactive modes. Interacts with the `GameState` wrapper. ([`src/trianglengin/ui/interaction/README.md`](src/trianglengin/ui/interaction/README.md))
245
+ - **`trianglengin.ui.app.Application`**: Integrates UI components for interactive modes.
246
+ - **`trianglengin.ui.cli`**: Command-line interface (`trianglengin play`/`debug`).
247
+
248
+ ## Contributing
249
+
250
+ Contributions are welcome! Please open an issue or submit a pull request on the [GitHub repository](https://github.com/lguibr/trianglengin). Ensure that changes maintain code quality (pass tests, linting, type checking) and keep READMEs updated. Building requires a C++17 compiler and CMake.
@@ -0,0 +1,215 @@
1
+
2
+ [![CI Status](https://github.com/lguibr/trianglengin/actions/workflows/ci_cd.yml/badge.svg)](https://github.com/lguibr/trianglengin/actions/workflows/ci_cd.yml)
3
+ [![codecov](https://codecov.io/gh/lguibr/trianglengin/graph/badge.svg?token=YOUR_CODECOV_TOKEN_HERE&flag=trianglengin)](https://codecov.io/gh/lguibr/trianglengin)
4
+ [![PyPI version](https://badge.fury.io/py/trianglengin.svg)](https://badge.fury.io/py/trianglengin)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6
+ [![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
7
+
8
+ # Triangle Engine (`trianglengin`) v2
9
+ <img src="bitmap.png" alt="trianglengin logo" width="300"/>
10
+
11
+ **Version 2 introduces a high-performance C++ core for the game logic.**
12
+
13
+ This library provides the core components for a triangle puzzle game, suitable for reinforcement learning agents or other applications requiring a fast game engine. Interactive play/debug modes are included.
14
+
15
+ It encapsulates:
16
+
17
+ 1. **Core Game Logic (C++):** High-performance implementation of environment rules, state representation, actions, placement validation, and line clearing. ([`src/trianglengin/cpp/README.md`](src/trianglengin/cpp/README.md))
18
+ 2. **Python Interface:** A Python `GameState` wrapper providing a user-friendly API to interact with the C++ core. ([`src/trianglengin/game_interface.py`](src/trianglengin/game_interface.py))
19
+ 3. **Configuration (Python/Pydantic):** Models for environment settings (`EnvConfig`). ([`src/trianglengin/config/README.md`](src/trianglengin/config/README.md))
20
+ 4. **Utilities (Python):** General helpers, geometry functions, shared types. ([`src/trianglengin/utils/README.md`](src/trianglengin/utils/README.md))
21
+ 5. **UI Components (Python/Pygame/Typer):** Basic visualization, interaction handling, and CLI for interactive modes. ([`src/trianglengin/ui/README.md`](src/trianglengin/ui/README.md))
22
+
23
+ ---
24
+
25
+ ## 🎮 The Ultimate Triangle Puzzle Guide 🧩
26
+
27
+ *(Game rules remain the same)*
28
+
29
+ *(... Game rules section remains unchanged ...)*
30
+
31
+ ---
32
+
33
+ ## Purpose
34
+
35
+ 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.
36
+
37
+ ## Installation
38
+
39
+ **Prerequisites:**
40
+ * A C++ compiler supporting C++17 (e.g., GCC, Clang, MSVC).
41
+ * CMake (version 3.14 or higher).
42
+ * Python (>= 3.10) and Pip.
43
+
44
+ ```bash
45
+ # For standard use (once published or built):
46
+ pip install trianglengin
47
+
48
+ # Building from source (requires compiler and CMake):
49
+ git clone https://github.com/lguibr/trianglengin.git
50
+ cd trianglengin
51
+ pip install .
52
+ ```
53
+ *(Note: `pygame` and `typer` will be installed as core dependencies).*
54
+
55
+ ## Running Interactive Modes
56
+
57
+ After installing, you can run the interactive modes directly:
58
+
59
+ - **Play Mode:**
60
+ ```bash
61
+ trianglengin play [--seed 42] [--log-level INFO]
62
+ ```
63
+ - **Debug Mode:**
64
+ ```bash
65
+ trianglengin debug [--seed 42] [--log-level DEBUG]
66
+ ```
67
+
68
+ ---
69
+
70
+ ## Local Development & Testing
71
+
72
+ These instructions are for developers contributing to `trianglengin`.
73
+
74
+ 1. **Clone the Repository:**
75
+ ```bash
76
+ git clone https://github.com/lguibr/trianglengin.git
77
+ cd trianglengin
78
+ ```
79
+
80
+ 2. **Prerequisites:** Ensure you have a C++17 compiler and CMake installed.
81
+
82
+ 3. **Create and Activate Virtual Environment:** (venv or conda)
83
+ ```bash
84
+ # Example using venv
85
+ python -m venv venv
86
+ source venv/bin/activate # or .\venv\Scripts\activate on Windows
87
+ ```
88
+ **IMPORTANT:** Ensure your virtual environment is activated.
89
+
90
+ 4. **Install Build Dependencies:** (Needed even for core dev)
91
+ ```bash
92
+ pip install pybind11>=2.10 cmake wheel
93
+ ```
94
+
95
+ 5. **Clean Previous Builds (Optional but Recommended):**
96
+ ```bash
97
+ rm -rf build/ src/trianglengin.egg-info/ dist/ src/trianglengin/trianglengin_cpp.*.so src/trianglengin/trianglengin_cpp*.cpp
98
+ ```
99
+
100
+ 6. **Install in Editable Mode with Dev Dependencies:**
101
+ * **Make sure your virtual environment is active!**
102
+ * Run from the project root directory:
103
+ ```bash
104
+ # Installs core, UI, and dev tools
105
+ pip install -e '.[dev]'
106
+ ```
107
+ This command compiles the C++ extension and installs the Python package so changes are reflected immediately. It also installs development tools.
108
+
109
+ 7. **Running Checks:**
110
+ * **Make sure your virtual environment is active!**
111
+ * **Tests & Coverage:**
112
+ ```bash
113
+ pytest tests/ --cov=src/trianglengin --cov-report=xml
114
+ ```
115
+ (Coverage measures core Python code, excluding UI).
116
+ To just run tests: `pytest`
117
+ * **Linting:** `ruff check .`
118
+ * **Formatting:** `ruff format .`
119
+ * **Type Checking:** `mypy src/trianglengin/ tests/`
120
+
121
+ 8. **Troubleshooting Build/Import Errors:**
122
+ * Ensure compiler and CMake are installed and in PATH.
123
+ * Make sure the virtual environment is active *before* running `pip install -e`.
124
+ * Clean previous builds (Step 5).
125
+ * Check `pyproject.toml` and `setup.py` for correct configuration.
126
+ * Verify Pybind11 version compatibility.
127
+
128
+ ---
129
+
130
+ ## Project Structure (v2 - UI Included)
131
+
132
+ ```
133
+ trianglengin/
134
+ ├── .github/workflows/ # GitHub Actions CI/CD
135
+ │ └── ci_cd.yml
136
+ ├── src/ # Source root
137
+ │ └── trianglengin/ # Python package source
138
+ │ ├── __init__.py # Exposes core public API (GameState, EnvConfig, Shape)
139
+ │ ├── game_interface.py # Python GameState wrapper class
140
+ │ ├── py.typed # PEP 561 marker
141
+ │ ├── cpp/ # C++ Core Implementation ([src/trianglengin/cpp/README.md])
142
+ │ │ ├── CMakeLists.txt
143
+ │ │ ├── bindings.cpp
144
+ │ │ ├── config.h
145
+ │ │ ├── structs.h
146
+ │ │ ├── grid_data.h / .cpp
147
+ │ │ ├── grid_logic.h / .cpp
148
+ │ │ ├── shape_logic.h / .cpp
149
+ │ │ └── game_state.h / .cpp
150
+ │ ├── core/ # Core Python components (now minimal/empty)
151
+ │ │ └── __init__.py
152
+ │ ├── utils/ # General Python utilities ([src/trianglengin/utils/README.md])
153
+ │ │ └── ... (geometry.py, types.py)
154
+ │ ├── config/ # Core configuration models ([src/trianglengin/config/README.md])
155
+ │ │ ├── __init__.py
156
+ │ │ └── env_config.py # EnvConfig (Pydantic)
157
+ │ └── ui/ # UI Components ([src/trianglengin/ui/README.md])
158
+ │ ├── __init__.py # Exposes UI API (Application, cli_app, DisplayConfig)
159
+ │ ├── app.py # Interactive mode application runner
160
+ │ ├── cli.py # CLI definition (play/debug)
161
+ │ ├── config.py # DisplayConfig (Pydantic)
162
+ │ ├── interaction/ # User input handling ([src/trianglengin/ui/interaction/README.md])
163
+ │ │ ├── __init__.py
164
+ │ │ ├── event_processor.py
165
+ │ │ ├── input_handler.py
166
+ │ │ ├── play_mode_handler.py
167
+ │ │ └── debug_mode_handler.py
168
+ │ └── visualization/ # Pygame rendering ([src/trianglengin/ui/visualization/README.md])
169
+ │ ├── __init__.py
170
+ │ ├── core/ # Core vis components ([src/trianglengin/ui/visualization/core/README.md])
171
+ │ │ ├── __init__.py
172
+ │ │ ├── colors.py
173
+ │ │ ├── coord_mapper.py
174
+ │ │ ├── fonts.py
175
+ │ │ ├── layout.py # NEW
176
+ │ │ └── visualizer.py
177
+ │ └── drawing/ # Drawing functions ([src/trianglengin/ui/visualization/drawing/README.md])
178
+ │ ├── __init__.py
179
+ │ ├── grid.py
180
+ │ ├── highlight.py
181
+ │ ├── hud.py
182
+ │ ├── previews.py
183
+ │ ├── shapes.py
184
+ │ └── utils.py
185
+ ├── tests/ # Unit/Integration tests (Python) ([tests/README.md])
186
+ │ ├── __init__.py
187
+ │ ├── conftest.py
188
+ │ └── core/environment/
189
+ │ └── test_game_state.py # Tests the Python GameState wrapper
190
+ ├── .gitignore
191
+ ├── pyproject.toml # Build config, dependencies
192
+ ├── setup.py # C++ Extension build script
193
+ ├── README.md # This file
194
+ ├── LICENSE
195
+ └── MANIFEST.in
196
+ ```
197
+
198
+ ## Core Components (v2)
199
+
200
+ - **`trianglengin.cpp` (C++ Core)**: Implements the high-performance game logic (state, grid, shapes, rules). Not directly imported in Python.
201
+ - **`trianglengin.game_interface.GameState` (Python Wrapper)**: The primary Python class for interacting with the game engine. It holds a reference to the C++ game state object and provides methods like `step`, `reset`, `is_over`, `valid_actions`, `get_shapes`, `get_grid_data_np`.
202
+ - **`trianglengin.config.EnvConfig`**: Python Pydantic model for core environment configuration. Passed to C++ core during initialization.
203
+ - **`trianglengin.utils`**: General Python utility functions and types. ([`src/trianglengin/utils/README.md`](src/trianglengin/utils/README.md))
204
+
205
+ ## UI Components (`trianglengin.ui`)
206
+
207
+ - **`trianglengin.ui.config.DisplayConfig`**: Pydantic model for UI display settings.
208
+ - **`trianglengin.ui.visualization`**: Python/Pygame rendering components. Uses data obtained from the `GameState` wrapper. ([`src/trianglengin/ui/visualization/README.md`](src/trianglengin/ui/visualization/README.md))
209
+ - **`trianglengin.ui.interaction`**: Python/Pygame input handling for interactive modes. Interacts with the `GameState` wrapper. ([`src/trianglengin/ui/interaction/README.md`](src/trianglengin/ui/interaction/README.md))
210
+ - **`trianglengin.ui.app.Application`**: Integrates UI components for interactive modes.
211
+ - **`trianglengin.ui.cli`**: Command-line interface (`trianglengin play`/`debug`).
212
+
213
+ ## Contributing
214
+
215
+ Contributions are welcome! Please open an issue or submit a pull request on the [GitHub repository](https://github.com/lguibr/trianglengin). Ensure that changes maintain code quality (pass tests, linting, type checking) and keep READMEs updated. Building requires a C++17 compiler and CMake.
@@ -0,0 +1,132 @@
1
+ # File: pyproject.toml
2
+ [build-system]
3
+ requires = [
4
+ "setuptools>=61.0", # Keep >=61 for find_packages support if needed, >=77 for new license format preferred
5
+ "wheel",
6
+ "pybind11>=2.10",
7
+ "cmake>=3.14",
8
+ ]
9
+ build-backend = "setuptools.build_meta"
10
+
11
+ [project]
12
+ name = "trianglengin"
13
+ version = "2.0.1" # Major version bump for C++ refactor
14
+ authors = [{ name="Luis Guilherme P. M.", email="lgpelin92@gmail.com" }]
15
+ description = "High-performance C++/Python engine for a triangle puzzle game." # Updated description
16
+ readme = "README.md"
17
+ # Use SPDX identifier string and specify license file(s)
18
+ license = "MIT"
19
+ license-files = ["LICENSE"]
20
+ requires-python = ">=3.10"
21
+ classifiers = [
22
+ "Programming Language :: Python :: 3",
23
+ "Programming Language :: Python :: 3.10",
24
+ "Programming Language :: Python :: 3.11",
25
+ "Programming Language :: C++", # Added C++ classifier
26
+ # REMOVED: "License :: OSI Approved :: MIT License", # Deprecated classifier
27
+ "Operating System :: OS Independent",
28
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
29
+ "Topic :: Games/Entertainment :: Puzzle Games",
30
+ "Development Status :: 4 - Beta",
31
+ ]
32
+ dependencies = [
33
+ # Core dependencies + UI dependencies are now required
34
+ "numpy>=1.20.0",
35
+ "pydantic>=2.0.0",
36
+ "typing_extensions>=4.0.0",
37
+ "pygame>=2.1.0",
38
+ "typer[all]>=0.9.0",
39
+ ]
40
+
41
+ [project.urls]
42
+ "Homepage" = "https://github.com/lguibr/trianglengin"
43
+ "Bug Tracker" = "https://github.com/lguibr/trianglengin/issues"
44
+
45
+ [project.scripts]
46
+ # Script now points to the CLI inside the 'ui' subpackage
47
+ trianglengin = "trianglengin.ui.cli:app"
48
+
49
+ [project.optional-dependencies]
50
+ # UI section removed
51
+ dev = [
52
+ "pytest>=7.0.0",
53
+ "pytest-cov>=3.0.0",
54
+ "pytest-mock>=3.0.0",
55
+ "ruff",
56
+ "mypy",
57
+ "build",
58
+ "twine",
59
+ "codecov",
60
+ # No need to list pygame/typer here anymore
61
+ ]
62
+
63
+ [tool.setuptools]
64
+ # package_dir is removed from here - handled by setup.py
65
+ # include-package-data = true # Optional: Keep if you rely on MANIFEST.in for data files
66
+
67
+ [tool.setuptools.package-data]
68
+ # Include C++ headers if needed, py.typed, etc.
69
+ "trianglengin" = ["py.typed", "cpp/*.h"]
70
+
71
+ # --- Tool Configurations ---
72
+
73
+ [tool.ruff]
74
+ line-length = 88
75
+ src = ["src", "tests"] # Specify source directories
76
+
77
+ [tool.ruff.lint]
78
+ select = ["E", "W", "F", "I", "UP", "B", "C4", "ARG", "SIM", "TCH", "PTH", "NPY", "PYI"] # Added PYI for stubs
79
+ ignore = ["E501"]
80
+
81
+ [tool.ruff.format]
82
+ quote-style = "double"
83
+
84
+ [tool.mypy]
85
+ python_version = "3.10"
86
+ warn_return_any = true
87
+ warn_unused_configs = true
88
+ ignore_missing_imports = false # Be stricter
89
+ disallow_untyped_defs = true
90
+ # Specify source directory for mypy
91
+ files = ["src/trianglengin", "tests"]
92
+
93
+ [[tool.mypy.overrides]]
94
+ # Ignore the compiled C++ extension module
95
+ module = "trianglengin.trianglengin_cpp"
96
+ ignore_missing_imports = true
97
+
98
+ # No longer need overrides for pygame/typer as they are required
99
+
100
+
101
+ [tool.pytest.ini_options]
102
+ minversion = "7.0"
103
+ # Update coverage path
104
+ addopts = "-ra -q --cov=src/trianglengin --cov-report=term-missing"
105
+ testpaths = [
106
+ "tests",
107
+ ]
108
+
109
+ [tool.coverage.run]
110
+ source = ["src/trianglengin"] # Specify source for coverage
111
+ omit = [
112
+ "src/trianglengin/__init__.py",
113
+ "src/trianglengin/cpp/*", # Exclude C++ source from Python coverage
114
+ "src/trianglengin/config/env_config.py", # Keep config covered (only env_config)
115
+ "src/trianglengin/utils/types.py",
116
+ # Omit the entire UI package
117
+ "src/trianglengin/ui/*",
118
+ # Omit the now empty core package
119
+ "src/trianglengin/core/*",
120
+ "tests/*",
121
+ "setup.py",
122
+ ]
123
+
124
+ [tool.coverage.report]
125
+ fail_under = 70 # Increased target coverage for core logic
126
+ show_missing = true
127
+
128
+ # Optional: Add cibuildwheel configuration if needed
129
+ # [tool.cibuildwheel]
130
+ # skip = "pp*" # Example: Skip PyPy builds
131
+ # test-requires = "pytest" # Dependencies needed for tests run by cibuildwheel
132
+ # test-command = "pytest {project}/tests" # Command to run tests after building wheel