DiscordSRV: настройка Discord бота для Minecraft сервера

Discord уже давно стал вторым домом для игровых комьюнити. Люди сидят там, даже когда не в игре, и логично, чтобы чат сервера был доступен оттуда же. DiscordSRV - самый популярный плагин для связки Minecraft с Discord. Он делает двусторонний мост чата, дублирует консоль в канал, синхронизирует роли, привязывает аккаунты и отправляет алерты о событиях сервера.

В этом гайде разберем всё: от создания бота в Developer Portal до тонкой настройки group sync и webhook-сообщений. Инструкция для Paper/Spigot/Purpur, но почти всё применимо и к другим форкам.

Что умеет DiscordSRV

Основные фичи, ради которых его ставят:

• Чат-мост: сообщения из игрового чата попадают в Discord-канал, и наоборот, сообщения из канала появляются в игре
• Консольный канал: вся консоль сервера летит в отдельный приватный канал, можно даже выполнять команды из Discord
• Алерты: join/leave игроков, смерти, достижения, падение/старт сервера
• Account linking: привязка Minecraft-ника к Discord-аккаунту через код
• Group sync: роли LuckPerms автоматически мапятся на роли Discord и обратно
• Webhook-сообщения: сообщения из игры приходят в Discord с аватаркой игрока, а не от имени бота
• API для аддонов: куча плагинов расширяют DiscordSRV (реакции как эмодзи, чат по каналам, модерация)

Альтернативы

Коротко о конкурентах, чтобы не гадать.

• DiscordIntegrator - проще, легче, без group sync и консоли. Подойдет, если нужен только базовый чат-мост
• EssentialsDiscord - часть EssentialsX, встроен в экосистему. Нет group sync, ограниченный функционал
• DiscordChat - минималистичный вариант, только чат
• UltimateChat с Discord-аддоном - платный, красивый, но overkill для большинства

DiscordSRV - стандарт де-факто. Живое сообщество, регулярные обновления, поддержка всех актуальных версий Minecraft от 1.8 до 1.21+. Дальше будем ставить именно его.

Установка плагина

1. Откройте страницу плагина на SpigotMC или GitHub Releases
2. Скачайте последний .jar под вашу версию Minecraft
3. Положите файл в папку plugins/ сервера
4. Перезапустите сервер (полный restart, не reload)

После старта в plugins/DiscordSRV/ появятся конфиги: config.yml, messages.yml, alerts.yml, synchronization.yml, linking.yml. Трогать сейчас их не нужно - сначала делаем бота.

Проверьте, что плагин загрузился:

/plugins

В списке должен быть DiscordSRV. Если красным - смотрите консоль, чаще всего это несовместимая версия Java или Minecraft.

Создание Discord-бота

Шаг 1: создать приложение

1. Откройте Discord Developer Portal
2. Нажмите New Application в правом верхнем углу
3. Введите имя (например, MyServer Bot) и примите условия
4. На вкладке General Information можно поменять иконку и описание - это то, что игроки увидят в Discord

Шаг 2: создать бота

1. В левом меню выберите Bot
2. Нажмите Add Bot -> Yes, do it!
3. Задайте никнейм и аватар бота (это отличается от имени приложения)

Шаг 3: получить токен

На той же странице Bot нажмите Reset Token -> Yes, do it!. Появится токен вида:

MTIzNDU2Nzg5MDEyMzQ1Njc4.Xy7Z_A.abcdefghijklmnopqrstuvwxyz

Скопируйте его сразу - Discord не покажет токен повторно, только даст сбросить. Никогда не публикуйте токен, не заливайте в git, не показывайте в скриншотах. Если токен утек - сразу сбрасывайте на той же странице.

Шаг 4: включить privileged intents

Это критичный шаг, без него бот не увидит сообщения пользователей.

На странице Bot найдите раздел Privileged Gateway Intents и включите:

• PRESENCE INTENT (опционально, для статусов)
• SERVER MEMBERS INTENT (обязательно для group sync)
• MESSAGE CONTENT INTENT (обязательно для чата)

Нажмите Save Changes.

Шаг 5: пригласить бота на сервер

