Telegram RPG — обзор проекта
🎮 Поиграть можно прямо сейчас: @dementev_RPG_Telebot
Живой документ. Обновляется по мере развития проекта — здесь всегда должна быть актуальная общая картина и ссылки на детальные документы. Если решение поменялось в одном из документов ниже — стоит свериться, не устарела ли соответствующая строка здесь.
1. Идея игры
Простая текстовая RPG в формате Telegram-бота. Герой перемещается по локациям, ищет противников, сражается по пошаговой боевой системе на основе кубика, получает награду за победу и прокачивает характеристики. Чистый PvE на одной локации с тремя рядовыми противниками и финальным боссом. PvP решено не делать — игра остаётся однопользовательской.
Ключевая метафора, которой подчинена вся боевая механика: бой должен ощущаться как игра по переписке — каждое действие игрока буквально бросает кубик и сразу видит результат, а не читает готовый отчёт о случившемся.
2. Запуск
Нужны два процесса одновременно: HTTP-бэкенд (api/) и Telegram-бот (bot/). Бэкенд можно запускать и тестировать отдельно, бот без запущенного бэкенда работать не будет.
1. Зависимости
Требуется Python 3.14 (та же версия, что и в Dockerfile — не зафиксирована через pyproject.toml/runtime.txt, только здесь и в самом образе).
pip install -r requirements.txt
Для тестов и разработки дополнительно:
pip install -r requirements-dev.txt
2. Настройка .env
Скопировать .env.example в .env и заполнить:
TELEGRAM_BOT_TOKEN=<токен от @BotFather>
API_BASE_URL=http://127.0.0.1:8000
INTERNAL_API_KEY=dev-local-key
DATABASE_URL=postgresql+psycopg2://rpg:rpg@localhost:5432/rpg
DATABASE_URL/INTERNAL_API_KEY/TELEGRAM_BOT_TOKEN обязательны (docs/hardening_plan.md, этап 2) — без любой из них api/бот сразу падают понятной ошибкой при старте (db/settings.py/api/settings.py/bot/settings.py), а не тихо работают с дефолтом или не той БД. Для PostgreSQL нужен запущенный сервер — быстрее всего поднять один контейнер (без docker-compose, это отдельный шаг для развёртывания на сервере):
docker run -d --name rpg-postgres -e POSTGRES_USER=rpg -e POSTGRES_PASSWORD=rpg -e POSTGRES_DB=rpg -p 5432:5432 -v rpg_pgdata:/var/lib/postgresql/data postgres:16
3. Применить миграции БД
alembic upgrade head
Создаёт (или доращивает) схему в БД, на которую указывает DATABASE_URL (SQLite или PostgreSQL — миграции одинаковы для обеих, docs/backend_plan.md §10). Нужно один раз при первом запуске и заново после каждой новой миграции — само приложение схему БД больше не создаёт и не трогает.
4. Запустить бэкенд
uvicorn api.main:app --reload
Swagger-документация эндпоинтов — на http://127.0.0.1:8000/docs.
5. Запустить бота (в отдельном терминале, при запущенном бэкенде)
python -m bot.main
6. Тесты
python -m pytest tests/
7. Проверки стиля и типов (docs/hardening_plan.md, этап 1 — то же, что гоняет .github/workflows/ci.yml на каждый PR)
ruff check .
ruff format --check .
mypy core api db
mypy пока проверяет только core//api//db/ — bot/ и scripts/ сознательно не включены (aiogram типизирует многие поля как Optional, это отдельная, более объёмная задача).
CI дополнительно гоняет тесты api/ против настоящего PostgreSQL (отдельная параллельная задача, схема — через alembic upgrade head, не create_all) — так проверяется и сама цепочка миграций. Локально это не обязательно; если нужно — отдельный контейнер, не тот, что для ручной разработки (шаг 2 выше): тесты делают TRUNCATE между прогонами, на реальных данных персонажа это будет потеря прогресса.
docker run -d --name rpg-test-postgres -e POSTGRES_USER=rpg -e POSTGRES_PASSWORD=rpg -e POSTGRES_DB=rpg_test -p 55432:5432 postgres:16
DATABASE_URL=postgresql+psycopg2://rpg:rpg@localhost:55432/rpg_test alembic upgrade head
POSTGRES_TEST_URL=postgresql+psycopg2://rpg:rpg@localhost:55432/rpg_test pytest tests/api
Через Docker (альтернатива шагам 1-5 выше — для переноса на сервер)
Всё (api, бот, PostgreSQL) — одним docker-compose.yml (docs/notes.md, п.63). Шаг 2 (.env) всё равно нужен — TELEGRAM_BOT_TOKEN/INTERNAL_API_KEY/POSTGRES_USER/POSTGRES_PASSWORD/POSTGRES_DB берутся оттуда; API_BASE_URL/DATABASE_URL для контейнеров заданы прямо в docker-compose.yml (имена сервисов сети compose, не localhost).
На чистом хосте (первый раз, без предыдущего шага 2 выше) нужен ещё именованный volume — docker-compose.yml подключает rpg_pgdata как external: true (переиспользует тот же volume, что и ручной docker run из шага 2, если он уже был), поэтому compose его не создаёт сам и упадёт с ошибкой, если volume не существует:
docker volume create rpg_pgdata
Дальше — обычный запуск:
docker compose up -d --build
Поднимает Postgres, применяет alembic upgrade head при каждом старте api-контейнера (идемпотентно) и запускает бэкенд + бота. Бэкенд публикуется на http://127.0.0.1:8000 (как и при ручном запуске), у бота портов нет — он только исходящий (long-polling).
docker compose ps # статус/health всех трёх сервисов
docker compose logs -f # логи всех сервисов
docker compose up -d --build # пересобрать образ и перезапустить после изменений в коде
docker compose down # остановить (том rpg_pgdata с данными не удаляется)
Тесты через Docker не гоняются — pytest по-прежнему только на хосте (шаг 6 выше), контейнеры этого не касаются.
Логи бота на диске (docs/notes.md) — bot/ пишет logs/bot.log (плюс ротация logs/bot.log.1/.2/.3) в дополнение к обычному выводу в stdout (docker compose logs bot), через bind mount ./logs:/app/logs в docker-compose.yml — переживает docker compose up -d --build, в отличие от вывода контейнера. Директория logs/ создаётся автоматически при первом запуске, в .gitignore/.dockerignore.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
