Warhammer 40K Telegram RPG Bot

Data-driven текстовая RPG в Telegram на базе aiogram 3.x. Вся игровая логика и контент описаны в JSON-сценариях.

Особенности

• Data-driven архитектура: движок бота максимально простой, вся логика игры в JSON
• Сеттинг Warhammer 40K: порча, репутация фракций, атмосфера мрачного будущего
• Skill checks: проверки навыков с детерминированным рандомом
• Ветвящийся сюжет: условия, эффекты, множественные концовки
• Тестируемость: JSON-сценарии можно валидировать и тестировать как данные

Быстрый старт

1. Клонирование и настройка

git clone <repo>
cd BotGame

# Создать .env файл
echo "BOT_TOKEN=your_telegram_bot_token" > .env

2. Запуск через Docker

docker-compose up -d

3. Запуск локально (для разработки)

# Создать виртуальное окружение
python -m venv venv
venv\Scripts\activate  # Windows
# или
source venv/bin/activate  # Linux/Mac

# Установить зависимости
pip install -r requirements.txt

# Запустить бота
python -m bot.main

Campaign Editor (Визуальный редактор)

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

Возможности редактора

• Визуальный граф узлов с drag & drop
• Редактирование текста, тегов, эффектов
• Настройка условий и проверок навыков
• Управление предметами и таблицами лута
• Редактирование метаданных кампании
• Автосохранение позиций узлов

Запуск редактора

cd campaign-editor
docker-compose up -d

Редактор будет доступен по адресу: http://localhost:3000

Подробнее: campaign-editor/README.md

Структура проекта

BotGame/
├── bot/                    # Код бота
│   ├── main.py             # Точка входа
│   ├── config.py           # Настройки
│   ├── handlers/           # Aiogram handlers
│   ├── engine/             # Игровой движок
│   ├── models/             # Pydantic модели
│   └── db/                 # Работа с БД
├── campaigns/              # Кампании (JSON)
│   └── hive_tithes/        # Пример кампании
├── campaign-editor/        # Визуальный редактор кампаний
│   ├── src/client/         # React frontend
│   ├── src/server/         # Express API
│   └── docker-compose.yml  # Отдельный запуск
├── schemas/                # JSON Schema для валидации
├── tests/                  # Тесты
├── docs/                   # Документация и изображения
├── Dockerfile
├── docker-compose.yml
└── requirements.txt

Создание кампании

Кампания состоит из нескольких JSON-файлов в папке campaigns/<campaign_id>/:

manifest.json

{
  "campaign": {
    "id": "my_campaign",
    "title": "Название кампании",
    "version": "1.0.0"
  },
  "start_node": "intro"
}

nodes.json

{
  "intro": {
    "text": ["Первый абзац.", "Второй абзац."],
    "options": [
      {
        "label": "Идти вперёд",
        "action": {
          "goto": { "next": "scene_2" }
        }
      },
      {
        "label": "Проверить ловкость",
        "action": {
          "checks": [
            {
              "stat": "agility",
              "dc": 10,
              "on_fail": [{ "type": "modify_resource", "key": "hp", "delta": -2 }]
            }
          ],
          "goto": { "success": "success_scene", "fail": "fail_scene" }
        }
      }
    ]
  }
}

tables.json (опционально)

{
  "loot_table": [
    { "weight": 70, "effects": [{ "type": "message", "text": "Ничего" }] },
    { "weight": 30, "effects": [{ "type": "add_item", "id": "treasure" }] }
  ]
}

Типы условий

Тип	Описание	Параметры
stat_gte	Стат >= значения	stat, value
stat_lte	Стат <= значения	stat, value
resource_gte	Ресурс >= значения	key, value
reputation_gte	Репутация >= значения	faction, value
has_item	Есть предмет	id
has_status	Есть статус	status
flag_is	Флаг равен значению	flag, value

Логические операторы: all, any, not

Типы эффектов

Тип	Описание	Параметры
modify_stat	Изменить стат	stat, delta
modify_resource	Изменить ресурс	key, delta
modify_reputation	Изменить репутацию	faction, delta
add_item	Добавить предмет	id
remove_item	Убрать предмет	id
add_status	Добавить статус	status
remove_status	Убрать статус	status
set_flag	Установить флаг	flag, value
roll_table	Бросок по таблице	table
message	Показать сообщение	text

Команды бота

• /start - Начать игру или продолжить
• /status - Показать статус персонажа
• /help - Справка

Тестирование

# Установить pytest
pip install pytest

# Запустить тесты
pytest tests/ -v

Валидация сценариев

JSON Schema находится в schemas/campaign.schema.json. Можно использовать для валидации в CI/CD.

Переменные окружения

Переменная	Описание	По умолчанию
BOT_TOKEN	Токен Telegram бота	-
DB_PATH	Путь к SQLite базе	data/game.db
CAMPAIGN_PATH	Путь к кампаниям	campaigns
LOG_LEVEL	Уровень логирования	INFO

Лицензия

MIT

---

В мрачной тьме далёкого будущего есть только война...