BeamMP server guide: setup, config, maps and mods

A BeamMP server is a small standalone program, not a copy of BeamNG.drive. It relays vehicle state between clients, hands out mods when people join, and runs Lua plugins. It does not simulate a single wheel. That one fact explains most of what follows: the server is cheap on CPU and memory, expensive on bandwidth, and the thing that actually limits your player count is what your players' PCs can simulate, not what you rent.

You need three things to start: the server binary, one port (30814 by default, on both TCP and UDP), and an auth key from the BeamMP Keymaster. The key is not optional and it is not something a host can give you - it is tied to your own BeamMP account. Everything else is a single ServerConfig.toml.

What BeamMP is and what the server does#

BeamNG.drive has no official multiplayer. BeamMP is the community project that adds it: a client-side mod and launcher for the players, and this server for everyone to meet on.

The architecture is worth internalising before you size anything or blame the host for lag:

• Every client simulates its own vehicle authoritatively. Your physics run on your machine.
• Other people's vehicles are simulated locally too, corrected by state updates arriving through the server. That is why a remote car that loses packets will jitter, snap or drive through a wall on your screen and look fine on theirs.
• The server holds no physics state. It authenticates players, tracks who owns which vehicle, relays updates and runs your Lua.

The consequences are immediate. A ten-player server with four cars each means forty vehicles being simulated on every player's PC, so MaxCars is a client performance setting that happens to be configured on the server. And a player complaining about "server lag" is usually describing packet loss or their own CPU, not a saturated host. Latency, jitter and packet loss is the right vocabulary for that conversation.

Requirements and resource usage#

By game server standards this one is tiny. The work it does is copying packets and, on join, pushing mod archives.

• CPU: low and mostly single-threaded. If your server is pinned at 100% with ten players, look at a Lua plugin doing something silly on every frame before you look at the plan.
• Disk: the server itself is a few tens of megabytes. Your Resources/Client folder is what grows - a serious mod pack is easily several gigabytes, and every one of those bytes is sent to every joining player.
• Bandwidth: this is the one to think about. Vehicle state for every car goes to every client, so traffic scales with players multiplied by cars, and mod downloads land in bursts whenever somebody joins. Expect noticeably more upstream than a Minecraft or Valheim server with the same head count. Unmetered is not the same as unlimited; bandwidth and fair use explains the difference.

The practical advice is to cap MaxCars at 2 or 3 for a public server and raise it only for a group you know has the hardware. Nothing else you configure will affect how the server feels as much.

Getting an auth key#

Every BeamMP server needs an auth key, including a private one. The key identifies the server to the BeamMP backend, which is what authenticates joining players. Without it the server refuses to start.

1. Go to the BeamMP Keymaster at keymaster.beammp.com and sign in with Discord.
2. Create a key, give it a name you will recognise later, and copy the string.
3. Paste it into AuthKey in ServerConfig.toml.

The key belongs to your account, not to your hosting provider. Nobody can issue one on your behalf, and you should treat it like a password: one key per server, never pasted into a public channel, regenerated if it leaks. The same reasoning applies to any credential a server holds - see environment variables and secrets.

On RE:NODE this is one of the games that needs a credential of your own. The server is created as soon as payment clears, and the install waits on the Setup tab until you paste the key in, which is also where you go if you ever need to replace it.

Installing and first start#

Download the server build for your platform from the BeamMP project, put it in its own directory, and run it once. It writes a default ServerConfig.toml beside itself, prints a complaint about the missing auth key and exits. That is expected - fill the key in and start it again.

BeamMP-ServerServerConfig.tomlResources/  Client/  Server/

On a panel-based host the binary and the folder layout are already there; you edit ServerConfig.toml in the browser and drop mods into Resources/Client over SFTP or the file manager. SFTP and the file manager has the connection details, and it is the sane way to upload a multi-gigabyte mod pack.

Keep the server version current. BeamMP updates alongside BeamNG releases, and a server running an older protocol is rejected by updated clients - the same trap every modded game has. What to do when a mod update breaks is the general habit worth having: know your working version, keep a copy of the config, and do not update on a night you have people waiting.

There is no world state to lose here, which makes backups unusually simple and unusually easy to neglect. What is worth keeping is ServerConfig.toml, everything under Resources/Server and the list of what is in Resources/Client. The config is five minutes of work to rebuild; a set of Lua plugins tuned over a year is not, and neither is the exact combination of mod versions that currently works together. Take a backup before every mod change and before every server update, and keep it somewhere that is not the server - backups that actually restore makes the case better than a bullet point can.

ServerConfig.toml line by line#

The file is TOML, so strings need quotes and booleans do not. A syntax error stops the server rather than being ignored, which is a kindness.

[General]Port = 30814AuthKey = "paste-your-keymaster-key-here"Name = "Sunday Night Cruise"Description = "Slow driving. No ramming. Italy."Tags = "Freeroam,Cruise,Europe"Map = "/levels/italy/info.json"MaxPlayers = 10MaxCars = 2Private = falseAllowGuests = falseLogChat = trueDebug = falseIP = "::"InformationPacket = trueResourceFolder = "Resources"

Recent server versions add sections beyond [General], typically a [Misc] block with update-reminder switches such as ImScaredOfUpdates and UpdateReminderTime, and an HTTP block for the optional built-in web endpoint. The file the server generates is the authority for which of those your build has; anything it did not write, your build probably does not read.

Maps and client mods#

The Map value is a path into the level structure, not a friendly name. The default is /levels/gridmap_v2/info.json, and the official levels use these folder names:

Mods work by upload, not by workshop. Drop a mod's .zip straight into Resources/Client and it is sent to every player as they join, then loaded automatically. Vehicles need nothing else. A map mod needs the zip in the same place plus the Map line changed to point at the level folder inside that zip - open the archive and look at the folder name under levels/, because it rarely matches the name on the download page.

