Discord Role Sync - 角色同步插件

💡Discord Role Sync

DiscordRoleSync 是一款用于同步 Discord 角色与 Minecraft 权限组的插件。此同步是单向的，仅从 Discord 同步至 Minecraft，而非双向同步。

您可以配置一个受管理的 Discord 角色列表，并将其关联到 Minecraft 权限组。当 Discord 用户获得某个角色时，他们将被添加到对应的 Minecraft 组中；反之，当角色被移除时，他们也会从 Minecraft 组中被移除。该插件支持 SQLite（自动创建，无需设置）或 MySQL 数据库，对于大型服务器，推荐使用 MySQL 以获得更好的稳定性。插件已测试支持 Minecraft 1.8.8 至 1.21 版本。

🎮功能特性

以下功能为可选，可在配置文件中启用或禁用。

• 角色同步：将 Discord 角色同步至 Minecraft 权限组。用户将根据其拥有的 Discord 角色，被自动添加或移除对应的 Minecraft 组。
• 授予链接角色：为已链接的用户添加指定的 Discord 角色。
• 白名单控制：使用 Discord 角色来控制谁可以访问您的服务器（白名单）。
• 昵称更新：根据用户的 Minecraft 用户名更新其在 Discord 中的昵称。
• PlaceholderAPI 集成：支持与 PlaceholderAPI 集成。

🔧安装指南

前置需求

• Vault：此插件必须安装 Vault，否则无法工作。
• 权限插件：您还需要安装一个与 Vault 兼容的权限插件，例如 LuckPerms 或其他替代品。
• Java 版本：插件目标运行环境为 Java 11，但也有报告称可在 Java 8 上运行。不提供对 Java 11 以下版本的支持。

安装步骤

• 将插件的 .jar 文件复制到服务器的 plugins 文件夹中。
• 启动服务器一次以生成配置文件。插件会因缺少配置而报错，这在首次运行时是正常现象。
• 停止服务器，编辑生成的 config.yml 文件，添加您的 Discord 机器人令牌。

获取并配置 Discord 机器人令牌

• 访问 Discord 开发者门户。
• 点击 “New Application”，为您的机器人命名。
• 在左侧边栏，点击 “Bot”。
• 点击 “Add Bot” 并确认。
• 在此页面，您可以更改机器人的头像和用户名。
• 务必开启 “Server Members Intent”，否则机器人无法获取成员列表，插件将无法工作。
• 点击 “Copy Token”，将其粘贴到插件的配置文件中。请像保护密码一样保密此令牌。
• 返回开发者门户，在左侧边栏点击 “OAuth2”。
• 在 “Scopes” 中选择 “bot”，然后复制生成的链接。
• 访问该链接，将机器人添加到您的 Discord 服务器。

配置角色 ID

您需要在配置文件中填写角色 ID，而不是角色名称。获取 ID 的方法如下：

• 在 Discord 设置中启用 “开发者模式”。
• 右键点击目标角色，选择 “复制 ID”（一串约 18 位的数字）。
• 服务器 ID 和频道 ID 的获取方式相同。

⭐工作原理

用户链接

所有用户都应在 Discord 中使用 /link 命令来关联他们的 Minecraft 账户：

/link myMCusername

一旦链接成功，只要用户在服务器中，他们的角色就会保持同步。当用户在 Discord 中获得角色时，他们将自动获得对应的 Minecraft 权限组，更新是即时的。

管理命令

管理员可以使用 /admlink 命令强制关联用户：

/admlink discordID mcUsername

其中 Discord ID 是一个 17 到 20 位的数字。

此外，管理员还可使用 /info 和 /unlink 命令，这两个命令都接受 Discord ID 或 Minecraft 用户名作为参数。默认情况下，拥有 Discord MANAGE_ROLES 权限的用户即可使用这三个管理命令，此权限可在您的 Discord 服务器中进行修改。

注意事项

• 用户必须保持在 Discord 服务器中才能维持其角色。如果他们离开服务器或被 /unlink 命令解除链接，他们将从白名单中移除，并且所有关联的角色都会被撤销。
• 如果启用了验证功能（在配置中设置 requireVerification: true），用户在被白名单踢出时（如果启用了白名单管理）或在 Minecraft 聊天中输入 /drs verify 时会获得一个验证码。然后他们需要在 Discord 中使用 /verify <code> 命令发送此验证码。

