Discord
概述
Discord 将你的 Minecraft 服务器与 Discord 服务器连接起来。所有发往 Discord 的内容都使用同一个可复用的对象：webhook destination（Discord 频道的 URL，加上名称和头像），只需声明一次，即可被所有功能引用。想要更换频道，只需修改一个条目。
该扩展涵盖六项功能：带有职位到身份组同步的账号关联、双向聊天转发、可从 Discord 运行服务器命令的控制台频道、游戏内 Bug 报告系统、商店交易公告，以及在 TypeWriter fact 变化时发布的 Webhook。每项功能都是独立的条目，因此你只需配置自己用到的部分。Discord 对 TypeWriter 的其余部分是可选的：没有 link manifest，就不会启动任何 Discord 机器人。
该扩展在 0.9 版本之前名为 Community。条目名称没有变化，在重命名之前编写的页面会在首次启动时被自动转换。
功能
- Webhook destinations — 每个 Discord 频道对应一个条目（URL、用户名、头像、固定的身份组提及），供所有功能共用。
- 账号关联 — 玩家运行命令获得一个验证码，在 Discord 频道中输入后即可关联账号；Discord 身份组会跟随其 Minecraft 权限组。
- 聊天同步 — Minecraft 聊天以及加入/离开消息会发送到 Discord，Discord 消息也可以回传到游戏中。
- 控制台频道 — 管理员可从 Discord 频道运行服务器命令，支持命令列表、身份组限制和日志文件。
- Bug 报告 — 游戏内的对话表单，附带状态跟踪存储，以嵌入消息或论坛帖子的形式发布到 Discord，并可通过 Discord 斜杠命令管理。
- 商店公告 — 购买和出售记录会发送到各商店指定的频道（需要 Shops 扩展）。
- Fact webhooks — 当 TypeWriter fact 发生变化时发送消息，可按玩家、按组或全局触发。
- 自动迁移 — 0.9 之前带有内联 webhook 的页面会被转换为 webhook destinations。
安装
- 在你想使用的频道中创建一个 Discord webhook：在 Discord 中依次进入 Channel settings（频道设置）、Integrations（整合）、Webhooks、New Webhook（新建 Webhook），然后复制其 URL。这对 webhook、Bug 报告和单向聊天已经足够。
- 若要使用账号关联、Discord 到 Minecraft 的聊天转发、控制台频道和斜杠命令，你还需要一个 Discord 机器人。请在 Discord Developer Portal 中创建，复制其 token，将它邀请到你的服务器，并在 Bot 下启用 Server Members Intent 和 Message Content Intent。扩展会请求这些 intent，没有它们就无法连接。
- 确保已安装 TypeWriter 的 Basic 扩展（参见 TypeWriter 文档）。
- 将 Discord 的 JAR 放入
plugins/Typewriter/extensions/，然后重启服务器。该 JAR 已内置机器人所使用的 JDA 库。 - 若要使用商店公告，还需安装 Shops 扩展。
Bug 报告使用 Paper 的对话界面，需要 Paper 1.21.6 或更高版本。
快速上手
关联账号，并将 Bug 报告发布到你的管理员频道：
- 在 TypeWriter 网页面板中，打开一个 manifest 页面，添加一个 Webhook Definition。将频道 URL 粘贴到
url，还可以选填username和avatarUrl。 - 在同一页面上添加一个 Discord Link Storage artifact：它用于存储关联记录和待验证的验证码。
- 添加一个 Discord Link Manifest。将
storage设为该 artifact，webhook设为你的 destination，启用bot，并填写botToken和guildId。将verificationChannelId设为玩家输入验证码的 Discord 频道。 - 可选：填写
roleMappings，按 Minecraft 权限组授予 Discord 身份组，例如minecraftGroup填vip，并在discordRoleId中填入 Discord 身份组 ID。 - 添加一个 Bug Report Sequence Storage artifact，然后添加一个 Bug Report Manifest。设置
commandName（例如bugreport）、sequenceStorage、serverName，并在categories中至少添加一项，其中包含一个key为description的输入项。在webhook中，将destination设为你的 destination。 - 发布。玩家运行
/discordlink获取验证码，在验证频道中输入后即完成关联。玩家运行/bugreport可打开表单。
要获取 Discord 频道或身份组的 ID，请在 Discord 的高级设置中开启开发者模式，然后右键点击该频道或身份组并选择 Copy ID（复制 ID）。
工作原理
发送使用 webhook，不需要机器人。从 Discord 接收内容则需要机器人，而机器人只在 Discord Link Manifest 中配置。如果没有启用机器人，Discord 到 Minecraft 的聊天转发、控制台频道和 Bug 报告斜杠命令都不会生效。
空的或被禁用的 destination 是“什么都不发送”的正常方式。对已不存在的 destination 的引用会被记录为 Destination '…' not found; message dropped。
配置
该扩展在网页面板中进行配置。关联数据和 Bug 报告存储在你创建的 artifact 条目中。除此之外，它还会写入：
| 文件 | 内容 |
|---|---|
logs/discord-console.log | 从控制台频道运行的命令（相对于服务器根目录；该路径是条目的一个字段）。 |
backup/community-webhook-v1/ | 从 Community 迁移时被重写的页面的备份，位于 Typewriter 文件夹中。 |
从 Community 迁移
0.9 之前编写的页面会把 webhook 存放在各个 manifest 内部。首次启动时，扩展会为每个不同的 destination 创建一个 Webhook Definition，让各 manifest 指向它，并且会先备份每个被重写的页面。随后它会提示你运行一次 /typewriter reload。
命令
下面的命令由 manifest 条目注册。它们的名称是这些条目的字段；此处显示的是默认值。
| 命令 | 说明 |
|---|---|
/discordlink | 生成验证码，或重复显示待验证的验证码。仅限玩家使用。 |
/discordlink unlink | 移除关联以及已映射的 Discord 身份组。 |
/bugreport | 打开分类选择，然后打开报告表单。 |
/bugreport mine | 列出你自己的报告。 |
/bugreport list [player] | 列出报告，可选择只列出某位玩家的。需要管理员权限。 |
/bugreport status <reportId> <statusId> | 更改某份报告的状态。需要管理员权限。 |
/bugreport delete <reportId> | 删除某份报告。需要管理员权限。 |
当 discordCommands 开启时，Bug 报告 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 正确，并且在 Developer Portal 中已开启 Server Members 和 Message Content 这两个 intent。guildId 必须是服务器的 ID：如果填错，你会看到 guild not found。
/discordlink 提示未配置关联功能。 已发布的页面上没有 Discord Link Manifest。控制台会显示 discord_link_manifest not found; Discord link is disabled。
在 Discord 中输入的验证码被忽略。 玩家必须只输入验证码本身，恰好是 codeLength 个字母或数字，并且要在 verificationChannelId 所设置的频道中输入。机器人会以对勾或叉号作为回应。已过期的验证码（codeValidityMinutes）或已经关联的 Discord 账号会被拒绝。已经关联过的玩家同样会被拒绝，除非开启了 autoOverwriteExistingLink。
Bug 报告命令提示没有分类。 categories 默认为空。请至少添加一个分类。只有填写了 title 或 description 输入项的报告才会被接受，而表单会自己添加 title 输入项，所以请添加一个 key 为 description 的输入项来填写内容。
Bug 报告被 Discord 拒绝。 threadNameTemplate 是为论坛频道准备的。如果你的 destination 是普通文字频道，请清空该模板。控制台会显示 Webhook '…' rejected with HTTP … 以及原因。
控制台命令没有反应。 控制台频道需要机器人，并且 discordChannelId 中的频道 ID 必须匹配。被拦截的命令会收到禁止进入的表情回应，未授权的成员则会收到叉号。默认情况下，commandList 是一个包含 stop、restart 和 reload 的黑名单；若要更安全的设置，请切换为 blacklistIsWhitelist 并限制 allowedRoles。
商店的出售没有被公告。 你需要一个 Shop Notification Manifest（没有它就不会发送任何内容），并且商店定义必须在其 notificationWebhookId 中指定 destination，填写你的 Webhook Definition 条目的 ID。同时必须安装 Shops 扩展。
相关扩展
- Shops — 其商店会指定用于公告交易的 Webhook Definition。