ShbDiscordBot/README.md

ShbDiscordBot

Paper-плагин со встроенным Discord-ботом для привязки Discord к Minecraft и выдачи LuckPerms permissions по ролям.

Как работает привязка

1. Участник настроенного Discord-сервера пишет боту в личных сообщениях /auth.
2. Бот выдаёт одноразовый шестизначный код на 10 минут.
3. Игрок выполняет на Minecraft-сервере /link <код>.
4. Плагин проверяет обе стороны и сохраняет discordId через ShbUtils Core API.

Существующие связи не перезаписываются. Незавершённые коды хранятся только в памяти и после рестарта исчезают.

Сборка и установка

./gradlew test shadowJar

Установите build/libs/ShbDiscordBot-1.0.jar и LuckPerms на Paper-сервер. Обычный *-plain.jar не является готовым артефактом для установки.

В Discord Developer Portal:

1. Создайте bot application.
2. Включите privileged intent Server Members Intent.
3. Пригласите бота в guild со scopes bot и applications.commands.
4. Разрешите участникам сервера отправлять боту личные сообщения.

Запустите сервер один раз, заполните plugins/ShbDiscordBot/config.yml и перезапустите его. Реальные discord.token и api.internal-secret нельзя публиковать или коммитить.

Конфигурация ролей

role-sync:
  interval-seconds: 300
  max-concurrent-requests: 4
  mappings:
    "123456789012345678":
      - "group.vip"
      - "server.chat.color"
    "234567890123456789":
      - "server.fly"

После успешной привязки, добавления роли и раз в пять минут плагин добавляет отсутствующие nodes игроку. Удаление Discord-роли не снимает ранее выданные permissions.

После изменения любых настроек выполните из консоли или от имени оператора:

/sdb reload

Команда сначала проверяет новый конфиг, затем полностью переподключает Discord-бота и API-клиент, пересоздаёт периодическую задачу и немедленно запускает синхронизацию ролей. Незавершённые шестизначные коды при этом аннулируются. Встроенная Paper-команда /reload намеренно не переопределяется.

Полный локальный справочник ShbUtils API находится в docs/API.md. Правила для следующих разработчиков и агентов — в AGENTS.md.

Если бот не видит guild

Сообщение Discord-бот не видит настроенный guild означает, что авторизация прошла, но Discord не вернул настроенный сервер для этого bot token.

• Скопируйте ID сервера через Discord Developer Mode и проверьте discord.guild-id.
• Убедитесь, что discord.token принадлежит тому же application, которого приглашали на сервер.
• Проверьте список Видимые guild в логе: он показывает guild IDs, доступные боту.
• Если список пуст, пригласите именно bot installation со scopes bot и applications.commands, а не только user installation.
• Включите Server Members Intent до повторного запуска плагина.