tttarena 0.1.1

Deterministic, turn-based Tetris engine with 'Nightmare' mechanics (target curve, petrification, entropy budget)

🏆 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:

   pip install tttarena
   

2. Запустите симуляцию с базовым ботом:

   python main.py --seed 42
   python main.py --seed 42 --render [cli/pygame]
   

3. Изучите результат: Лог игры будет в run_logs/. Верифицируйте его:

   python tttarena/verify.py run_logs/my_best_run.json
   

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

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

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

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

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

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

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

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

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.