We are your new 5-Star Hosting Company. At least according to ★ Trustpilot

Following along with a BeamMP server? Deploy yours in minutes.

All servers come with a 24-Hour Trial, Free Backups, and 40Gbps DDoS Protection included!

Use code SAVE15 to take 15% OFF Your First Invoice with ChicagoServers! Limited Time!
BeamMP guide

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

By the ChicagoServers team · Updated · 6 min read

BeamMP servers have a small set of built-in moderation tools: a console kick command, guest blocking through AllowGuests, and a server-side Lua API. There is no built-in ban list or whitelist in the v3.9.3 console, so persistent bans and whitelists are done with a Lua plugin in Resources/Server.

This guide explains how plugins are loaded, which events and functions matter for moderation, and gives short working examples. It was checked against the official BeamMP scripting reference and the v3.9.3 server source on 2026-11-01.

Quick answer
  • Each folder in Resources/Server is a plugin with its own Lua 5.3 state. Put your main .lua file in it and register events in onInit.
  • Console commands in v3.9.3: help, exit, kick, list, say, lua, settings, status, clear, version, protectmod, reloadmods. Type them on the Console tab. There is no ban or whitelist command.
  • Block or allow players in the onPlayerAuth event: return a string to deny the join with that message.
  • Cancel chat with onChatMessage and block vehicle spawns with onVehicleSpawn by returning 1.
  • Saving a .lua file in a plugin's main folder (on the Files tab) reloads it within a few seconds, so you can iterate without restarting the whole server.
On this page
  1. Built-in moderation: console commands and AllowGuests
  2. How BeamMP server plugins are laid out
  3. How to add a plugin on a ChicagoServers server
  4. Events and functions that matter for moderation
  5. Example: ban list and whitelist in onPlayerAuth
  6. Example: chat rules and vehicle limits
  7. Debugging plugins and handling player data responsibly
  8. Frequently asked questions

Built-in moderation: console commands and AllowGuests

Type help on the Console tab (then press Send) to see what your version offers. In v3.9.3 the list is:

CommandWhat it does
kickKicks a player by name, with an optional reason: kick NAME REASON.
listLists connected players with their IDs and car counts.
saySends a chat message to all players.
statusShows player and vehicle counts, uptime and subsystem health.
luaSwitches the console into Lua mode, optionally for one plugin's state.
reloadmodsReloads everything in Resources/Client.
protectmodMarks a client mod as protected so the server does not distribute it.
version, clear, help, exitServer version, clear the console, show help, shut down.

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

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.

Plugin layout from the BeamMP docs
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 .lua file in the plugin's main folder reloads that plugin. Changes to other file types or to files in subfolders do not reload it. The onFileChanged event (server v3.1.0 and later) fires for changes anywhere under Resources/Server.
  • lua PLUGINNAME on the Console tab 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:

Resources/Server/myplugin/main.lua
function onInit()
    MP.RegisterEvent("onPlayerAuth", "onPlayerAuth")
    print("my plugin loaded")
end

How to add a plugin on a ChicagoServers server

Plugins are plain files, so you add them with the file manager.

  1. Open the Server folder

    Open your server in the panel, then the Files tab, and go to Resources/Server.

  2. Create the plugin folder

    Click New to make a folder named after your plugin and open it.

  3. Add the Lua file

    Click Upload (or drag the file onto the page), or use New to make a file and edit it in the editor, then Save (or Ctrl+S).

  4. Restart once

    Click Restart at the top of the page. Files added after startup are not tracked, so a new plugin needs a restart.

  5. Check the console

    Open the Console tab and look for Lua errors or your plugin's startup message.

After that, saving a change to a .lua file in the plugin's main folder reloads the plugin without a restart.

Events and functions that matter for moderation

EventWhen it firesCancel or deny
onPlayerAuthA player tries to join. Arguments: name, role, is_guest, identifiers.Return 1 to deny, or a string to deny with that reason
onPlayerJoiningA player is joining.No
onPlayerDisconnectA player left.No
onChatMessageA player sends chat. Arguments: player_id, player_name, message.Return 1 to drop the message
onVehicleSpawnA player spawns a vehicle. Arguments: player_id, vehicle_id, data.Return 1 to block the spawn
onConsoleInputText typed into the server console.No
  • 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.

Resources/Server/access/access.lua
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 on the Files tab and saving it, 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:

Resources/Server/rules/rules.lua
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 tab 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 on the Configs tab, or in the Startup field where the setting has one.

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

Frequently asked questions

Does BeamMP have a built-in ban command?

Not in the v3.9.3 server console. The console help lists help, exit, kick, list, say, lua, settings, status, clear, version, protectmod and reloadmods. For persistent bans, use a Lua plugin that denies players in the onPlayerAuth event.

How do I kick a player on a BeamMP server?

Type kick followed by the player's name and an optional reason on the <strong>Console</strong> tab and press <strong>Send</strong>. From a plugin, call MP.DropPlayer with the player's ID and an optional reason.

How do I whitelist players on a BeamMP server?

Write a small plugin that registers onPlayerAuth, checks the player's BeamMP ID in identifiers.beammp against a list, and returns a message string to deny anyone who is not on it.

Do I need to restart the server to apply Lua changes?

Not for edits. Changing a Lua file in a plugin's main folder reloads that plugin's state. Files added after startup are not tracked as of server v3.1.0, so click <strong>Restart</strong> after adding a new plugin.

We are your new 5-Star Hosting Company. At least according to ★ Trustpilot

Following along with a BeamMP server? Deploy yours in minutes.

All servers come with a 24-Hour Trial, Free Backups, and 40Gbps DDoS Protection included!

We offer quality support, a detailed knowledgebase, video tutorials on most topics, and even live support in case you prefer a live human.

Use code SAVE15 to take 15% OFF Your First Invoice with ChicagoServers! Limited Time!