1. Перейдите в раздел OAuth2 -> URL Generator
2. В Scopes отметьте: bot, applications.commands
3. В Bot Permissions отметьте минимум:
   • View Channels
   • Send Messages
   • Embed Links
   • Attach Files
   • Read Message History
   • Manage Messages (для редактирования/удаления)
   • Manage Roles (для group sync)
   • Manage Webhooks (для красивых сообщений с аватарами)
   • Add Reactions
4. Скопируйте сгенерированный URL внизу
5. Откройте URL в браузере, выберите свой Discord-сервер, подтвердите

Бот появится в списке участников, но пока оффлайн.

Получение Channel ID и Guild ID

DiscordSRV работает с числовыми ID, а не с названиями каналов. Чтобы их получить, включите Developer Mode в клиенте Discord:

1. User Settings -> Advanced -> Developer Mode: On
2. Правый клик по серверу (guild) -> Copy Server ID - это ID гильдии
3. Правый клик по каналу -> Copy Channel ID - это ID канала

ID выглядят так: 948273194820394820. Сохраните ID нужных каналов: #minecraft-chat (глобальный чат), #console (если будете зеркалить консоль), #server-events (для алертов).

Настройка DiscordSRV

Откройте plugins/DiscordSRV/config.yml. Самые важные параметры:

BotToken

BotToken: "MTIzNDU2Nzg5MDEyMzQ1Njc4.Xy7Z_A.abcdefghijklmnopqrstuvwxyz"

Вставьте токен из Developer Portal. Без него бот не запустится.

Channels

Здесь мапятся игровые каналы DiscordSRV на каналы Discord. global - дефолтный канал для всего чата.

Channels:
  global: "948273194820394820"
  staff: "948273194820394821"

Первое значение (global, staff) - имя канала в DiscordSRV, второе - ID канала в Discord. Несколько каналов позволяют разделить стафф-чат и публичный.

Console Channel

Отдельная секция для зеркалирования консоли:

DiscordConsoleChannelId: "948273194820394822"
DiscordConsoleChannelUsageLog: true
DiscordConsoleChannelBlacklistedCommands:
  - "?"
  - "op"
  - "deop"
  - "stop"

Канал должен быть приватным, с доступом только для админов - иначе любой, у кого есть права смотреть канал, сможет выполнять команды на сервере.

MinecraftChatToDiscordMessageFormat

Формат сообщений из Minecraft в Discord, редактируется в messages.yml:

MinecraftChatToDiscordMessage:
  Content: "%message%"
  Webhook:
    Enable: true
    AvatarUrl: "https://mc-heads.net/avatar/%uuid%/128"
    Username: "%username%"

Webhook-режим делает сообщения похожими на обычные сообщения Discord: с аватаркой игрока (из головы в Minecraft) и его никнеймом, а не от имени бота. Рекомендую включить.

DiscordChatChannelMinecraftMessage

Формат для обратного направления: из Discord в Minecraft.

DiscordToMinecraftChatMessageFormat: "&b[Discord] &r<%username%> %message%"
DiscordToMinecraftChatMessageFormatNoPrimaryGroup: "&b[Discord] &r<%username%> %message%"

Цвета через &-коды. %username% - Discord-ник, %message% - текст сообщения.

Полный пример минимального рабочего config.yml:

BotToken: "YOUR_TOKEN_HERE"

Channels:
  global: "948273194820394820"

DiscordConsoleChannelId: "948273194820394822"
DiscordConsoleChannelUsageLog: true

DiscordChatChannelPrefixRequiredToProcessMessage: ""

MinecraftDiscordAccountLinkedConsoleCommands:
  - "lp user %player% parent add verified"

MinecraftDiscordAccountUnlinkedConsoleCommands:
  - "lp user %player% parent remove verified"

Сохраните, в игре выполните /discord reload - плагин подхватит изменения без перезапуска сервера.

Account Linking (привязка аккаунтов)

Чтобы DiscordSRV знал, какой Discord-юзер соответствует какому игроку, нужна привязка. Без неё group sync и персональные аватары не работают.

Процесс привязки

1. Игрок в Minecraft вводит команду /discord link
2. Плагин выдает 4-значный код, например 4829
3. Игрок в Discord пишет этому боту в личку: link 4829
4. Бот отвечает подтверждением, привязка сохранена

Код одноразовый, действует ограниченное время (по умолчанию 15 минут). Отвязать: /discord unlink в игре или unlink боту в ЛС.

