docs-2/docs/minecraft/autowhitelist/install.md

title	sidebar_position	outline
Getting started	2	deep

Installing

::: tip Basic JSON or JSON5 knowledge is highly recommended. :::

Installing the mod

Make sure you download the correct version for your server's Minecraft version.

1. Download the mod from Modrinth
2. Download the required dependencies FabricAPI and Fabric Language Kotlin
3. Put the downloaded files in your mods folder
4. Start the server, this will generate the config file at config/autowhitelist.json5

Setting up the Discord bot

The mod requires a Discord bot, you can create a new one or choose an existing one in the Discord developer portal
Make sure it has the Server members intent enabled

1. Visit the Discord developer portal
2. Click New Application
3. Name the application
4. Agree to the developer terms of service
5. Create the application
6. Select Bot on the sidebar
7. Enable the Server members intent
8. Disable Public bot
9. Save the changes

Configuring the mod

Bot token

Copy the bot token from the developer console and add it to the mod config

Never share or publish the bot token!

1. Scroll to the top of the Bot page
2. Click Reset Token
3. Click Yes, do it!
4. Insert your 2FA if required
5. Click Copy
6. Put the token in the mod config

  "lock_time": "1d",
  // Your bot token. Never share it, anyone with it has full control of the bot
  "token": "NEVER SHARE YOUR BOT TOKEN",
  "discord_server_id": 0,
  // When enabled, all interactions and slash commands will be ephemeral, meaning only the user can see the response.
  "ephemeral_replies": true,

Server ID

Copy the Discord server/guild id of the server where you added the bot to

To get the server id you need to enable developer mode on Discord.
On the app go to Settings > App Settings > Advanced and enable Developer Mode.

1. Right-click the server icon
2. Click Copy Server ID

  "lock_time": "1d",
  // Your bot token. Never share it, anyone with it has full control of the bot
  "token": "NEVER SHARE YOUR BOT TOKEN",
  "discord_server_id": 0,
  // When enabled, all interactions and slash commands will be ephemeral, meaning only the user can see the response.
  "ephemeral_replies": true,

Adding the bot to your server

Create the url to add the bot to a server and use it to add it to the server you plan to use it on

1. Select OAuth2 on the sidebar
2. Select bot and applications.commands in Scopes
3. Select Send messages in Bot permission
4. Copy the generated URL
5. Open the URL in your browser
6. Select the Discord server the bot should work on
7. Click Authorize

Configuring the entries

::: tip You can use the entry generator for an easier setup :::

On the config file, entries will be empty by default, there you will configure what the server will do when whitelisting the players.

All of them takes a list of roles that will be used to whitelist the players, and a type that will be used to determine what the server will do when whitelisting the players.

roles takes either the role ID or the role name, prefixed by an @, you can use both ways on the same entry

Any extra keys (if any) go inside the execute object

The format is

{
  // The Discord roles that will be used to whitelist the players
  "roles": ["Discord role id", "@Or the role name"],
  // The method that will be used to whitelist the players
  "type": "namespace:path",
  // Any extra option goes in here, it defines what will be done when the entry runs, for adding/removing to the whitelist
  "execute": {}
}

When a player is moved between entries, for example, due to a role change, the mod will execute the code for removal of the old entry and right after it executes the code for adding into the new entry

For more details on entries view the entries documentation page

:::details Example Let's take this example config:

{
  "roles": ["@Role 1"],
  "type": "autowhitelist:execute_command",
  "execute": {
    "on_add": "say {player} joined the cool team",
    "on_remove": "say {player} is no longer cool"
  }
},
{
  "roles": ["@Role 2"],
  "type": "autowhitelist:execute_command",
  "execute": {
    "on_add": "say {player} is now awesome",
    "on_remove": "say {player} left the awesome team"
  }
}

Once I register while having @Role 1 the server will announce:

[23:31:22] [AutoWhitelist] AwakenedRedstone joined the cool team

Now, I got a new role, @Role 2
The server will follow with:

[23:33:53] [AutoWhitelist] AwakenedRedstone is no longer cool
[23:33:53] [AutoWhitelist] AwakenedRedstone is now awesome

:::