Initial commit: GM-Relay Telegram Bot
This commit is contained in:
@@ -0,0 +1,120 @@
|
||||
# 🎲 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. Использование в некоммерческих целях приветствуется.
|
||||
Reference in New Issue
Block a user