Three things go wrong here, predictably:

• The map path is wrong, so the server starts on the default level or fails to load one. Read the zip, do not guess.
• The mod pack is enormous, so first-time joiners sit through a several-minute download and half of them give up. Keep the pack as small as the server concept allows, and say the size in your Discord.
• A mod is incompatible with the current game version. BeamNG updates break vehicle mods regularly. When a patch lands, the fastest diagnosis is to move the mod folder aside and start clean.

Server-side Lua plugins go in Resources/Server, and they are never sent to clients.

Lua plugins#

A plugin is a folder under Resources/Server containing main.lua. The server loads it at start, and you hook the events you care about:

local function onInit()    print("Welcome plugin loaded")    MP.RegisterEvent("onPlayerJoin", "greet")    MP.RegisterEvent("onChatMessage", "filter")endfunction greet(playerID)    local name = MP.GetPlayerName(playerID)    MP.SendChatMessage(-1, name .. " joined. Rules are in the Discord.")endfunction filter(playerID, name, message)    if string.find(message, "badword") then        MP.SendChatMessage(playerID, "That word is not welcome here.")        return 1    endendonInit()

The events you will use most are onInit, onPlayerAuth, onPlayerConnecting, onPlayerJoining, onPlayerJoin, onPlayerDisconnect, onChatMessage, onVehicleSpawn, onVehicleEdited and onVehicleDeleted. Returning 1 from a cancellable handler such as onChatMessage or onVehicleSpawn blocks the action. The functions you will reach for are MP.SendChatMessage (with -1 for everyone), MP.DropPlayer, MP.GetPlayerName, MP.GetPlayers, MP.GetPlayerIdentifiers and MP.CreateEventTimer for anything periodic.

Signatures have changed between major server versions, so check the plugin you downloaded against the documentation for the version you are running rather than assuming a three-year-old script still works. This is also where whitelists, vehicle blacklists, anti-ram rules and Discord bridges come from - BeamMP has no built-in admin system worth the name, and every well-run server is well-run because somebody wrote or installed the Lua.

Access control hangs off onPlayerAuth, which fires before a player is admitted and receives their identifiers - the account name and the numeric BeamMP identifier the backend vouched for. A whitelist is a table of those identifiers checked in that handler, with MP.DropPlayer for anybody not in it. The reason to key on the identifier rather than the display name is the obvious one: names are changeable and identifiers are not. Log both when somebody misbehaves, because by the time you come to ban them the name in your screenshot may belong to nobody.

Be conservative about what you install. A server-side plugin runs with the server's privileges and sees every chat message and every connection, so a plugin from an anonymous forum post deserves a read before it is dropped into a folder that loads automatically at start. The same instinct applies to the client mods you push to other people's machines; keeping a modded server clean is about exactly this kind of hygiene.

Keep plugins in version control or at least keep copies off the server. They are the part of the setup you cannot re-download.

Ports, joining and firewalls#

One port number, both protocols, both directions. Opening only TCP gives the classic symptom: players connect, see the map load, and then nobody moves - because the state stream never arrives. Game server ports explained covers why games split traffic like this.

Players find the server in the in-game BeamMP list when Private = false, or connect directly by address and port. Direct connection works regardless of the list, which makes it the right test when you are not sure whether your server is broken or merely unlisted. If you would rather hand out a name than an address, an A record works fine - connecting a domain to a game server has the details, and BeamMP does not need any SRV trickery.

Troubleshooting#

The server exits immediately on start. Almost always the auth key: missing, mistyped, or still the placeholder. The log line says so, but it scrolls past quickly.

The server is running and not in the list. Check Private, then check that the machine can reach the BeamMP backend outbound, then wait a couple of minutes. Test with a direct connect meanwhile.

Players connect, then time out at "loading". Usually the mod transfer. A large Resources/Client over a slow uplink will hit a client-side timeout. Trim the pack or accept that first joins are slow.

Everyone stutters near each other. Too many cars. Drop MaxCars, then MaxPlayers. Remember the simulation happens on their PCs, so this is a client cost you are managing from the server.

One player is unplayable and everyone else is fine. That player's connection, or their CPU. Have them check packet loss to the server address before you change anything centrally.

Version mismatch on join. The server build is older than the client mod. Update the server. This happens after every BeamNG release, so plan for it rather than being surprised.

Lua plugin does nothing. Check that the function names you passed to MP.RegisterEvent are global, that main.lua is inside its own folder under Resources/Server, and that the server log has no syntax error from load time.

FAQ#

Do I need BeamNG.drive installed on the server?

No. The BeamMP server is a standalone program that relays state and serves mods. Only the players need the game, plus the BeamMP client mod.

Can a host give me an auth key?

No. The key comes from the BeamMP Keymaster and is tied to your own BeamMP account. Any host will ask you to paste yours in, because there is no legitimate way for them to generate one for you.

How many players can a BeamMP server take?

Ten is a comfortable default and busy public servers run more, but the real limit is client performance: every player simulates every vehicle present. Lowering MaxCars raises the practical player ceiling far more than a bigger plan does.

Where do I put vehicle and map mods?

In Resources/Client as .zip files. They are pushed to players on join. For a map mod you also have to set Map to the level folder inside the archive, which often differs from the file name.

Does BeamMP support passwords?

Not as a config option. Private = true only removes the server from the public list. Real access control means a Lua plugin that checks player identifiers when they authenticate.

Why do other cars jitter or teleport?

Because remote vehicles are simulated locally and corrected from network updates. Packet loss between a player and the server shows up as exactly that, and it is a connection problem rather than a host capacity problem.