121 lines
6.5 KiB
Markdown
121 lines
6.5 KiB
Markdown
# 🎲 GM-Relay: TTRPG Session Scheduling Bot
|
|
|
|
**GM-Relay** — это высокопроизводительный Telegram-бот для Мастеров Подземелий (ГМов), предназначенный для автоматизации записи игроков на сессии и управления игровым расписанием.
|
|
|
|
Бот разработан с упором на скорость, минимальное потребление ресурсов и удобство использования в реальных игровых группах.
|
|
|
|
---
|
|
|
|
## ✨ Ключевые возможности
|
|
|
|
- **📅 Создание расписаний (Batch Sessions)**: Создавайте сразу несколько игр одним сообщением (на неделю или месяц вперед).
|
|
- **✋ Интерактивная запись**: Игроки записываются на конкретные даты нажатием одной кнопки.
|
|
- **📁 Поддержка Форумов (Telegram Topics)**: Бот автоматически создает тему во вложенных чатах Telegram под каждую новую пачку игр.
|
|
- **❌ Управление сессиями**: Мастер может отменять отдельные игры прямо в общем сообщении расписания.
|
|
- **🗓 Экспорт в Календарь**: Генерация файла `.ics` для добавления всех игр в Google, Apple или Яндекс Календарь одной командой.
|
|
- **🚀 Native AOT**: Скомпилирован в нативный бинарный файл. Мгновенный запуск и потребление памяти в десятки раз меньше обычных .NET приложений. Идеально для **Raspberry Pi**.
|
|
|
|
---
|
|
|
|
## 🛠 Технологический стек
|
|
|
|
- **Язык**: C# 13 (.NET 10)
|
|
- **База данных**: PostgreSQL
|
|
- **ORM**: Dapper (AOT-совместный через Dapper.AOT)
|
|
- **Миграции**: DbUp (автоматически при старте)
|
|
- **Контейнеризация**: Docker + Multi-arch build (AMD64/ARM64)
|
|
|
|
---
|
|
|
|
## 🚀 Быстрый старт (Docker Compose)
|
|
|
|
### 1. Подготовка
|
|
Убедитесь, что у вас установлены **Docker** и **Docker Compose**.
|
|
|
|
### 2. Настройка окружения
|
|
Скопируйте файл-шаблон и заполните его значениями:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Отредактируйте `.env`:
|
|
|
|
```env
|
|
# Токен вашего бота от @BotFather
|
|
TELEGRAM_BOT_TOKEN=ваш_токен_здесь
|
|
|
|
# Пароль для базы данных PostgreSQL
|
|
POSTGRES_PASSWORD=ваш_надежный_пароль
|
|
```
|
|
|
|
### 3. Запуск
|
|
Выполните команду:
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
Бот сам создаст базу данных, применит миграции и начнет слушать сообщения.
|
|
|
|
---
|
|
|
|
## ⚙️ Настройка в Telegram
|
|
|
|
Чтобы бот работал корректно в вашей игровой группе:
|
|
|
|
1. **Добавьте бота в группу** (или Супергруппу/Форум).
|
|
2. **Назначьте бота Администратором**.
|
|
3. **Необходимые права**:
|
|
* `Выбор тем` (Managed Topics) — **обязательно**, если вы используете Форум (Темы), иначе бот не сможет создавать ветки для игр.
|
|
* `Отправка сообщений` — само собой.
|
|
* `Закрепление сообщений` — рекомендуется для удобства игроков.
|
|
|
|
> [!TIP]
|
|
> Колонку "Мастер" (GM) бот определяет по первому человеку, который создал сессию в этой группе. Только этот пользователь сможет отменять игры через кнопки.
|
|
|
|
---
|
|
|
|
## 📝 Инструкция для Мастера
|
|
|
|
### Создание расписания игр
|
|
Используйте команду `/newsession` с описанием в следующем формате:
|
|
|
|
```text
|
|
/newsession
|
|
Название: Легенды Берега Мечей (D&D 5e)
|
|
Время: 15.05.2024 19:30
|
|
Время: 22.05.2024 19:00
|
|
Ссылка: https://discord.gg/invite-link
|
|
```
|
|
|
|
* **Название**: Заголовок игры (будет отображаться в списке).
|
|
* **Время**: Неограниченное количество строк "Время:" для каждой сессии.
|
|
* **Ссылка**: Ссылка на Discord/Roll20/Foundry (будет доступна игрокам).
|
|
|
|
### Другие команды
|
|
- `/listsessions` — Показать список всех актуальных игр в этой группе.
|
|
- `/reschedulesession` — Перенести сессию на другое время. Запускает голосование среди всех записавшихся игроков — время обновится только после единогласного одобрения.
|
|
- `/deletesession` — Удалить сессию. Автоматически закрывает связанную тему в Форуме.
|
|
- `/exportcalendar` — Получить файл `.ics` со всеми вашими будущими играми.
|
|
- `/help` — Справка по формату.
|
|
|
|
---
|
|
|
|
## 🏗 Разработка и сборка
|
|
|
|
Если вы хотите собрать проект вручную без Docker:
|
|
|
|
1. Установите [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0).
|
|
2. Настройте строку подключения в `appsettings.json` или через переменные окружения.
|
|
3. Для сборки Native AOT:
|
|
```bash
|
|
dotnet publish src/GmRelay.Bot/GmRelay.Bot.csproj -c Release
|
|
```
|
|
|
|
> [!NOTE]
|
|
> При использовании **Dapper** в режиме Native AOT, все SQL-запросы должны использовать строго типизированные DTO. Динамические типы (`dynamic`) не поддерживаются.
|
|
|
|
---
|
|
|
|
## 📜 Лицензия
|
|
Проект распространяется под лицензией MIT. Использование в некоммерческих целях приветствуется.
|