❓语言与翻译

支持的语言

目前插件内置支持以下语言

• 英语 (en_US)
• 葡萄牙语 (pt_BR)
• 意大利语 (it_IT)
• 法语 (fr_FR)
• 西班牙语 (es_ES)
• 土耳其语 (tr_TR)
• 德语 (de_DE)
• 日语 (ja_JP)
• 俄语 (ru_RU)

贡献翻译

如果您想添加新语言，可以复制 en_US.yml 文件并编辑为您的语言。如果您希望您的翻译被包含在插件中，请通过 Discord 联系我或在 GitLab 上提交合并请求，我很乐意将其加入。

请注意，随着插件更新，只有英语和葡萄牙语会得到及时更新（因为这是我使用的语言）。其他语言可能会过时，届时将默认使用英语。如果您愿意帮助更新这些语言，请告知我！

✨权限插件兼容性

此插件应与所有支持 Vault 的权限插件兼容。

已测试确认可用的插件

• LuckPerms（推荐）
• Ultra Permissions
• PermissionsEx（已弃用）
• PowerRanks

关于 PermissionsEx 的说明：不建议使用 PermissionsEx，因为它已弃用且不支持异步权限添加。在大型服务器上使用可能会导致性能下降。

🎮权限节点

• discordrolesync.reload：允许使用 /drs reload 命令。
• discordrolesync.botrestart：允许使用 /drs botrestart 命令。
• discordrolesync.notifyupdates：拥有此权限的用户在加入服务器时，如果插件有更新可用，会收到通知。
• discordrolesync.bypasswhitelist：拥有此权限的用户即使未链接账户，在白名单启用时也始终被允许加入。请注意，对于大多数权限插件，需要用户先尝试加入服务器才能为其添加权限。
• 所有用户默认允许使用 /drs verify 命令。

🔧集成功能

PlaceholderAPI

在配置中将 integrations.plugins.PlaceholderAPI 设置为 true 即可启用 PlaceholderAPI 集成。

• 这将允许机器人的状态消息读取占位符。
• 同时，插件会提供一个 Placeholder 扩展，支持以下占位符：

- `%drs linked users%`：已链接的用户数量。

- `%drs link status%`：用户是否已链接。

- `%drs discord username%`：用户的 Discord 用户名（如果已链接），否则为空。

- `%drs discord display_name%`：用户在 Discord 中的昵称（如果已链接），否则为空。

PlaceholderAPI 集成是新增功能，可能仍需改进。如果您有功能请求或错误报告，请告知我。

Geyser

在配置中将 experimental.geyser.enableGeyserSupport 设置为 true 即可启用 Geyser 集成。

• 启用后，链接以点开头的用户名（例如 .exampleuser）将被视为 Geyser 用户。

这是一个实验性功能。如果您有功能请求或错误报告，请告知我。

❓功能请求、错误报告与贡献

此插件是开源的！源代码可在 GitLab 上找到。更多信息请参阅 CONTRIBUTING.md 文件。

欢迎贡献！我最近重新开始维护此插件，并正在清理代码。我不是 Java 专家，所以如果您愿意，可以提交代码清理或优化建议。

如果需要，您可以通过 GitLab 或 Discord 联系我。报告错误或请求功能，可以在 GitLab 上创建 Issue，或通过 Discord 联系我。

💡已知问题与限制

离线服务器模式

请注意，在离线模式服务器中，链接用户名是区分大小写的。

虽然此插件适用于离线服务器，但可能会与那些在用户加入后更改其 UUID 的“登录插件”冲突。如果您使用登录插件，请尝试配置中的 userUUIDMode 为 FALLBACK 或 MANUAL 选项。

数据库注意事项

如果您在离线模式和在线模式之间切换（无论是通过更改 UUID 模式配置还是服务器模式），都需要删除数据库。

• 如果使用 SQLite，只需删除 database.db 文件。
• 如果使用 MySQL，请执行 DROP TABLE syncbot_discordmcusers; 命令（如果您的 config.yml 中更改了表前缀，请将 syncbot 替换为您的实际前缀）。