# Celestial Whitelister<\/p>\n
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.<\/p>\n
## Requirements<\/p>\n
– Paper 1.21.4+
\n– LuckPerms
\n– A Discord bot token (how to create one)<\/p>\n
## Installation<\/p>\n
1. Drop the plugin JAR into your server’s `plugins\/` folder.
\n2. Start the server once to generate the default `config.yml`.
\n3. Edit `plugins\/CelestialWhitelister\/config.yml` with your Discord bot token and role mappings.
\n4. Restart the server or run `\/celestialwhitelister reload`.<\/p>\n
Make sure your Discord bot has been invited to your guild with the `applications.commands` and `bot` scopes.<\/p>\n
## How It Works<\/p>\n
1. A member runs `\/whitelist ## Configuration<\/p>\n The config file is located at `plugins\/CelestialWhitelister\/config.yml`.<\/p>\n “`yaml # Language for plugin messages. Must match the name of a .ftl file # Mapping of Discord role IDs to LuckPerms group names. # The default LuckPerms group to assign if the user has none of the mapped roles. # UUID resolution, only applies to offline-mode servers. # Channel restriction, when enabled, the \/whitelist command will only work # Role requirement, when enabled, users must have at least one of the listed # One-time whitelist restriction. When enabled, each Discord user can only “`<\/p>\n ## Localization<\/p>\n CelestialWhitelister supports multiple languages using Project Fluent, a localization framework designed for natural, fluent translations.<\/p>\n ### Supported Languages<\/p>\n Currently supported languages: The plugin automatically selects the appropriate language file based on the `.ftl` files present in the `messages\/` directory.<\/p>\n ### Translation Files<\/p>\n Translation files are stored at `plugins\/CelestialWhitelister\/messages\/` in Project Fluent format (`.ftl`).<\/p>\n Each language has its own file: ### Adding a New Language<\/p>\n To add a new language:<\/p>\n 1. Create a new `.ftl` file in `plugins\/CelestialWhitelister\/messages\/` using the language code as the filename (e.g., `fr.ftl` for French). All `.ftl` files in the messages directory are automatically loaded and processed in alphabetical order.<\/p>\n ### Options<\/p>\n | Option | Description | ## Commands<\/p>\n ### In-game<\/p>\n | Command | Alias | Description | ### Discord<\/p>\n | Command | Description | ## Permissions<\/p>\n | Permission | Description | Default | ## Building<\/p>\n Requires Java 21+.<\/p>\n “`sh The compiled JAR will be in `build\/libs\/`.<\/p>\n","protected":false},"excerpt":{"rendered":" A Paper plugin for whitelist management that integrates with LuckPerms<\/p>\n","protected":false},"featured_media":38099,"template":"","meta":{"_minecraft_slug":"celestialwhitelister","_minecraft_project_id":"jNiWYkWv","_minecraft_author":"KernelFreeze","_minecraft_license":"MIT","_minecraft_downloads":16,"_minecraft_follows":0,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"celestialwhitelister.zip","_minecraft_size_bytes":97005,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-15T22:47:27.063583Z","_minecraft_date_created":"2026-02-16T21:08:14.037459Z","_minecraft_date_modified":"2026-02-15T00:56:24.954796Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/celestialwhitelister","_minecraft_icon_attachment_id":38099,"_minecraft_imported_at":"2026-06-01T19:34:41+00:00","_minecraft_import_hash":"2bd2c5f5b17526242bfdc73f3e96eec2","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[126,127,867,92],"mod_loader":[132],"minecraft_version":[62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-38098","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-management","mod_category-paper","mod_category-social","mod_category-utility","mod_loader-paper","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n
\n2. The plugin checks whether the member is allowed to use the command (channel and role restrictions, if enabled).
\n3. It looks up which LuckPerms group the member should receive based on their Discord roles and the `role-groups` mapping.
\n4. It resolves the Minecraft username to a UUID, adds the player to the server whitelist, and assigns the LuckPerms group.
\n5. The member receives a private (ephemeral) response in Discord confirming the result.<\/p>\n
\n# Discord bot token
\ndiscord-token: “YOUR_BOT_TOKEN_HERE”<\/p>\n
\n# in the messages folder (e.g. “en” for en.ftl, “es” for es.ftl).
\nlanguage: “en”<\/p>\n
\n# Players will be added to the LuckPerms group corresponding to
\n# the highest role they have from this list.
\n# Format: “discord_role_id”: “luckperms_group_name”
\nrole-groups:
\n “123456789012345678”: “vip”
\n “987654321098765432”: “member”<\/p>\n
\n# Leave empty to not assign any group if no roles match.
\ndefault-group: “default”<\/p>\n
\n# When enabled, the plugin will try to resolve the player’s online (Mojang) UUID first,
\n# falling back to an offline UUID if the player doesn’t have a Mojang account.
\n# On online-mode servers, online UUIDs are always used regardless of this setting.
\nforce-online-uuids: false<\/p>\n
\n# in the listed Discord channel IDs.
\nchannel-restriction:
\n enabled: false
\n channels:
\n – “111111111111111111”
\n – “222222222222222222”<\/p>\n
\n# Discord role IDs to use \/whitelist. This is checked independently of the
\n# role-groups mapping above.
\nrequired-roles:
\n enabled: false
\n roles:
\n – “333333333333333333”
\n – “444444444444444444”<\/p>\n
\n# use \/whitelist once. Their entry is stored in a local SQLite database.
\n# Users can change their whitelisted nickname using \/changenick instead.
\none-time-whitelist: true<\/p>\n
\n– **English** (en)
\n– **Spanish** (es)<\/p>\n
\n– `en.ftl` – English messages
\n– `es.ftl` – Spanish messages<\/p>\n
\n2. Translate all message keys from the English `en.ftl` file.
\n3. Reload the plugin with `\/celestialwhitelister reload`.<\/p>\n
\n|—|———————————————————————————————————————————-|
\n| `discord-token` | The bot token from the Discord Developer Portal. |
\n| `language` | The language for plugin messages. Must match a `.ftl` file in the messages folder (e.g., `”en”` for `en.ftl`). |
\n| `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. |
\n| `default-group` | The LuckPerms group assigned when no role matches. Set to `””` to reject users with no matching role instead. |
\n| `force-online-uuids` | When enabled on an **offline mode** server, the plugin will try to resolve the player’s online (Mojang) UUID first, |
\n| `channel-restriction.enabled` | When `true`, the `\/whitelist` command only works in the listed channels. |
\n| `channel-restriction.channels` | List of Discord channel IDs where the command is allowed. |
\n| `required-roles.enabled` | When `true`, members must have at least one of the listed roles to use the command. |
\n| `required-roles.roles` | List of Discord role IDs required to use `\/whitelist`. |
\n| `one-time-whitelist` | When `true`, each Discord user can only whitelist once. Use `\/changenick` to change the whitelisted nickname. |<\/p>\n
\n|—|—|—|
\n| `\/celestialwhitelister reload` | `\/cw reload` | Reloads the config and restarts the Discord bot. |<\/p>\n
\n|—|—|
\n| `\/whitelist
\n| `\/changenick
\n|—|—|—|
\n| `celestialwhitelister.reload` | Allows using `\/celestialwhitelister reload`. | OP |<\/p>\n
\n.\/gradlew build
\n“`<\/p>\n