
[![CI Status](https://github.com/lguibr/trianglengin/actions/workflows/ci_cd.yml/badge.svg)](https://github.com/lguibr/trianglengin/actions/workflows/ci_cd.yml) <!-- Update workflow name if changed -->
[![codecov](https://codecov.io/gh/lguibr/trianglengin/graph/badge.svg?token=YOUR_CODECOV_TOKEN_HERE&flag=trianglengin)](https://codecov.io/gh/lguibr/trianglengin) <!-- Update repo name -->
[![PyPI version](https://badge.fury.io/py/trianglengin.svg)](https://badge.fury.io/py/trianglengin)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

# Triangle Engine (`trianglengin`)
<img src="bitmap.png" alt="trianglengin logo" width="300"/>

This library provides the core, reusable components for reinforcement learning agents playing a triangle puzzle game.

It encapsulates:

1.  **Core Game Logic:** Environment rules, state representation, actions.
2.  **Basic Visualization:** Pygame rendering for interactive play/debug modes.
3.  **Interaction Handling:** Input processing for interactive modes.
4.  **Utilities:** General helpers, geometry functions, shared types.
5.  **Configuration:** Pydantic models for environment and display settings.
6.  **(Planned) Feature Extraction:** Logic to convert game state to NN input format.
7.  **(Planned) Data Management Framework:** Structure for saving/loading checkpoints and buffers.
8.  **(Planned) Statistics Collection:** Components for tracking game/training stats.

---

## 🎮 The Ultimate Triangle Puzzle Guide 🧩

Get ready to become a Triangle Master! This guide explains everything you need to know to play the game, step-by-step, with lots of details!

### 1. Introduction: Your Mission! 🎯

Your goal is to place colorful shapes onto a special triangular grid. By filling up lines of triangles, you make them disappear and score points! Keep placing shapes and clearing lines for as long as possible to get the highest score before the grid fills up and you run out of moves. Sounds simple? Let's dive into the details!

### 2. The Playing Field: The Grid 🗺️

- **Triangle Cells:** The game board is a grid made of many small triangles. Some point UP (🔺) and some point DOWN (🔻). They alternate like a checkerboard pattern based on their row and column index (specifically, `(row + col) % 2 != 0` means UP).
- **Shape:** The grid itself is rectangular overall, but the playable area within it is typically shaped like a triangle or hexagon, wider in the middle and narrower at the top and bottom.
- **Playable Area:** You can only place shapes within the designated playable area.
- **Death Zones 💀:** Around the edges of the playable area (often at the start and end of rows), some triangles are marked as "Death Zones". You **cannot** place any part of a shape onto these triangles. They are off-limits! Think of them as the boundaries within the rectangular grid.

### 3. Your Tools: The Shapes 🟦🟥🟩

- **Shape Formation:** Each shape is a collection of connected small triangles (🔺 and 🔻). They come in different colors and arrangements. Some might be a single triangle, others might be long lines, L-shapes, or more complex patterns.
- **Relative Positions:** The triangles within a shape have fixed positions _relative to each other_. When you move the shape, all its triangles move together as one block.
- **Preview Area:** You will always have **three** shapes available to choose from at any time. These are shown in a special "preview area" on the side of the screen.

### 4. Making Your Move: Placing Shapes 🖱️➡️▦

This is the core action! Here's exactly how to place a shape:

- **Step 4a: Select a Shape:** Look at the three shapes in the preview area. Click on the one you want to place. It should highlight 💡 to show it's selected.
- **Step 4b: Aim on the Grid:** Move your mouse cursor over the main grid. You'll see a faint "ghost" image of your selected shape following your mouse. This preview helps you aim.
- **Step 4c: The Placement Rules (MUST Follow!)**
  - 📏 **Rule 1: Fit Inside Playable Area:** ALL triangles of your chosen shape must land within the playable grid area. No part of the shape can land in a Death Zone 💀.
  - 🧱 **Rule 2: No Overlap:** ALL triangles of your chosen shape must land on currently _empty_ spaces on the grid. You cannot place a shape on top of triangles that are already filled with color from previous shapes.
  - 📐 **Rule 3: Orientation Match!** This is crucial!
    - If a part of your shape is an UP triangle (🔺), it MUST land on an UP space (🔺) on the grid.
    - If a part of your shape is a DOWN triangle (🔻), it MUST land on a DOWN space (🔻) on the grid.
    - 🔺➡️🔺 (OK!)
    - 🔻➡️🔻 (OK!)
    - 🔺➡️🔻 (INVALID! ❌)
    - 🔻➡️🔺 (INVALID! ❌)
  - **Visual Feedback:** The game helps you!
    - 👍 **Valid Spot:** If the position under your mouse follows ALL three rules, the ghost preview will usually look solid and possibly greenish. This means you _can_ place the shape here.
    - 👎 **Invalid Spot:** If the position breaks _any_ of the rules (out of bounds, overlaps, wrong orientation), the ghost preview will usually look faded and possibly reddish. This means you _cannot_ place the shape here.
- **Step 4d: Confirm Placement:** Once you find a **valid** spot (👍), click the left mouse button again. _Click!_ The shape is now placed permanently on the grid! ✨

### 5. Scoring Points: How You Win! 🏆

You score points in two main ways:

- **Placing Triangles:** You get a small number of points for _every single small triangle_ that makes up the shape you just placed. (e.g., placing a 3-triangle shape might give you 3 \* tiny_score points).
- **Clearing Lines:** This is where the BIG points come from! You get a much larger number of points for _every single small triangle_ that disappears when you clear a line (or multiple lines at once!). See the next section for details!

### 6. Line Clearing Magic! ✨ (The Key to High Scores!)

This is the most exciting part! When you place a shape, the game immediately checks if you've completed any lines. This section explains how the game _finds_ and _clears_ these lines.

- **What Lines Can Be Cleared?** There are **three** types of lines the game looks for:

  - **Horizontal Lines ↔️:** A straight, unbroken line of filled triangles going across a single row.
  - **Diagonal Lines (Top-Left to Bottom-Right) ↘️:** An unbroken diagonal line of filled triangles stepping down and to the right.
  - **Diagonal Lines (Bottom-Left to Top-Right) ↗️:** An unbroken diagonal line of filled triangles stepping up and to the right.

- **How Lines are Found: Pre-calculation of Maximal Lines**

  - **The Idea:** Instead of checking every possible line combination all the time, the game pre-calculates all *maximal* continuous lines of playable triangles when it starts. A **maximal line** is the longest possible straight segment of *playable* triangles (not in a Death Zone) in one of the three directions (Horizontal, Diagonal ↘️, Diagonal ↗️).
  - **Tracing:** For every playable triangle on the grid, the game traces outwards in each of the three directions to find the full extent of the continuous playable line passing through that triangle in that direction.
  - **Storing Maximal Lines:** Only the complete maximal lines found are stored. For example, if tracing finds a playable sequence `A-B-C-D`, only the line `(A,B,C,D)` is stored, not the sub-segments like `(A,B,C)` or `(B,C,D)`. These maximal lines represent the *potential* lines that can be cleared.
  - **Coordinate Map:** The game also builds a map linking each playable triangle coordinate `(r, c)` to the set of maximal lines it belongs to. This allows for quick lookup.

- **Defining the Paths (Neighbor Logic):** How does the game know which triangle is "next" when tracing? It depends on the current triangle's orientation (🔺 or 🔻) and the direction being traced:

  - **Horizontal ↔️:**
    - Left Neighbor: `(r, c-1)` (Always in the same row)
    - Right Neighbor: `(r, c+1)` (Always in the same row)
  - **Diagonal ↘️ (TL-BR):**
    - If current is 🔺 (Up): Next is `(r+1, c)` (Down triangle directly below)
    - If current is 🔻 (Down): Next is `(r, c+1)` (Up triangle to the right)
  - **Diagonal ↗️ (BL-TR):**
    - If current is 🔻 (Down): Next is `(r-1, c)` (Up triangle directly above)
    - If current is 🔺 (Up): Next is `(r, c+1)` (Down triangle to the right)

- **Visualizing the Paths:**

  - **Horizontal ↔️:**
    ```
    ... [🔻][🔺][🔻][🔺][🔻][🔺] ...  (Moves left/right in the same row)
    ```
  - **Diagonal ↘️ (TL-BR):** (Connects via shared horizontal edges)
    ```
    ...[🔺]...
    ...[🔻][🔺] ...
    ...     [🔻][🔺] ...
    ...         [🔻] ...
    (Path alternates row/col increments depending on orientation)
    ```
  - **Diagonal ↗️ (BL-TR):** (Connects via shared horizontal edges)
    ```
    ...           [🔺]  ...
    ...      [🔺][🔻]   ...
    ... [🔺][🔻]        ...
    ... [🔻]            ...
    (Path alternates row/col increments depending on orientation)
    ```

- **The "Full Line" Rule:** After you place a piece, the game looks at the coordinates `(r, c)` of the triangles you just placed. Using the pre-calculated map, it finds all the *maximal* lines that contain _any_ of those coordinates. For each of those maximal lines (that have at least 2 triangles), it checks: "Is _every single triangle coordinate_ in this maximal line now occupied?" If yes, that line is complete! (Note: Single isolated triangles don't count as clearable lines).

- **The _Poof_! 💨:**
  - If placing your shape completes one or MORE maximal lines (of any type, length >= 2) simultaneously, all the triangles in ALL completed lines vanish instantly!
  - The spaces become empty again.
  - You score points for _every single triangle_ that vanished. Clearing multiple lines at once is the best way to rack up points! 🥳

### 7. Getting New Shapes: The Refill 🪄

- **The Trigger:** The game only gives you new shapes when a specific condition is met.
- **The Condition:** New shapes appear **only when all three of your preview slots become empty at the exact same time.**
- **How it Happens:** This usually occurs right after you place your _last_ available shape (the third one).
- **The Refill:** As soon as the third slot becomes empty, _BAM!_ 🪄 Three brand new, randomly generated shapes instantly appear in the preview slots.
- **Important:** If you place a shape and only one or two slots are empty, you **do not** get new shapes yet. You must use up all three before the refill happens.

### 8. The End of the Road: Game Over 😭

So, how does the game end?

- **The Condition:** The game is over when you **cannot legally place _any_ of the three shapes currently available in your preview slots anywhere on the grid.**
- **The Check:** After every move (placing a shape and any resulting line clears), and after any potential shape refill, the game checks: "Is there at least one valid spot on the grid for Shape 1? OR for Shape 2? OR for Shape 3?"
- **No More Moves:** If the answer is "NO" for all three shapes (meaning none of them can be placed anywhere according to the Placement Rules), then the game immediately ends.
- **Strategy:** This means you need to be careful! Don't fill up the grid in a way that leaves no room for the types of shapes you might get later. Always try to keep options open! 🤔

That's it! Now you know all the rules. Go forth and conquer the Triangle Puzzle! 🏆

---

## Purpose

The primary goal is to provide a self-contained, installable library for the core logic and basic interactive UI of the triangle puzzle game. This allows different RL agent implementations or other applications to build upon a consistent and well-defined game backend, avoiding code duplication.

## Installation

```bash
# For standard use (once published or built):
pip install trianglengin
```

## Running Interactive Modes

After installing (`pip install trianglengin`), you can run the interactive modes directly:

- **Play Mode:**
  ```bash
  trianglengin play [--seed 42] [--log-level INFO]
  ```
- **Debug Mode:**
  ```bash
  trianglengin debug [--seed 42] [--log-level DEBUG]
  ```

---

## Local Development & Testing

These instructions are for developers contributing to `trianglengin`.

1.  **Clone the Repository:**
    ```bash
    git clone https://github.com/lguibr/trianglengin.git
    cd trianglengin
    ```

2.  **Create and Activate Virtual Environment:**
    *   **Using `venv` (Recommended):**
        ```bash
        python -m venv venv
        # On Linux/macOS:
        source venv/bin/activate
        # On Windows (Command Prompt):
        # .\venv\Scripts\activate
        # On Windows (PowerShell):
        # .\venv\Scripts\Activate.ps1
        ```
    *   **Using `conda`:**
        ```bash
        conda create -n trianglengin python=3.10
        conda activate trianglengin
        ```
    **IMPORTANT:** Ensure your virtual environment is activated in your terminal *before* proceeding to the next step. You should see `(venv)` or `(trianglengin)` at the beginning of your terminal prompt.

3.  **Install in Editable Mode with Dev Dependencies:**
    *   **Make sure your virtual environment is active!**
    *   Run the following command from the project root directory (where `pyproject.toml` is located):
        ```bash
        # Use quotes to prevent shell expansion issues (especially in Zsh)
        pip install -e '.[dev]'
        ```
        **Note the syntax:** `'.[dev]'` includes the optional development dependencies, and the quotes prevent the shell from misinterpreting the brackets.
        This installs the `trianglengin` package itself in a way that your code changes are immediately reflected, *and* it installs all the tools needed for testing and development (`pytest`, `ruff`, `mypy`, etc.).

4.  **Running Checks:**
    *   **Make sure your virtual environment is active!**
    *   **Tests & Coverage:**
        ```bash
        pytest tests/ --cov=trianglengin --cov-report=xml
        ```
        (This generates `coverage.xml` for upload if using Codecov).
        To just run tests: `pytest`
    *   **Linting:**
        ```bash
        ruff check .
        ```
    *   **Formatting:**
        ```bash
        ruff format .
        ```
    *   **Type Checking:**
        ```bash
        mypy trianglengin/
        ```

5.  **Troubleshooting "command not found" errors:**
    *   If you see errors like `pytest: command not found`, `ruff: command not found`, or `mypy: command not found`, the **most likely cause** is that your virtual environment is **not activated**. Go back to Step 2 and activate it.
    *   If the environment is active, double-check that you ran `pip install -e '.[dev]'` correctly in Step 3 (with the quotes and square brackets).

---

## Project Structure

```
trianglengin/
├── .github/workflows/      # GitHub Actions CI/CD
│   └── ci_cd.yml
├── trianglengin/           # Source code for the library package
│   ├── __init__.py         # Exposes public API
│   ├── app.py              # Interactive mode application runner
│   ├── cli.py              # CLI definition (play/debug)
│   ├── core/               # Core game logic
│   │   ├── __init__.py
│   │   ├── structs/        # Triangle, Shape, constants
│   │   │   └── README.md   # Link: trianglengin/core/structs/README.md
│   │   └── environment/    # GameState, GridData, GridLogic, ShapeLogic, ActionCodec
│   │       └── README.md   # Link: trianglengin/core/environment/README.md
│   ├── interaction/        # User input handling for interactive modes
│   │   └── README.md       # Link: trianglengin/interaction/README.md
│   ├── visualization/      # Basic Pygame rendering components
│   │   ├── __init__.py
│   │   ├── core/           # Visualizer, layout, colors, fonts, coord_mapper
│   │   │   └── README.md   # Link: trianglengin/visualization/core/README.md
│   │   └── drawing/        # Specific drawing functions (grid, shapes, previews, hud)
│   │       └── README.md   # Link: trianglengin/visualization/drawing/README.md
│   ├── features/           # Feature extraction logic (Planned)
│   │   └── README.md       # Link: trianglengin/features/README.md
│   ├── data/               # Data management framework (Planned)
│   │   └── README.md       # Link: trianglengin/data/README.md
│   ├── stats/              # Statistics collection actor (Planned)
│   │   └── README.md       # Link: trianglengin/stats/README.md
│   ├── utils/              # General utilities
│   │   └── README.md       # Link: trianglengin/utils/README.md
│   └── config/             # Shared configuration models
│       ├── __init__.py
│       ├── env_config.py   # Environment configuration (EnvConfig)
│       └── display_config.py # Display configuration (DisplayConfig)
├── tests/                  # Unit tests for trianglengin components
│   ├── __init__.py
│   ├── conftest.py         # Shared test fixtures
│   ├── core/
│   │   ├── __init__.py
│   │   ├── environment/    # Contains test_grid_logic.py now
│   │   └── structs/
│   └── README.md           # Link: tests/README.md
├── .gitignore
├── pyproject.toml          # Build config, dependencies
├── README.md               # This file
├── LICENSE
└── MANIFEST.in
```

## Core Components

- **`trianglengin.core`**: Contains the fundamental game logic.
  - **`structs`**: Defines `Triangle`, `Shape`, and related constants. ([`core/structs/README.md`](trianglengin/core/structs/README.md))
  - **`environment`**: Defines `GameState`, `GridData`, `GridLogic`, `ShapeLogic`, action encoding/decoding, and step execution logic. ([`core/environment/README.md`](trianglengin/core/environment/README.md))
- **`trianglengin.config`**: Contains shared configuration models (`EnvConfig`, `DisplayConfig`).
- **`trianglengin.visualization`**: Basic Pygame rendering (`Visualizer`, drawing functions, colors, fonts, layout). ([`visualization/README.md`](trianglengin/visualization/README.md))
- **`trianglengin.interaction`**: Input handling for interactive modes (`InputHandler`). ([`interaction/README.md`](trianglengin/interaction/README.md))
- **`trianglengin.app`**: Integrates components for interactive modes.
- **`trianglengin.cli`**: Command-line interface for `play`/`debug`.
- **`trianglengin.utils`**: General utility functions and types. ([`utils/README.md`](trianglengin/utils/README.md))

## Contributing

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.
