Celestial Whitelister
一个 Paper 插件,允许玩家通过 Discord /whitelist 斜杠命令将自己添加到白名单。当有人使用此命令时,该插件会将其加入 Minecraft 服务器白名单,并根据其 Discord 角色分配 LuckPerms 用户组。
要求
安装
- 将插件 JAR 文件放入服务器的
plugins/ 文件夹中。
- 启动服务器一次以生成默认的
config.yml。
- 编辑
plugins/CelestialWhitelister/config.yml,填入你的 Discord 机器人令牌和角色映射。
- 重启服务器或运行
/celestialwhitelister reload。
确保已将你的 Discord 机器人邀请到你的服务器中,并授予了 applications.commands 和 bot 权限范围。
工作原理
-
成员在你的 Discord 服务器中运行 /whitelist <nickname>。
-
插件检查该成员是否被允许使用此命令(包括频道和角色限制,如果已启用)。
-
它根据成员的 Discord 角色以及 role-groups 映射关系,查找其应获得的 LuckPerms 组别。
-
它将 Minecraft 用户名解析为 UUID,将玩家添加到服务器白名单中,并分配 LuckPerms 组。
-
成员会在 Discord 上收到一条私有的(临时)回复,确认操作结果。
配置
配置文件位于 plugins/CelestialWhitelister/config.yml。
# Discord 机器人令牌
discord-token: "YOUR_BOT_TOKEN_HERE"
# 插件消息的语言。必须与 messages 文件夹中某个 .ftl 文件的名称匹配
#(例如,「en」对应 en.ftl,「es」对应 es.ftl)。
language: "en"
将 Discord 角色 ID 映射到 LuckPerms 组名。
玩家将被添加到与该列表中最高的角色对应的 LuckPerms 组中。
格式:"discord_role_id": "luckperms_group_name"
role-groups:
"123456789012345678": "vip"
"987654321098765432": "member"
如果用户没有任何已映射的角色,则分配给玩家的默认 LuckPerms 组。
留空表示如果没有匹配的角色,则不分配任何组。
default-group: "default"
UUID 解析,仅适用于离线模式服务器。
启用后,插件将优先尝试解析玩家的在线(Mojang)UUID,
如果玩家没有 Mojang 账户,则回退到离线 UUID。
在在线模式服务器上,无论此设置如何,始终使用在线 UUID。
force-online-uuids: false
频道限制,启用后,/whitelist 命令仅在列出的 Discord 频道 ID 中生效。
channel-restriction:
enabled: false
channels:
- "111111111111111111"
- "222222222222222222"
角色要求,启用后,用户必须拥有至少一个列出的 Discord 角色 ID 才能使用 /whitelist。
此检查独立于上述的 role-groups 映射进行。
required-roles:
enabled: false
roles:
- "333333333333333333"
- "444444444444444444"
一次性白名单限制。启用后,每个 Discord 用户只能使用一次 /whitelist。
他们的条目存储在本地 SQLite 数据库中。
用户可以使用 /changenick 更改其白名单昵称。
one-time-whitelist: true
## 本地化
CelestialWhitelister 支持使用 [Project Fluent](https://projectfluent.org/) 进行多语言翻译,这是一个专为自然、流畅翻译而设计的本地化框架。
### 支持的语言
当前支持的语言:
- **English** (en)
- **Spanish** (es)
插件会根据 `messages/` 目录中存在的 `.ftl` 文件自动选择相应的语言文件。
### 翻译文件
翻译文件存储在 `plugins/CelestialWhitelister/messages/` 目录下,采用 [Project Fluent](https://projectfluent.org/fluent.html) 格式(`.ftl`)。
每种语言都有自己对应的文件:
- `en.ftl` - English 消息
- `es.ftl` - Spanish 消息
### 添加新语言
要添加新语言:
1. 在 `plugins/CelestialWhitelister/messages/` 中创建一个以语言代码为文件名(例如法语为 `fr.ftl`)的新 `.ftl` 文件。
2. 从英文 `en.ftl` 文件中翻译所有消息键。
3. 使用 `/celestialwhitelister reload` 重新加载插件。
messages 目录中的所有 `.ftl` 文件会按照字母顺序自动加载和处理。
### 选项
| 选项 | 说明 |
|---|----------------------------------------------------------------------------------------------------------------------------------|
| `discord-token` | 来自 Discord 开发者门户的机器人令牌。 |
| `language` | 插件消息的语言。必须与消息文件夹中的 `.ftl` 文件匹配(例如,`"en"` 对应 `en.ftl`)。 |
| `role-groups` | Discord 角色 ID 到 LuckPerms 组名的映射。成员拥有的第一个出现在此映射中的角色将决定其所属组。 |
| `default-group` | 当没有角色匹配时分配的 LuckPerms 组。设置为 `""` 以拒绝没有匹配角色的用户。 |
| `force-online-uuids` | 在**离线模式**服务器上启用时,插件将优先尝试解析玩家的在线(Mojang)UUID, |
| `channel-restriction.enabled` | 当为 `true` 时,`/whitelist` 命令仅在列出的频道中生效。 |
| `channel-restriction.channels` | 允许使用该命令的 Discord 频道 ID 列表。 |
| `required-roles.enabled` | 当为 `true` 时,成员必须拥有所列角色之一才能使用该命令。 |
| `required-roles.roles` | 使用 `/whitelist` 所需的 Discord 角色 ID 列表。 |
| `one-time-whitelist` | 当为 `true` 时,每个 Discord 用户只能加入白名单一次。使用 `/changenick` 更改已加入白名单的昵称。 |
## 命令
### 游戏内
| 命令 | 别名 | 说明 |
|---|---|---|
| `/celestialwhitelister reload` | `/cw reload` | 重新加载配置文件并重启 Discord 机器人。 |
### Discord
| 命令 | 说明 |
|---|---|
| `/whitelist <nickname>` | 将 Minecraft 玩家加入白名单并分配其 LuckPerms 组。 |
| `/changenick <nickname>` | 更改你的白名单昵称(仅在启用 `one-time-whitelist` 时可用)。 |
## 权限
| 权限 | 说明 | 默认值 |
|---|---|---|
| `celestialwhitelister.reload` | 允许使用 `/celestialwhitelister reload`。 | OP |
## 构建
需要 Java 21+。
```sh
./gradlew build
编译后的 JAR 文件将位于 build/libs/ 中。
Celestial Whitelister
A Paper plugin that lets players whitelist themselves through a Discord /whitelist slash command. When someone uses the command, the plugin adds them to the Minecraft server whitelist and assigns a LuckPerms group based on their Discord roles.
Requirements
- Paper 1.21.4+
- LuckPerms
- A Discord bot token (how to create one)
Installation
- Drop the plugin JAR into your server's
plugins/ folder.
- Start the server once to generate the default
config.yml.
- Edit
plugins/CelestialWhitelister/config.yml with your Discord bot token and role mappings.
- Restart the server or run
/celestialwhitelister reload.
Make sure your Discord bot has been invited to your guild with the applications.commands and bot scopes.
How It Works
- A member runs
/whitelist <nickname> in your Discord server.
- The plugin checks whether the member is allowed to use the command (channel and role restrictions, if enabled).
- It looks up which LuckPerms group the member should receive based on their Discord roles and the
role-groups mapping.
- It resolves the Minecraft username to a UUID, adds the player to the server whitelist, and assigns the LuckPerms group.
- The member receives a private (ephemeral) response in Discord confirming the result.
Configuration
The config file is located at plugins/CelestialWhitelister/config.yml.
# Discord bot token
discord-token: "YOUR_BOT_TOKEN_HERE"
# Language for plugin messages. Must match the name of a .ftl file
# in the messages folder (e.g. "en" for en.ftl, "es" for es.ftl).
language: "en"
# Mapping of Discord role IDs to LuckPerms group names.
# Players will be added to the LuckPerms group corresponding to
# the highest role they have from this list.
# Format: "discord_role_id": "luckperms_group_name"
role-groups:
"123456789012345678": "vip"
"987654321098765432": "member"
# The default LuckPerms group to assign if the user has none of the mapped roles.
# Leave empty to not assign any group if no roles match.
default-group: "default"
# UUID resolution, only applies to offline-mode servers.
# When enabled, the plugin will try to resolve the player's online (Mojang) UUID first,
# falling back to an offline UUID if the player doesn't have a Mojang account.
# On online-mode servers, online UUIDs are always used regardless of this setting.
force-online-uuids: false
# Channel restriction, when enabled, the /whitelist command will only work
# in the listed Discord channel IDs.
channel-restriction:
enabled: false
channels:
- "111111111111111111"
- "222222222222222222"
# Role requirement, when enabled, users must have at least one of the listed
# Discord role IDs to use /whitelist. This is checked independently of the
# role-groups mapping above.
required-roles:
enabled: false
roles:
- "333333333333333333"
- "444444444444444444"
# One-time whitelist restriction. When enabled, each Discord user can only
# use /whitelist once. Their entry is stored in a local SQLite database.
# Users can change their whitelisted nickname using /changenick instead.
one-time-whitelist: true
Localization
CelestialWhitelister supports multiple languages using Project Fluent, a localization framework designed for natural, fluent translations.
Supported Languages
Currently supported languages:
- English (en)
- Spanish (es)
The plugin automatically selects the appropriate language file based on the .ftl files present in the messages/ directory.
Translation Files
Translation files are stored at plugins/CelestialWhitelister/messages/ in Project Fluent format (.ftl).
Each language has its own file:
en.ftl - English messages
es.ftl - Spanish messages
Adding a New Language
To add a new language:
- Create a new
.ftl file in plugins/CelestialWhitelister/messages/ using the language code as the filename (e.g., fr.ftl for French).
- Translate all message keys from the English
en.ftl file.
- Reload the plugin with
/celestialwhitelister reload.
All .ftl files in the messages directory are automatically loaded and processed in alphabetical order.
Options
| Option |
Description |
discord-token |
The bot token from the Discord Developer Portal. |
language |
The language for plugin messages. Must match a .ftl file in the messages folder (e.g., "en" for en.ftl). |
role-groups |
A map of Discord role ID to LuckPerms group name. The first role the member has that appears in this map determines their group. |
default-group |
The LuckPerms group assigned when no role matches. Set to "" to reject users with no matching role instead. |
force-online-uuids |
When enabled on an offline mode server, the plugin will try to resolve the player's online (Mojang) UUID first, |
channel-restriction.enabled |
When true, the /whitelist command only works in the listed channels. |
channel-restriction.channels |
List of Discord channel IDs where the command is allowed. |
required-roles.enabled |
When true, members must have at least one of the listed roles to use the command. |
required-roles.roles |
List of Discord role IDs required to use /whitelist. |
one-time-whitelist |
When true, each Discord user can only whitelist once. Use /changenick to change the whitelisted nickname. |
Commands
In-game
| Command |
Alias |
Description |
/celestialwhitelister reload |
/cw reload |
Reloads the config and restarts the Discord bot. |
Discord
| Command |
Description |
/whitelist <nickname> |
Whitelist a Minecraft player and assign their LuckPerms group. |
/changenick <nickname> |
Change your whitelisted nickname (only available when one-time-whitelist is enabled). |
Permissions
| Permission |
Description |
Default |
celestialwhitelister.reload |
Allows using /celestialwhitelister reload. |
OP |
Building
Requires Java 21+.
./gradlew build
The compiled JAR will be in build/libs/.
评论 0
登录后参与评分
还没有评论,来抢沙发吧