Discord
Обзор
Discord соединяет ваш сервер Minecraft с вашим сервером Discord. Всё, что отправляется в Discord, использует один повторно применяемый объект: получатель вебхука (webhook destination) — URL канала Discord плюс имя и аватар, который объявляется один раз и используется во всех функциях. Чтобы сменить канал, достаточно отредактировать одну запись.
Расширение выполняет шесть задач: связывание аккаунтов с синхронизацией рангов и ролей, двусторонняя ретрансляция чата, консольный канал для выполнения серверных команд из Discord, внутриигровая система отчётов об ошибках, объявления о транзакциях в магазинах и вебхуки, публикуемые при изменении факта TypeWriter. Каждая функция — отдельная запись, поэтому вы настраиваете только то, чем пользуетесь. Для остального TypeWriter Discord необязателен: без manifest связывания бот Discord не запускается.
До версии 0.9 это расширение называлось Community. Названия записей не изменились, а страницы, написанные до переименования, преобразуются при первом запуске.
Возможности
- Получатели вебхуков — одна запись на канал Discord (URL, имя пользователя, аватар, постоянные упоминания ролей), общая для всех функций.
- Связывание аккаунтов — игроки выполняют команду, чтобы получить код, вводят его в канале Discord, и их аккаунты связываются; роли Discord следуют за группами Minecraft.
- Синхронизация чата — чат Minecraft и сообщения о входе и выходе отправляются в Discord, а сообщения из Discord могут возвращаться в игру.
- Консольный канал — персонал выполняет серверные команды из канала Discord со списком команд, ограничением по роли и файлом журнала.
- Отчёты об ошибках — внутриигровая форма в диалоговом окне, хранение с отслеживанием статуса, публикация в Discord как embed или ветка форума и управление через слэш-команды Discord.
- Объявления магазинов — покупки и продажи публикуются в канале, указанном у каждого магазина (требуется расширение Shops).
- Вебхуки по фактам — сообщение при изменении факта TypeWriter для каждого игрока, группы или глобально.
- Автоматическая миграция — страницы до версии 0.9 со встроенными вебхуками преобразуются в получателей вебхуков.
Установка
- Создайте вебхук Discord в нужном канале: в Discord откройте Channel settings (Настройки канала), Integrations (Интеграции), Webhooks (Вебхуки), New Webhook (Новый вебхук), затем скопируйте его URL. Этого достаточно для вебхуков, отчётов об ошибках и односторонней отправки чата.
- Для связывания аккаунтов, ретрансляции чата из Discord в Minecraft, консольного канала и слэш-команд вам также нужен бот Discord. Создайте его на Discord Developer Portal, скопируйте его токен, пригласите на свой сервер и включите Server Members Intent и Message Content Intent в разделе Bot. Расширение запрашивает эти интенты и без них подключиться не может.
- Убедитесь, что установлено расширение TypeWriter Basic (см. документацию TypeWriter).
- Положите JAR-файл Discord в
plugins/Typewriter/extensions/и перезапустите сервер. JAR уже содержит библиотеку JDA, используемую для бота. - Для объявлений магазинов дополнительно установите расширение Shops.
Отчёты об ошибках используют диалоговые экраны Paper, для которых нужен Paper 1.21.6 или новее.
Быстрый старт
Свяжем аккаунты и направим отчёты об ошибках в канал персонала:
- В веб-панели TypeWriter откройте страницу manifest и добавьте Webhook Definition. Вставьте URL канала в
url, а при желании такжеusernameиavatarUrl. - Добавьте на той же странице артефакт Discord Link Storage: он хранит связи и ожидающие коды.
- Добавьте Discord Link Manifest. Укажите в
storageартефакт, вwebhook— вашего получателя, включитеbotи заполнитеbotTokenиguildId. ЗадайтеverificationChannelId— канал Discord, в котором игроки будут вводить свой код. - По желанию: заполните
roleMappings, чтобы выдавать роли Discord по группам Minecraft, напримерminecraftGroupvipи ID роли Discord вdiscordRoleId. - Добавьте артефакт Bug Report Sequence Storage, а затем Bug Report Manifest. Задайте
commandName(напримерbugreport),sequenceStorage,serverNameи хотя бы одну запись вcategoriesс полем ввода, у которогоkeyравенdescription. Вwebhookукажите вdestinationвашего получателя. - Опубликуйте. Игрок выполняет
/discordlink, чтобы получить код, вводит его в канале проверки и оказывается связан. Игрок выполняет/bugreport, чтобы открыть форму.
Чтобы узнать ID канала или роли Discord, включите Developer Mode (Режим разработчика) в расширенных настройках Discord, затем кликните правой кнопкой по каналу или роли и выберите Copy ID (Копировать ID).
Как это работает
Отправка использует вебхук, без бота. Для получения из Discord нужен бот, который настраивается только в Discord Link Manifest. Без включённого бота ретрансляция чата из Discord в Minecraft, консольный канал и слэш-команды отчётов об ошибках не работают.
Пустой или отключённый получатель — обычный способ ничего не отправлять. Ссылка на получателя, которого больше не существует, записывается в лог как Destination '…' not found; message dropped.
Конфигурация
Расширение настраивается в веб-панели. Данные связывания и отчёты об ошибках хранятся в создаваемых вами артефактах. Помимо них, оно записывает:
| Файл | Содержимое |
|---|---|
logs/discord-console.log | Команды, выполненные из консольного канала (путь от корня сервера; сам путь — поле записи). |
backup/community-webhook-v1/ | Резервная копия страниц, переписанных миграцией с Community, в папке Typewriter. |
Миграция с Community
Страницы, написанные до 0.9, хранили вебхук внутри каждого manifest. При первом запуске расширение создаёт по одному Webhook Definition на каждого отдельного получателя, направляет на него manifest и предварительно создаёт резервную копию каждой переписанной страницы. Затем оно просит один раз выполнить /typewriter reload.
Команды
Приведённые ниже команды регистрируются записями manifest. Их имена — поля этих записей; показаны значения по умолчанию.
| Команда | Описание |
|---|---|
/discordlink | Генерирует код подтверждения или повторяет ожидающий. Только для игроков. |
/discordlink unlink | Удаляет связь и сопоставленные роли Discord. |
/bugreport | Открывает выбор категории, а затем форму отчёта. |
/bugreport mine | Показывает ваши собственные отчёты. |
/bugreport list [player] | Показывает отчёты, при желании одного игрока. Требует права администратора. |
/bugreport status <reportId> <statusId> | Меняет статус отчёта. Требует права администратора. |
/bugreport delete <reportId> | Удаляет отчёт. Требует права администратора. |
При включённом discordCommands manifest отчётов об ошибках также регистрирует слэш-команду на вашем сервере Discord с именем, как у commandName, с подкомандами list, status и delete. Пользоваться ею могут только администраторы Discord или участники с ролью из discordAdminRoleIds.
Регистрация этих слэш-команд заменяет остальные слэш-команды этого бота на сервере.
Права
Все права — это поля записей, их можно изменять. Значения по умолчанию:
| Право | Даёт доступ к |
|---|---|
discordlink.notify | Получение сообщения, когда игрок связывает аккаунт (notifyPermission; пустое значение отключает). |
bugreport.notify | Получение сообщения при отправке отчёта (notifyPermission). |
bugreport.admin | Использование /bugreport list, status и delete (adminPermission). |
group.<group> | Соответствует сопоставлению ролей: первое сопоставление, чья группа проходит проверку, определяет роль игрока в Discord (groupPermissionFormat). |
Записи
Записей: 9, сгенерированы из исходного кода расширения.
События1
- Webhook Fact EventPublish a Discord webhook when a Typewriter fact changes
Команды2
- Bugreport ManifestConfigure bug report behaviour
- Discord Link ManifestConfigure Discord linking and role synchronization
Артефакты2
- Bugreport Sequence StorageBug report sequence storage
- Discord Link StorageDiscord link storage
Манифесты4
- Chat Sync ManifestConfigure Minecraft to Discord chat synchronization
- Console Channel ManifestConfigure Discord console channel
- Shop Notification ManifestFormat shop transactions announced on Discord
- Webhook DefinitionA reusable Discord webhook destination
Устранение неполадок
Бот не подключается. Консоль показывает Failed to connect Discord Bot или Discord Bot is disabled or token is missing. Проверьте, что bot включён и указан правильный botToken, а интенты Server Members и Message Content включены в Developer Portal. guildId должен быть ID сервера: если он неверный, вы увидите guild not found.
/discordlink сообщает, что связывание не настроено. На опубликованной странице нет Discord Link Manifest. Консоль показывает discord_link_manifest not found; Discord link is disabled.
Код, введённый в Discord, игнорируется. Игроки должны вводить только код, ровно codeLength букв или цифр, в канале, заданном в verificationChannelId. Бот реагирует галочкой или крестиком. Истёкший код (codeValidityMinutes) или уже связанный аккаунт Discord отклоняются. Уже связанный игрок тоже получает отказ, если не включено autoOverwriteExistingLink.
Команда отчёта об ошибке сообщает, что категорий нет. По умолчанию categories пуст. Добавьте хотя бы одну категорию. Отчёт принимается, только если заполнено поле title или description, а поле title форма добавляет сама, поэтому для сообщения добавьте поле с ключом description.
Discord отклоняет отчёты об ошибках. threadNameTemplate предназначен для каналов-форумов. Если ваш получатель — обычный текстовый канал, очистите шаблон. Консоль показывает Webhook '…' rejected with HTTP … с причиной.
Консольные команды ничего не делают. Консольному каналу нужен бот, а ID канала в discordChannelId должен совпадать. Заблокированная команда получает реакцию «запрещено», а неавторизованный участник — крестик. По умолчанию commandList — чёрный список, содержащий stop, restart и reload; для более безопасной настройки переключитесь на blacklistIsWhitelist и ограничьте allowedRoles.
Продажи в магазине не объявляются. Нужен Shop Notification Manifest (без него ничего не отправляется), а определение магазина должно указывать получателя в notificationWebhookId, используя ID вашей записи Webhook Definition. Расширение Shops должно быть установлено.
Связанные расширения
- Shops — его магазины указывают Webhook Definition, который объявляет их транзакции.