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 bot
Section titled “The bot”The role check asks Discord with a bot of your own, a member of your Discord server:
- In Discord’s Developer Portal (discord.com/developers), make a new application - its name is the bot’s.
- Under Bot, Reset Token and copy the token. Keep it private: anyone with it acts as your bot.
- Still under Bot, turn on the Server Members Intent - without it Discord will not tell the bot a member’s roles.
- Under OAuth2, URL Generator: tick
bot, no permissions, open the link and add the bot to your Discord server. - 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.
BasicRP’s whitelist
Section titled “BasicRP’s whitelist”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.
Your own
Section titled “Your own”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)endA 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.
