How to add mods to a BeamMP server

The two folders

A BeamMP server keeps everything it hands out in one place, the Resources folder next to the server executable. It has two subfolders, and which one a mod belongs in is the first thing to get right.

Resources/Client

Content players need on their own PC: vehicles, parts, skins, sounds, custom maps and UI mods. Each mod is one .zip file placed directly in this folder. When someone joins, the launcher downloads every zip here that it does not already have. BeamMP's own documentation warns that any other kind of file in this folder causes an error on start-up, so no extracted folders, readme files or screenshots.

Resources/Server

Lua plugins that run on the server itself: game modes, admin tools, race systems, chat commands. Each plugin lives in its own subfolder with at least one .lua file, and the server loads them in alphabetical order. Players never download these. Well known examples you will see in server tags are BeamJoy, BeamPaint and CEI.

Check the mod's description if you are unsure. A vehicle or map is always a client mod. A plugin that adds commands or a game mode is a server resource, and some larger projects ship both parts, a Lua folder for the server and a zip for the clients.

1. Find a mod

The BeamNG.drive repository

beamng.com/resources is the official mod repository and the first place to look. Vehicles and maps from here are what most BeamMP servers run. Download the .zip and leave it zipped.

The BeamMP forum and Discord

Server-side resources and multiplayer-specific mods tend to be published on the BeamMP forum and in the resources channels of the BeamMP Discord. This is where you find the Lua plugins.

What to avoid

Mods behind unknown paywalls, mods that have not been updated for a couple of game versions, and anything pirated. A stale vehicle mod is the most common cause of players being unable to join after a BeamNG.drive update.

2. Install it on the server

1. Stop the server

   The folder is read at start-up. On a hosted server, press Stop in the control panel; at home, close the server window or stop the service.

2. Open Resources/Client

   With the panel file manager, SFTP, or Explorer on your own machine. Hosted panels put a Files section in the sidebar; our panel also supports drag and drop in the browser.

3. Upload the .zip, as it is

   Drop the file directly into Resources/Client. Not extracted, not inside a subfolder you made for tidiness. For files over a gigabyte, use SFTP rather than the browser uploader; browser uploads of that size tend to time out.

4. Server-side plugins go in Resources/Server

   Create a folder named after the plugin inside Resources/Server and put its .lua files in there. One folder per plugin.

5. Start the server and check the log

   Start it and watch the console. A line such as [INFO] Loaded 4 Mods confirms the server found them. An error at start-up usually means a stray non-zip file in Resources/Client.

That is the whole install. The next player to join sees the download progress in the launcher, then finds the new vehicles in the vehicle selector.

3. Maps need one more line

A custom map is a client mod like any other: its .zip goes in Resources/Client. The difference is that the server has to be told to load it. Look inside the zip for the folder under levels, note its exact name, and set the map line in ServerConfig.toml or in your panel's Map field:

Map = "/levels/NAME/info.json"

Keep the /levels/ prefix and the /info.json suffix. If the map still will not load, install it in singleplayer, enter the map, open the console with the tilde key and run print(getMissionFilename()) to get the name the game actually uses. Vanilla maps need no upload at all: just set the name, for example west_coast_usa or gridmap_v2. Every map with its code and size is in our BeamMP map names guide.

How big is too big

There is no mod limit in BeamMP. What limits you is the first join: a new player downloads your entire Resources/Client folder before they can drive, and every vehicle on the server is then simulated on every player's PC. The figures hosting companies converge on are rules of thumb rather than anything BeamMP enforces, but they match what players put up with.

One vehicle mod

Roughly 100 to 200 MB for a well made car. Much larger than that and it is usually carrying uncompressed textures that hurt frame rates as well as downloads.

The whole pack

Under about 100 MB is comfortable on any connection. Around 500 MB and people on ordinary home broadband start giving up at the loading screen.

Mod count

If you find yourself past twenty vehicle mods, curate. Five to ten cars that fit the server's theme beat a folder of everything you ever downloaded.

The server itself

Each mod costs RAM on the server, and complex physics mods cost CPU for every player using them. A hosted plan sized by slots already accounts for a normal pack.

Updating, removing and ordering mods

Update a mod

Stop the server, replace the .zip in Resources/Client with the new version, start. Players fetch the new file on their next join.

Remove a mod

Stop, delete the .zip (or the plugin folder in Resources/Server), start. Vehicles already spawned from it disappear for players when they reconnect.

Load order

If two mods must load in a particular order, rename the files with prefixes such as 001_ and 002_. Zips are read alphabetically.

Keep a list

Name, source, version, date added. When a BeamNG.drive update breaks the lobby, that list is how you find the stale mod in minutes rather than an evening.

Back up first

Copy Resources before a big change. On our servers an automatic backup runs on a schedule and you can take one manually before you start uploading, then roll back with one click if the new pack misbehaves.

Protected mods

If you run paid or restricted content you are not allowed to redistribute, run protectmod <file.zip> true in the server console. The server then checks players have the file without sending it; they obtain it from the creator and place it in their own launcher resources folder.

When a mod breaks the server

Players stuck on "done" or "start"

The classic symptom of a broken or incompatible mod. Remove the mod you added last and restart. If several went in at once, move them all out, confirm people can join, then add them back one at a time.

Worked until the game updated

BeamNG.drive updates change vehicle and map formats from time to time, and mods need updating to match. Check the mod's page for a new version before blaming the server.

Two mods fighting

Two maps editing the same terrain files, or two vehicle mods overriding the same base vehicle, conflict silently. Remove one.

Only one player has problems

It is their local mods. Have them disable everything except multiplayerbeammp and rejoin.

Server will not start after an upload

Something that is not a .zip is sitting in Resources/Client, often an extracted folder or a text file. Remove it.

For players: using mods on a BeamMP server

Half of the people searching for BeamMP mods are not running a server at all. They want to know how to use mods in multiplayer, why their own mods vanished, and how to keep a car they liked on someone else's server. The answers are short.

You install nothing

The server decides which mods are in use. When you join, the launcher downloads them and they are active for that session. There is no mod to enable and no file to place.

Your own mods are switched off on purpose

BeamMP disables your singleplayer mods in multiplayer so everyone in the lobby runs the same content and cars stay in sync. Keep multiplayerbeammp as the only enabled mod; if your game freezes or shows a black screen on join, a local mod is the usual cause. The old Steam Workshop guide on forcing local mods on has been taken down, and the console tricks that replaced it desync other players.

Where downloaded mods are stored

In a Resources folder inside the BeamMP-Launcher installation folder on your PC. That cache is why a second join to the same server is instant. Delete the folder to clear it and free space; mods download again next time.

Keeping a server mod for singleplayer

Copy the mod's .zip from the launcher's Resources folder into the mods folder of your BeamNG.drive user folder, then enable it in the in-game mod manager. This works for freely published mods from the repository. Protected or paid mods are not handed to you as a file, and redistributing them is not yours to do.

Downloads are slow

The first join fetches the whole pack. A lean server on a fast uplink is the owner's side of that; on your side, let the first download finish rather than cancelling and retrying, which starts it again.

If you want a particular mod on a server you play on, ask the owner. Adding it is the five steps at the top of this page, and on a hosted server it takes about a minute.