Автоматическая выдача роли за привязку

В linking.yml настраивается автовыдача ролей:

MinecraftDiscordAccountLinkedRoleNameToAddUserTo: "Verified"
MinecraftDiscordAccountLinkedConsoleCommands:
  - "lp user %player% parent add verified"
  - "say %player% привязал Discord!"

Игрок получит роль Verified в Discord и группу verified в LuckPerms сразу после привязки. Это удобно, чтобы отделить проверенных от случайных.

Обязательная привязка

Можно сделать вход на сервер только для привязавших Discord. В config.yml:

Require linked account to play:
  Enabled: true
  Subtract from online count: true
  Kick message: "Привяжите Discord: /discord link | Invite: discord.gg/yourserver"
  Whitelisted players bypass check: true

Пускать на сервер будут только игроков с привязкой. Для whitelisted-игроков можно оставить обход.

Group Sync (синхронизация ролей)

Одна из самых полезных фич. Настраивается в synchronization.yml.

GroupRoleSynchronizationGroupsAndRolesToSync:
  "admin": "948273194820394830"
  "moderator": "948273194820394831"
  "vip": "948273194820394832"
  "donator": "948273194820394833"
  "member": "948273194820394834"

GroupRoleSynchronizationOneWay: false
GroupRoleSynchronizationCycleTime: 10

Слева - группа в LuckPerms (или permission), справа - ID роли в Discord. Синхронизация работает в обе стороны по умолчанию: получил админа в LuckPerms - получил @Admin в Discord и наоборот.

OneWay: true заставит DiscordSRV только читать из Minecraft и писать в Discord, но не трогать LuckPerms обратно. Это безопаснее, если не хотите, чтобы кто-то с правами в Discord случайно получил права на сервере.

CycleTime: 10 - интервал в минутах, с которым плагин пересчитывает синхронизацию. Плюс она срабатывает по событиям (join, role change).

Иерархия ролей

Бот может выдавать только те роли, которые ниже его собственной в иерархии Discord. В настройках сервера Discord перетащите роль бота выше всех синхронизируемых ролей. Иначе получите в консоли Missing Permissions.

Alerts (алерты событий)

Файл alerts.yml. Позволяет слать в канал любые события сервера через custom-сообщения.

Alerts:
  - Trigger: "PlayerJoinEvent"
    Async: true
    Channel: "server-events"
    Content: ":green_circle: **%player%** присоединился к серверу"

  - Trigger: "PlayerDeathEvent"
    Async: true
    Channel: "server-events"
    Content: ":skull: %player% умер: `%event.deathMessage%`"

  - Trigger: "PlayerAdvancementDoneEvent"
    Async: true
    Conditions:
      - "event.advancement.display != null"
    Channel: "server-events"
    Content: ":trophy: **%player%** получил достижение **%event.advancement.display.title%**"

Триггеры - любые Bukkit-события. Условия позволяют фильтровать: например, не слать алерты на скрытые ачивки.

Для серверных событий (старт, стоп, краш) есть встроенные в config.yml:

DiscordChatChannelServerStartupMessage: ":green_circle: Сервер запущен"
DiscordChatChannelServerShutdownMessage: ":red_circle: Сервер остановлен"

Webhook-сообщения для красоты

Если включить в messages.yml:

MinecraftChatToDiscordMessage:
  Webhook:
    Enable: true
    AvatarUrl: "https://mc-heads.net/avatar/%uuid%/128"
    Username: "%username%"

Сообщения из игры будут показаны как отдельные "пользователи" в Discord, каждый со своим аватаром - головой игрока из Minecraft. Визуально это намного лучше стандартного вывода через бота, где все сообщения от одного имени.

Важно: боту нужно право Manage Webhooks в канале, иначе ничего не заработает. Также Discord ограничивает количество webhook-сообщений в минуту, на небольшом сервере это не проблема, но на 100+ онлайне может упираться в лимиты. В таком случае отключайте webhook или делайте батчинг.

Whitelist через Discord

Можно завязать вход на сервер на роль в Discord. Например, роль @Member должна давать whitelist.

Через group sync: мапим роль @Member на группу whitelisted в LuckPerms, в которой есть permission essentials.whitelist.bypass или просто добавление в whitelist.json через кастомные команды:

MinecraftDiscordAccountLinkedConsoleCommands:
  - "whitelist add %player%"

MinecraftDiscordAccountUnlinkedConsoleCommands:
  - "whitelist remove %player%"

Или написать свой алерт на RoleAddEvent от DiscordSRV API через плагин-аддон, но для большинства серверов хватает простой связки с group sync.

Troubleshooting

"No such channel" при старте

Плагин в логах пишет Could not find Discord channel by ID.... Причины:

• Неправильно скопирован ID канала (лишние пробелы, буквы вместо цифр)
• Бот не приглашен на сервер, где находится канал
• У бота нет прав View Channel на этот канал
• Канал - это категория или voice, а DiscordSRV ждет текстовый

Проверьте: в Discord зайдите в настройки канала -> Permissions, найдите роль бота, убедитесь, что View Channel включено.

"Missing Permissions" при выдаче ролей

WARN: Tried to assign role but lacks permissions

Две причины:

1. Роль бота в иерархии Discord ниже выдаваемой. Решение: перетащите роль бота выше в настройках Server -> Roles
2. У бота нет Manage Roles. Решение: Server Settings -> Roles -> роль бота -> включить Manage Roles

Сообщения не отправляются из Minecraft в Discord

• Проверьте, что global в Channels: мапится на правильный ID
• Проверьте, что бот онлайн (/discord в игре покажет статус)
• Посмотрите консоль сервера на ошибки JDA (библиотека, которую использует DiscordSRV)

Сообщения не отправляются из Discord в Minecraft

Почти всегда - не включен Message Content Intent в Developer Portal. Это новая политика Discord с 2022 года, без этого intent бот не видит содержимое сообщений. Включите, перезапустите сервер, проверьте.

Webhook-сообщения не работают

• Бот не имеет Manage Webhooks в нужном канале
• На сервере Discord достигнут лимит webhook (10 на канал)
• Proxy/CDN блокирует исходящие webhook-запросы с сервера Minecraft

Бот показывает "Connecting..." и не запускается

• Токен неправильный или сброшен - сгенерируйте новый в Developer Portal
• Токен случайно скопирован с пробелом или переводом строки
• У хостинга заблокированы исходящие соединения на gateway.discord.gg

Group sync не работает в одну из сторон

Проверьте GroupRoleSynchronizationOneWay. Если true, синхронизация идет только MC -> Discord. Для двусторонней поставьте false.

Также проверьте, что в LuckPerms нужные группы существуют (/lp group <name> info).

Безопасность и лучшие практики

1. Консольный канал - только для админов. Любой, кто может писать в канал, может выполнять команды на сервере. Выдавайте доступ к нему только доверенным людям
2. Бэкапьте токен в менеджере паролей. При утечке сбрасывайте сразу
3. Отдельные каналы для разных задач: #minecraft-chat публичный, #staff-chat приватный для модерации, #server-events для алертов, #console для админов
4. Не ставьте webhook для чата, если онлайн 200+. Лимиты Discord на webhook могут начать глючить
5. Roles bot выше sync ролей. Это экономит часы отладки
6. Используйте alerts умеренно. Канал, в который падает сотня алертов в минуту, никто не читает
7. Обновляйте DiscordSRV. Discord регулярно меняет API, старые версии плагина могут начать отваливаться

Финальный чеклист

• Плагин DiscordSRV в plugins/, сервер запущен, плагин зеленый
• Бот создан в Developer Portal, токен сохранен
• Включены три privileged intents (SERVER_MEMBERS, MESSAGE_CONTENT, PRESENCE)
• Бот приглашен на Discord-сервер через OAuth2 URL с нужными permissions
• Developer Mode включен, ID каналов скопированы
• В config.yml заполнены BotToken, Channels, DiscordConsoleChannelId
• В synchronization.yml настроен group sync (если нужен)
• Роль бота в Discord выше всех синхронизируемых ролей
• Консольный канал приватный
• Привязка аккаунта проверена через /discord link
• Отправка сообщений работает в обе стороны

Если все галочки проставлены, DiscordSRV готов к продакшену. Дальше можно добавлять аддоны: DiscordSRV-Reactions для реакций как эмодзи в игре, DiscordSRV-Voice для отображения голосовых каналов, SRVLinker для расширенной привязки - и превращать сервер в полноценную экосистему.