Contents
- Bot Token
- Use ID For Roles
- Add and Remove Roles
- Add Roles
- Limited Add Roles
- Whitelisted Roles
- Banned Roles
- Target Text Channels
- Use Easy Whitelist
- Whitelisted Roles Auto Add
- Whitelisted Roles Auto Remove
- Limited Whitelist Enabled
- On Ban Events
- Max Whitelist Amount
- Username Validation
- Removed List Enabled
- Use Custom Messages
- Use Custom Prefixes
- Show Player Skin on Whitelist
- Show Player Count
- Show Vanished Players in Player Count
- Add In-Game Add and Removes To List
- Assign Permissions with Ultra Permissions
- Use On Whitelist Commands
Main Configuration File Location and Generation
To generate the main configuration file the plugin must be ran at least once, once this is done the location of the file will be: server-root/plugins/DiscordWhitelister/discord-whitelister.yml
Bot Token
discord-bot-token:
To get your bot token you must first create an application here: https://discord.com/developers/applications/ if you haven't already. Once you have created an application the token is located in the bot tab under token.
Use ID For Roles
use-id-for-roles: false
Accepts true or false (default: false).
When set to true, the bot will use IDs for roles instead of strings. This helps when your roles contain special characters or emojis. To get the Ids of a role, first developer mode must be enabled in your user settings on Discord (under Appearance) then right clicking the target role and clicking copy ID under Server Settings > Roles.
Add and Remove Roles
add-remove-roles:
- Owner
- Admin
Supports a singular role or multiple
Add and remove roles give the specified roles unlimited whitelist adds and removes therefore it should usually be reserved for the highest ranking members on your Discord, such as the owner or admins.
Add Roles
add-roles:
- Mod
Supports a singular role or multiple
Add roles give the specified roles unlimited whitelist adds with no access to the whitelist remove command. This role is recommended for staff members such as moderators.
Limited Add Roles
limited-add-roles:
- LimitedWhitelister
- NewMember
Supports a singular role or multiple, requires limited-whitelist-enabled to be set to true
Limited add roles are used when you want normal users to whitelist Minecraft usernames a limited amount of times. The amount of available whitelists per person is set with max-whitelist-amount. These roles are recommended to be enabled as they enable more features to be used.
Whitelisted Roles
whitelisted-roles:
- Whitelisted
Supports a singular role or multiple, requires limited-whitelist-enabled & whitelisted-role-auto-add to be set to true
Any role set in whitelisted-roles will be automatically assigned to the user if they are in any of the limited-add-roles on whitelist success.
Banned Roles
banned-roles:
- Banned
- BanAppealRole
Supports a singular role or multiple, requires limited-whitelist-enabled & use-on-ban-events to be set to true
The roles that will be assigned to the user when one of their registered Minecraft usernames is banned in-game. It is up to the server owner on how to handle these roles, for example: removing access to other text channels and only allowing access to a ban-appeal text channel.
Target Text Channels
target-text-channels:
- '482390428138194894'
- '478234927498237482'
Supports a singular channel ID or multiple
The channel ID(s) set here will be the text channels the bot listens for commands. To get a channel ID, developer mode must be enabled in your user settings on Discord (under Appearance) then right clicking the target channel and clicking copy ID.
Use Easy Whitelist
use-easy-whitelist: false
Accepts true or false (default: false).
When set to true, the bot uses Easy Whitelist instead of the vanilla whitelist command and file.
Whitelisted Roles Auto Add
whitelisted-role-auto-add: false
Accepts true or false (default: false). Requires limited-whitelist-enabled to be set to true.
Enables the automatic assigning of the set whitelisted-roles when a limited whitelister successfully whitelists.
Whitelisted Roles Auto Remove
whitelisted-role-auto-remove: false
Accepts true or false (default: false). Requires limited-whitelist-enabled to be set to true.
Automatically removes any whitelisted-roles from a Discord user if a user in any of the add-remove-roles removes any of their registered Minecraft usernames through the bot. The bot also removes any whitelisted-roles if any of their linked Minecraft names are removed in-game when add-in-game-adds-and-removes-to-list is enabled.
Limited Whitelist Enabled
limited-whitelist-enabled: true
Accepts true or false (default: true).
Enables the limited-add-roles which allows users under any of these roles to whitelist themselves a limited amount of times. This is highly recommended as it links the users Discord ID to their whitelisted username(s); this allows a lot more features to be enabled.
On Ban Events
use-on-ban-events: false
Accepts true or false (default: false). Requires limited-whitelist-enabled to be set to true.
When enabled, the bot will listen in-game for the /ban command. When the ban command is executed and the target Minecraft username is linked to a Discord ID, the bot will remove any assigned whitelisted-roles and assign any set banned-roles. The bot will also remove any other Minecraft usernames that were whitelisted through the same Discord ID.
Max Whitelist Amount
max-whitelist-amount: 3
Accepts any integer value (default: 3).
Self explanatory; this value sets the max amount a limited whitelister can whitelist (recommended is 1).
Username Validation
username-validation: true
Accepts true or false (default: true).
Performs checks on the specified Minecraft username before attempting to whitelist such as an invalid character check and a invalid length check.
Removed List Enabled
removed-list-enabled: true
Accepts true or false (default: true).
When enabled, this list stores all the Minecraft usernames removed by any user in the add-remove-roles. This avoids other players adding back removed players without permission.
Use Custom Messages
use-custom-messages: false
Accepts true or false (default: false).
This enables the customization of the bots messages. This is useful if you want to change the language of the bot to something other than English. The file used to customize messages is located at: server-root/plugins/DiscordWhitelister/custom-messages.yml.
Supports context specific variables such as {Sender} and {MinecraftUsername} but only in the messages they were originally in. If you try to use any of these variables in messages they were not originally in, they will not be processed.
Use Custom Prefixes
use-custom-prefixes: false
Accepts true or false (default: false).
Allows editing of the prefix for the whitelist add & remove commands.
custom-prefixes.yml:
whitelist-add-prefix: '!whitelist add'
whitelist-remove-prefix: '!whitelist remove'
This file containing these entries is located at: server-root/plugins/DiscordWhitelister/custom-prefixes.yml.
Show Player Skin on Whitelist
show-player-skin-on-whitelist: true
Accepts true or false (default: true).
Determines whether the player's skin will be shown in the whitelist success message.
Show Player Count
show-player-count: true
Accepts true or false (default: true).
Determines whether the player count will be shown as the bots status in Discord.
Show Vanished Players in Player Count
show-vanished-players-in-player-count: false
Accepts true or false (default: false). Requires show-player-count to be enabled.
When enabled, users in-game with any joinvanished permissions (including discordsrv.silentjoin & discordsrv.silentquit) will be added to the player count.
Add In-Game Add and Removes To List
add-in-game-adds-and-removes-to-list: true
Accepts true or false (default: true).
When enabled, the bot listens for vanilla or easy whitelist add/remove commands. When someone is removed they are added to a store called in-game-removed-list.yml. This means users in Discord cannot re-add users that have been removed in-game (not through the bot). When a user is added in-game and is located in either removed lists (removed-list.yml & in-game-removed-list.yml) they will be removed from said lists automatically.
Assign Permissions with Ultra Permissions
assign-perms-with-ultra-perms: false
Accepts true or false (default: false).
Automatically assigns permissions set in server-root/plugins/DiscordWhitelister/on-whitelist-permissions.yml to the target Minecraft username on whitelist success. The bot also automatically removes any assigned permissions when removed from the whitelist either through the bot or in-game, and when banned.
Add desired permissions to the perms-on-whitelist list:
perms-on-whitelist:
- bukkit.command.tps
Use On Whitelist Commands
use-on-whitelist-commands: false
Accepts true or false (default: false).
Runs any amount of commands as either the console or the target Minecraft username when the player is successfully whitelisted. Any command you add to the list supports %PLAYER% which will be replaced with the target Minecraft username when the player is successfully whitelisted.
NOTE: The 'PLAYER' type will only work if the target whitelisted player is in the server at the time of command dispatch. This should only be used in specific situations.
The file to add custom commands is located at: server-root/plugins/DiscordWhitelister/on-whitelist-commands.yml.
Edit on-whitelist-commands to add commands:
on-whitelist-commands:
- CONSOLE:gamemode adventure %PLAYER%
- CONSOLE:say hello testing