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

1. Drop the plugin JAR into your server's plugins/ folder.
2. Start the server once to generate the default config.yml.
3. Edit plugins/CelestialWhitelister/config.yml with your Discord bot token and role mappings.
4. 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

1. A member runs /whitelist <nickname> in your Discord server.
2. The plugin checks whether the member is allowed to use the command (channel and role restrictions, if enabled).
3. It looks up which LuckPerms group the member should receive based on their Discord roles and the role-groups mapping.
4. It resolves the Minecraft username to a UUID, adds the player to the server whitelist, and assigns the LuckPerms group.
5. 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:

1. Create a new .ftl file in plugins/CelestialWhitelister/messages/ using the language code as the filename (e.g., fr.ftl for French).
2. Translate all message keys from the English en.ftl file.
3. 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/.