Toutsu/GmRelayBot
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases 15 Wiki Activity
Page: Руководство ГМа
Pages
Архитектура База данных Быстрый старт Развёртывание Разработка Руководство ГМа Home
Clone
8
Руководство ГМа
Toutsu edited this page 2026-04-27 14:58:56 +03:00
Unescape Escape
Table of Contents
This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Руководство ГМа

Руководство описывает пользовательские сценарии бота и Web-панели для GM-Relay v1.7.0.

Кто управляет группой

При первом создании сессии в группе бот сохраняет автора как owner группы. Owner хранится в таблице group_managers с ролью Owner; историческое поле game_groups.gm_telegram_id остаётся для совместимости и миграций.

Owner может назначать помощников с ролью CoGm в Web Dashboard. Owner и co-GM могут создавать, отменять, удалять и переносить сессии, редактировать batch и поднимать игроков из листа ожидания. Только owner может добавлять или убирать co-GM.

Делегирование co-GM

На странице группы Web-панель показывает блок управления группой: owner, список co-GM и текущую роль пользователя. Чтобы добавить помощника, owner указывает Telegram ID, имя и при необходимости username. После сохранения co-GM видит эту группу на главной странице Web Dashboard и получает доступ к тем же операциям управления расписанием, что и owner.

Если co-GM больше не должен помогать с группой, owner удаляет его из того же блока. Снятие роли не удаляет игрока из таблицы players и не меняет его записи на игры.

Создание расписания

Команда:

/newsession
Название: Легенды Берега Мечей
Время: 15.05.2026 19:30
Время: 22.05.2026 19:00
Мест: 4
Ссылка: https://example.com/join

Поддерживаемые строки:

  • Название: — общий заголовок пачки игр.
  • Время: — дата и время в МСК. Можно указать несколько строк.
  • Мест: — необязательный лимит основного состава для каждой сессии в пачке.
  • Ссылка: — ссылка для подключения к игре.

Если Мест: не указан, запись остаётся без лимита. Если указан лимит, бот показывает заполненность в формате Места: 2/4.

Запись игроков и лист ожидания

Игроки записываются через inline-кнопки вида На <дата> в сообщении расписания.

Поведение при записи:

  • если мест достаточно, игрок попадает в основной состав со статусом RSVP Pending;
  • если лимит заполнен, игрок попадает в Лист ожидания и не считается активным участником игры;
  • повторная запись отвечает, что игрок уже записан или уже находится в листе ожидания.

Игроки из листа ожидания не участвуют в RSVP, голосовании переноса и рассылке ссылки на игру, пока GM не поднимет их в основной состав.

Самостоятельный выход игрока

Игрок может снять запись кнопкой Выйти <дата> в сообщении расписания.

Поведение при выходе:

  • если игрок был в основном составе, его запись удаляется из сессии;
  • если игрок был в листе ожидания, он удаляется из очереди;
  • если после выхода из основного состава есть свободное место и лист ожидания не пуст, бот автоматически переводит первого ожидающего в основной состав;
  • после изменения бот перерисовывает сообщение расписания, чтобы список участников и очередь оставались актуальными.

Повышение из листа ожидания

Owner или co-GM может поднять первого игрока из очереди:

  • в Telegram — кнопкой Из ожидания (ГМ) в сообщении расписания;
  • в Web Dashboard — кнопкой Из ожидания в списке сессий.

Повышение возможно только если в основном составе есть свободное место. Если лимит заполнен, сначала увеличьте Мест: в Web-редактировании сессии. При самостоятельном выходе активного игрока первый ожидающий повышается автоматически.

Bulk-операции для batch в Web

На странице группы Web-панель показывает отдельный блок для каждой видимой пачки игр. Owner и co-GM могут:

  • обновить общий title и link сразу у всех сессий batch;
  • выбрать режим уведомлений для игроков: В группе и в личку или Только в группе;
  • перенести всю пачку, задав новую первую дату и фиксированный шаг между играми в днях;
  • клонировать batch на следующую неделю или следующий календарный месяц.

Редактирование title/link и перенос перерисовывают исходное Telegram-сообщение расписания. Клонирование создаёт новую пачку с новым batch_id, новым Telegram-сообщением и пустым составом игроков.

Режим В группе и в личку оставляет все групповые сообщения и дополнительно отправляет активным игрокам персональные уведомления в ЛС. Режим Только в группе отключает личные сообщения для batch, но не меняет публикацию в групповом чате.

Отмена и удаление

  • Отменить <дата> (ГМ) в сообщении расписания меняет статус сессии на Cancelled и оставляет её в истории пачки.
  • /listsessions показывает будущие сессии; если команду вызывает owner или co-GM, бот добавляет кнопки удаления.
  • Удаление физически удаляет сессию из БД. Если после удаления пачка пустая и была создана forum-тема, бот пытается удалить тему.

Перенос сессии

Перенос запускается кнопкой ⏰ (ГМ) в сообщении расписания.

Поток:

  1. Бот проверяет, что кнопку нажал owner или co-GM.
  2. Создаётся reschedule_proposals со статусом AwaitingTime.
  3. Инициатор переноса пишет 2-3 варианта нового времени и дедлайн обычным сообщением в чат.
  4. Если активных участников нет, бот переносит сессию сразу на первый предложенный вариант.
  5. Если активные участники есть, бот создаёт голосование с кнопкой для каждого варианта.
  6. Участники видят текущие результаты в Telegram-сообщении и могут менять голос до дедлайна.
  7. По дедлайну побеждает вариант с наибольшим числом голосов. Если голосов нет или есть ничья, перенос отклоняется.
  8. При успешном переносе бот сбрасывает RSVP активных участников в Pending, очищает confirmation_message_id и link_message_id, обновляет batch-сообщение и отправляет результат в ЛС при включённом DM-режиме.

Формат ввода:

25.04.2026 19:30
26.04.2026 18:00
Дедлайн: 25.04.2026 12:00

RSVP и ссылка на игру

За 24 часа до плановой сессии бот отправляет RSVP-сообщение активным участникам:

  • Буду переводит участника в Confirmed.
  • Не смогу переводит участника в Declined, а GM получает личное уведомление.

Когда все активные участники подтвердили участие, сессия переходит в Confirmed, группа и GM получают уведомления.

За 5 минут до подтверждённой сессии бот отправляет ссылку на подключение и список подтверждённых активных участников.

Если для batch включены личные уведомления, игроки дополнительно получают DM о RSVP за 24 часа, напоминание примерно за 1 час до старта, ссылку перед игрой, отмену и результат переноса. Если бот не может написать игроку в ЛС, отправка остальным участникам продолжается.

Web-панель

Web UI доступен после входа через Telegram Login Widget. Owner и co-GM могут:

  • видеть свои Telegram-группы;
  • открыть список предстоящих сессий группы;
  • видеть заполненность и размер листа ожидания;
  • редактировать название, время, ссылку и лимит мест;
  • поднять первого игрока из листа ожидания, если есть свободное место;
  • выполнять bulk-операции над batch: общий title/link, перенос пачки и клонирование на неделю или месяц.
  • выбирать режим уведомлений batch: групповые сообщения с личными DM или только групповые сообщения.

Дополнительно owner может управлять списком co-GM на странице группы.

При сохранении отдельной сессии Web-панель обновляет запись в БД, отправляет уведомление в Telegram-группу и пытается перерисовать исходное сообщение расписания пачки. Bulk-операции обновляют исходное batch-сообщение, а clone публикует новое сообщение для новой пачки.