tttarena 0.1.2
Deterministic, turn-based Tetris engine with 'Nightmare' mechanics (target curve, petrification, entropy budget)
License: MIT
Requires Python: >=3.11

# 🏆 tttarena

[![PyPI version](https://badge.fury.io/py/tttarena.svg)](https://pypi.org/project/tttarena/)
[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/naereni/tttarena/blob/main/baseline.ipynb)
[![Kaggle Competition](https://img.shields.io/badge/Kaggle-Competition-blue?logo=kaggle&logoColor=white)](https://www.kaggle.com/c/tttarena)

Детерминированный, пошаговый движок для симуляции игры в Тетрис с уникальными механиками. Проект предназначен для разработки ИИ-ботов, балансирующих между набором очков и минимизацией отклонения от динамически изменяющейся "целевой кривой".

---

### 🎯 Цель

Разработка алгоритма, который на фиксированной последовательности из **100,000 фигур** достигнет наилучшего **Итогового Результата (Final Score)**. Результат вычисляется как среднее гармоническое двух показателей:
1.  **Классический Счет (`Game Score`):** Очки за очистку линий.
2.  **Точность Аппроксимации (`Approximation Precision`):** Мера соответствия профиля высот поля "целевой кривой".

Итоговая метрика чувствительна к дисбалансу. Оптимальный результат достигается при сбалансированной производительности.

---

### 🚀 Руководство по участию

1.  **Клонирование репозитория:** Получите исходный код движка и примеры ботов.
2.  **Разработка бота:** Создайте класс бота, наследующий от `BaseBot` и реализующий `choose_move()`.
3.  **Локальное тестирование:** Используйте симулятор для запуска игр, анализа логов и визуализации.
4.  **Генерация лога решения:** Запустите симуляцию на актуальном `seed` для создания `my_best_run.json`.
5.  **Отправка решения:** Загрузите `my_best_run.json` в систему соревнований.

---

### 🔧 Ключевые Механики

*   **Детерминизм:** При одинаковом `seed` последовательность фигур идентична, обеспечивая воспроизводимость.
*   **Целевая кривая:** Генерируется фиксированно вначале каждого раунда
*   **Система Оценки:**
    *   **Game Score (S):** Очки за очищенные линии.
    *   **Approximation Error (P):** Ошибка (MSE) между высотами поля и целевой кривой. `P` — сумма всех ошибок за игру.
    *   **Final Score:** `Final Score = 2 / (1/S_norm + 1/P_norm)`. Среднее гармоническое нормализованных показателей.

---

### ✨ Быстрый старт

1.  **Установка с PyPI:**
    ```bash
    pip install tttarena
    ```

4.  **Запустите симуляцию с базовым ботом:**
    ```bash
    python main.py --seed 42
    python main.py --seed 42 --render [cli/pygame]
    ```

5.  **Изучите результат:** Лог игры будет в `run_logs/`. Верифицируйте его:
    ```bash
    python tttarena/verify.py run_logs/my_best_run.json
    ```

7.  **Разработка бота:** Создайте `tttarena/bots/my_bot.py` для собственного алгоритма (смотри бейзлайн на колабе)

### 📊 Визуализация и Кастомизация

Проект предоставляет гибкие возможности визуализации. Выберите встроенный или создайте свой.

Для запуска симуляции с визуализацией используйте флаг `--render`:

```bash
poetry run python main.py --seed 123 --render <имя_визуализатора>
```

**Встроенные визуализаторы:**

*   `cli`: Консольная текстовая визуализация.
*   `pygame`: Графическая визуализация с Pygame.

**Добавление собственных визуализаторов:**

```bash
git clone https://github.com/your-org/tttarena.git 
cd tttarena
poetry install
```

1.  Создайте `your_visualizer_name.py` в `tttarena/simulator/visualizers/`.
2.  Определите класс, наследующий от `BaseVisualizer` и реализующий его абстрактные методы.
3.  Добавьте информацию о вашем визуализаторе в `VISUALIZERS` в `main.py`.