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.
- trianglengin-2.0.1/MANIFEST.in +26 -0
- trianglengin-2.0.1/PKG-INFO +250 -0
- trianglengin-2.0.1/README.md +215 -0
- trianglengin-2.0.1/pyproject.toml +132 -0
- trianglengin-2.0.1/setup.py +172 -0
- trianglengin-2.0.1/src/trianglengin/__init__.py +35 -0
- trianglengin-2.0.1/src/trianglengin/config/README.md +38 -0
- trianglengin-2.0.1/src/trianglengin/config/__init__.py +8 -0
- trianglengin-2.0.1/src/trianglengin/config/env_config.py +62 -0
- trianglengin-2.0.1/src/trianglengin/core/__init__.py +10 -0
- trianglengin-2.0.1/src/trianglengin/cpp/CMakeLists.txt +42 -0
- trianglengin-2.0.1/src/trianglengin/cpp/bindings.cpp +211 -0
- trianglengin-2.0.1/src/trianglengin/cpp/config.h +28 -0
- trianglengin-2.0.1/src/trianglengin/cpp/game_state.cpp +327 -0
- trianglengin-2.0.1/src/trianglengin/cpp/game_state.h +73 -0
- trianglengin-2.0.1/src/trianglengin/cpp/grid_data.cpp +239 -0
- trianglengin-2.0.1/src/trianglengin/cpp/grid_data.h +78 -0
- trianglengin-2.0.1/src/trianglengin/cpp/grid_logic.cpp +125 -0
- trianglengin-2.0.1/src/trianglengin/cpp/grid_logic.h +30 -0
- trianglengin-2.0.1/src/trianglengin/cpp/shape_logic.cpp +100 -0
- trianglengin-2.0.1/src/trianglengin/cpp/shape_logic.h +28 -0
- trianglengin-2.0.1/src/trianglengin/cpp/structs.h +40 -0
- trianglengin-2.0.1/src/trianglengin/game_interface.py +222 -0
- trianglengin-2.0.1/src/trianglengin/ui/README.md +35 -0
- trianglengin-2.0.1/src/trianglengin/ui/__init__.py +21 -0
- {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/app.py +19 -22
- {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/cli.py +29 -40
- trianglengin-1.0.6/trianglengin/config/display_config.py → trianglengin-2.0.1/src/trianglengin/ui/config.py +6 -9
- {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/interaction/README.md +15 -16
- {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/interaction/__init__.py +2 -0
- trianglengin-2.0.1/src/trianglengin/ui/interaction/debug_mode_handler.py +72 -0
- {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/interaction/event_processor.py +8 -2
- {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/interaction/input_handler.py +20 -13
- trianglengin-2.0.1/src/trianglengin/ui/interaction/play_mode_handler.py +156 -0
- {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/README.md +11 -13
- {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/__init__.py +20 -23
- {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/core/README.md +15 -16
- trianglengin-2.0.1/src/trianglengin/ui/visualization/core/__init__.py +16 -0
- {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/core/colors.py +13 -15
- {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/core/coord_mapper.py +22 -10
- {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/core/fonts.py +11 -1
- trianglengin-2.0.1/src/trianglengin/ui/visualization/core/layout.py +77 -0
- {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/core/visualizer.py +55 -39
- {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/drawing/README.md +9 -5
- trianglengin-2.0.1/src/trianglengin/ui/visualization/drawing/__init__.py +43 -0
- trianglengin-2.0.1/src/trianglengin/ui/visualization/drawing/grid.py +213 -0
- {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/drawing/highlight.py +12 -11
- {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/drawing/hud.py +8 -4
- {trianglengin-1.0.6/trianglengin → trianglengin-2.0.1/src/trianglengin/ui}/visualization/drawing/previews.py +44 -35
- trianglengin-2.0.1/src/trianglengin/ui/visualization/drawing/shapes.py +46 -0
- trianglengin-2.0.1/src/trianglengin/ui/visualization/drawing/utils.py +23 -0
- {trianglengin-1.0.6 → trianglengin-2.0.1/src}/trianglengin/utils/geometry.py +13 -24
- trianglengin-2.0.1/src/trianglengin.egg-info/PKG-INFO +250 -0
- trianglengin-2.0.1/src/trianglengin.egg-info/SOURCES.txt +70 -0
- trianglengin-2.0.1/src/trianglengin.egg-info/entry_points.txt +2 -0
- trianglengin-2.0.1/src/trianglengin.egg-info/not-zip-safe +1 -0
- {trianglengin-1.0.6 → trianglengin-2.0.1/src}/trianglengin.egg-info/top_level.txt +0 -2
- trianglengin-2.0.1/tests/conftest.py +113 -0
- trianglengin-2.0.1/tests/core/environment/README.md +38 -0
- trianglengin-2.0.1/tests/core/environment/test_game_state.py +482 -0
- {trianglengin-1.0.6 → trianglengin-2.0.1}/tests/utils/test_geometry.py +25 -54
- trianglengin-1.0.6/MANIFEST.in +0 -7
- trianglengin-1.0.6/PKG-INFO +0 -367
- trianglengin-1.0.6/README.md +0 -311
- trianglengin-1.0.6/pyproject.toml +0 -100
- trianglengin-1.0.6/tests/conftest.py +0 -108
- trianglengin-1.0.6/tests/core/environment/README.md +0 -47
- trianglengin-1.0.6/tests/core/environment/test_action_codec.py +0 -50
- trianglengin-1.0.6/tests/core/environment/test_game_state.py +0 -483
- trianglengin-1.0.6/tests/core/environment/test_grid_data.py +0 -205
- trianglengin-1.0.6/tests/core/environment/test_grid_logic.py +0 -362
- trianglengin-1.0.6/tests/core/environment/test_shape_logic.py +0 -171
- trianglengin-1.0.6/tests/core/environment/test_step.py +0 -372
- trianglengin-1.0.6/tests/core/structs/test_shape.py +0 -83
- trianglengin-1.0.6/tests/core/structs/test_triangle.py +0 -97
- trianglengin-1.0.6/trianglengin/__init__.py +0 -18
- trianglengin-1.0.6/trianglengin/config/__init__.py +0 -9
- trianglengin-1.0.6/trianglengin/config/env_config.py +0 -103
- trianglengin-1.0.6/trianglengin/core/__init__.py +0 -8
- trianglengin-1.0.6/trianglengin/core/environment/__init__.py +0 -31
- trianglengin-1.0.6/trianglengin/core/environment/action_codec.py +0 -37
- trianglengin-1.0.6/trianglengin/core/environment/game_state.py +0 -217
- trianglengin-1.0.6/trianglengin/core/environment/grid/README.md +0 -46
- trianglengin-1.0.6/trianglengin/core/environment/grid/__init__.py +0 -18
- trianglengin-1.0.6/trianglengin/core/environment/grid/grid_data.py +0 -140
- trianglengin-1.0.6/trianglengin/core/environment/grid/line_cache.py +0 -189
- trianglengin-1.0.6/trianglengin/core/environment/grid/logic.py +0 -131
- trianglengin-1.0.6/trianglengin/core/environment/logic/__init__.py +0 -3
- trianglengin-1.0.6/trianglengin/core/environment/logic/actions.py +0 -38
- trianglengin-1.0.6/trianglengin/core/environment/logic/step.py +0 -134
- trianglengin-1.0.6/trianglengin/core/environment/shapes/__init__.py +0 -19
- trianglengin-1.0.6/trianglengin/core/environment/shapes/logic.py +0 -84
- trianglengin-1.0.6/trianglengin/core/environment/shapes/templates.py +0 -587
- trianglengin-1.0.6/trianglengin/core/structs/__init__.py +0 -27
- trianglengin-1.0.6/trianglengin/core/structs/constants.py +0 -28
- trianglengin-1.0.6/trianglengin/core/structs/shape.py +0 -61
- trianglengin-1.0.6/trianglengin/core/structs/triangle.py +0 -48
- trianglengin-1.0.6/trianglengin/interaction/debug_mode_handler.py +0 -96
- trianglengin-1.0.6/trianglengin/interaction/play_mode_handler.py +0 -141
- trianglengin-1.0.6/trianglengin/visualization/core/__init__.py +0 -12
- trianglengin-1.0.6/trianglengin/visualization/core/layout.py +0 -101
- trianglengin-1.0.6/trianglengin/visualization/drawing/__init__.py +0 -30
- trianglengin-1.0.6/trianglengin/visualization/drawing/grid.py +0 -156
- trianglengin-1.0.6/trianglengin/visualization/drawing/shapes.py +0 -36
- trianglengin-1.0.6/trianglengin.egg-info/PKG-INFO +0 -367
- trianglengin-1.0.6/trianglengin.egg-info/SOURCES.txt +0 -76
- trianglengin-1.0.6/trianglengin.egg-info/entry_points.txt +0 -2
- {trianglengin-1.0.6 → trianglengin-2.0.1}/LICENSE +0 -0
- {trianglengin-1.0.6 → trianglengin-2.0.1}/setup.cfg +0 -0
- /trianglengin-1.0.6/tests/__init__.py → /trianglengin-2.0.1/src/trianglengin/py.typed +0 -0
- {trianglengin-1.0.6 → trianglengin-2.0.1/src}/trianglengin/utils/__init__.py +0 -0
- {trianglengin-1.0.6 → trianglengin-2.0.1/src}/trianglengin/utils/types.py +0 -0
- {trianglengin-1.0.6 → trianglengin-2.0.1/src}/trianglengin.egg-info/dependency_links.txt +0 -0
- {trianglengin-1.0.6 → trianglengin-2.0.1/src}/trianglengin.egg-info/requires.txt +0 -0
- {trianglengin-1.0.6/tests/core/structs → trianglengin-2.0.1/tests}/__init__.py +0 -0
- {trianglengin-1.0.6 → trianglengin-2.0.1}/tests/core/__init__.py +0 -0
- {trianglengin-1.0.6 → trianglengin-2.0.1}/tests/core/environment/__init__.py +0 -0
- {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
|
+
[](https://github.com/lguibr/trianglengin/actions/workflows/ci_cd.yml)
|
38
|
+
[](https://codecov.io/gh/lguibr/trianglengin)
|
39
|
+
[](https://badge.fury.io/py/trianglengin)
|
40
|
+
[](https://opensource.org/licenses/MIT)
|
41
|
+
[](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
|
+
[](https://github.com/lguibr/trianglengin/actions/workflows/ci_cd.yml)
|
3
|
+
[](https://codecov.io/gh/lguibr/trianglengin)
|
4
|
+
[](https://badge.fury.io/py/trianglengin)
|
5
|
+
[](https://opensource.org/licenses/MIT)
|
6
|
+
[](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
|