BeamMP Lua Plugins and Server Moderation: Kick, Ban, Whitelist

Built-in moderation: console commands and AllowGuests

Type help in the server console to see what your version offers. In v3.9.3 the list is:

The settings command gets or sets some server settings at runtime; run settings help on your build for the exact syntax. In ServerConfig.toml, AllowGuests = false is the simplest filter: it requires players to be logged in to a BeamMP account rather than joining as an anonymous guest.

What is not there: no ban, unban, or whitelist command appears in the v3.9.3 console help. If you need a persistent list of banned or allowed players, write it as a plugin.

How BeamMP server plugins are laid out

Server-side Lua lives under Resources/Server. Each subfolder is one plugin. Client-side zips live separately in Resources/Client.

Resources/
  Client/
    examplePlugin.zip
  Server/
    examplePlugin/
      examplePlugin.lua
      further_lua/
        further.lua

• Each plugin folder gets its own Lua 5.3 state, so plugins do not share global variables.
• Lua files directly in the plugin's folder load in alphabetical order. Files in subfolders are ignored unless you load them with require().
• Changing a file in the plugin's main folder reloads that plugin's state. The onFileChanged event (server v3.1.0 and later) fires for changes anywhere under Resources/Server.
• lua PLUGINNAME in the console opens that plugin's state for debugging. Leave it with :exit.

Plugins talk to the server through events. You write a function, then register it by name inside onInit, which runs when the plugin loads:

function onInit()
    MP.RegisterEvent("onPlayerAuth", "onPlayerAuth")
    print("my plugin loaded")
end

Events and functions that matter for moderation

• MP.DropPlayer(player_id, reason) kicks a connected player. The reason is optional.
• MP.SendChatMessage(player_id, message) sends a chat message to one player.
• MP.GetPlayerName(player_id), MP.GetPlayers() and MP.GetPlayerCount() look up who is connected.
• MP.GetPlayerIdentifiers(player_id) returns a table with ip, beammp and, if the player linked Discord to their forum account, discord.
• MP.IsPlayerGuest(player_id) says whether the player joined as a guest.

A player's BeamMP ID can be found by opening forum.beammp.com/u/USERNAME.json and reading the numeric id under user. For bans, key your list on identifiers.beammp rather than the IP, since IP addresses can change and be shared between people.

Example: ban list and whitelist in onPlayerAuth

This plugin denies anyone on a ban list and any guest. The same function can implement a whitelist by inverting the check.

local banned = {
    ["123456"] = true,   -- BeamMP ID of a banned player
}

function onInit()
    MP.RegisterEvent("onPlayerAuth", "onPlayerAuth")
end

function onPlayerAuth(player_name, role, is_guest, identifiers)
    if is_guest then
        return "Please log in with a BeamMP account to join."
    end
    local id = tostring(identifiers.beammp or "")
    if banned[id] then
        return "You are banned from this server."
    end
end

Returning a string from onPlayerAuth denies the join with that reason. Returning nothing lets the player in. For a whitelist, define the table of allowed IDs and return a message when allowed[id] is not true.

The table here is hard-coded, so adding a ban means editing the file, which reloads the plugin automatically. That is fine for a small community. For something bigger, the scripting reference documents FS helpers (create directories, list, copy, rename, remove, existence checks) and Util.JsonEncode / Util.JsonDecode (server v3.1.0 and later); test file persistence on your own version before relying on it.

Example: chat rules and vehicle limits

To intercept chat, return 1 from onChatMessage. The message is then shown to nobody, including the sender, so send the sender a reply first if you want them to know why:

function onInit()
    MP.RegisterEvent("onChatMessage", "onChatMessage")
end

function onChatMessage(player_id, player_name, message)
    if message == "!rules" then
        MP.SendChatMessage(player_id, "1. No ramming. 2. Be kind. 3. Have fun.")
        return 1
    end
end

onVehicleSpawn works the same way: returning 1 stops the vehicle from spawning. The data argument begins with the player ID and vehicle ID followed by JSON describing the vehicle configuration, so you can inspect it before allowing it. For a blunt vehicle cap, MaxCars in ServerConfig.toml needs no code at all.

Debugging plugins and handling player data responsibly

• Watch the console for Lua errors after saving a plugin; a reload happens as soon as the file changes.
• Keep event handlers short. Slow code in onChatMessage or onVehicleSpawn delays everyone. Util.DebugExecutionTime() returns per-handler timing in milliseconds if you suspect a plugin.
• Namespace any custom console commands you add through onConsoleInput, for example with a short prefix, so they do not collide with another plugin's.
• IP addresses and Discord IDs from MP.GetPlayerIdentifiers are personal data. Do not print them to public logs or post them in chat.
• MP.Set changes a setting temporarily. It does not write ServerConfig.toml, so make permanent changes in the file.

Hosting with ChicagoServers? The BeamMP server hosting page lists what is included, such as free server backups and SFTP file access.

Frequently asked questions