Skip to content

A Discord role whitelist

A role-play server often lets in only the people its staff have accepted: they join the server’s Discord, pass whatever the server asks, and get a role - “Whitelisted”. With KCD:MP the game server can check that role itself, at every join: a member with the role gets in, anyone else reads why in their launcher, before their game even starts.

How a player’s Discord account reaches your server

Section titled “How a player’s Discord account reaches your server”

A player signs in with Discord once, in the KCD:MP launcher’s Options (again after a month). KCD:MP asks Discord whose account it is - so a player cannot claim someone else’s - and from then on the player’s game proves that account to each server that asks for it, and to that server alone: a server that receives it cannot use it to join another one. Your game mode never sees a password or a Discord token, only the account’s id (GetPlayerDiscordId).

Only servers that ask get it: the game mode calls UseDiscordIdentity. A player who has not signed in is offered the sign-in when they pick such a server in the launcher.

Your server must know the address players dial. A server on the public list knows it already. A server that is not on the list, or that players reach through a forwarding or protection service, sets [master] public_address in server.toml to the address players use (the name or the IP and the port) - otherwise their accounts are refused, and the server log says so.

The role check asks Discord with a bot of your own, a member of your Discord server:

  1. In Discord’s Developer Portal (discord.com/developers), make a new application - its name is the bot’s.
  2. Under Bot, Reset Token and copy the token. Keep it private: anyone with it acts as your bot.
  3. Still under Bot, turn on the Server Members Intent - without it Discord will not tell the bot a member’s roles.
  4. Under OAuth2, URL Generator: tick bot, no permissions, open the link and add the bot to your Discord server.
  5. In Discord’s settings, Advanced, turn on Developer Mode. Then right-click your server’s icon for Copy Server ID, and in Server Settings, Roles, right-click the role for Copy Role ID.

The shipped BasicRP mode has a whitelist, off as it ships. Near the top of its script is a DISCORD_WHITELIST table:

local DISCORD_WHITELIST = {
enabled = true,
bot_token = "your bot's token",
guild = "111111111111111111", -- your Discord server's id
roles = { "222222222222222222" }, -- any one of these lets a member in
always_allow = { "333333333333333333" },-- Discord ids let in whatever Discord says: you and your admins
grace_hours = 12, -- while Discord is down, a member let in this recently gets in again
messages = { ... }, -- what a refused player reads
}

Set it, restart the server (or /reload), and the server log says the Discord whitelist is on. Every join then gets a line: who was let in or turned away, and why. A member’s answer is kept for a minute, so a join asks Discord once.

The pieces, in any mode:

UseDiscordIdentity asks joining players for their Discord account
OnPlayerJoinRequest asked about every join before the player is anyone on the server - first by their launcher, then by their game; answer at once or later
AnswerPlayerJoin the later answer: in, or out with a message, within 15 seconds
GetDiscordMemberRoles a member’s roles, asked with your bot
GetPlayerDiscordId the account of a player who joined, for your own records
local GUILD, ROLE, TOKEN = "111111111111111111", "222222222222222222", "your bot's token"
function OnGameModeInit()
UseDiscordIdentity(true)
end
function OnPlayerJoinRequest(ask, join)
if not join.discord then
return false, "Sign in with Discord in the KCD:MP launcher's Options, then join again."
end
GetDiscordMemberRoles(GUILD, join.discord, TOKEN, function(roles, problem)
if not roles then
AnswerPlayerJoin(ask, false, problem == "not a member" and "Join our Discord first." or "Your roles could not be checked - try again.")
return
end
for _, role in ipairs(roles) do
if role == ROLE then AnswerPlayerJoin(ask, true) return end
end
AnswerPlayerJoin(ask, false, "You do not have the Whitelisted role in our Discord.")
end)
end

A check that cannot finish - Discord does not answer, the callback has an error, 15 seconds pass - refuses the join: a whitelist stays shut when it cannot check. Keep the bot’s token out of anything players can read, such as the mode’s client scripts or web pages.