How to Add Mods to a BeamMP Server (Cars, Maps and Plugins)

To add mods to a BeamMP server, upload the mod .zip files, unextracted, into Resources/Client. Players download everything in that folder automatically when they join. For a modded map, also set Map in ServerConfig.toml to /levels/<folder>/info.json, using the folder name inside the zip's levels folder, not the zip's file name. Server plugins go in their own folder in Resources/Server, with a main.lua. Restart after every change.

What you are working with

BeamMP sends the client mods to players when they connect, and runs the server plugins itself. Stock BeamNG.drive content needs nothing at all, because every player already has it.

What works and what does not

Where your mods are on your PC

BeamNG.drive keeps downloaded mods in the mods folder of its user folder, with mods installed from the in game repository in mods/repo. The location changes between BeamNG versions, so the reliable way to find it is the user folder option in the BeamNG.drive launcher. Copy the zips from there to the server.

Step 1: Back up and stop the server

Stop the server so nothing loads half uploaded files, and take a backup if you are swapping a lot of mods.

Step 2: Upload the zips to Resources/Client

Put each mod zip straight into Resources/Client. Do not extract them, and do not put them in subfolders. The BeamMP server guide is clear that zips stay zipped.

Check each zip before uploading: opening it should show folders such as vehicles, levels or art at the top. If you see another zip, or one extra folder wrapping everything, you have a download archive around the real mod. Upload the inner mod zip instead.

Step 3: Set the map for a modded map

This is the step almost everyone gets wrong. The Map value comes from the folder inside the zip, not from the zip's name:

1. Open the map's zip on your PC.
2. Open the levels folder inside. The folder there, for example myawesomedriftmap2021, is the map name.
3. Set the map path to it:

[General]
Map = "/levels/myawesomedriftmap2021/info.json"

On GamezServers, put the same path in the Map setting in the panel. A zip called Awesome_Drift_Map_v3.zip often holds a folder with a completely different name, and a wrong name leaves players loading into an empty void.

Step 4: Add Lua plugins to Resources/Server

Each plugin gets its own folder with a main.lua:

Resources/
  Server/
    CobaltEssentials/
      main.lua
    MyRaceMode/
      main.lua

The server scripting guide explains that Lua files in a plugin's top folder load on startup in alphabetical order, and files in subfolders are only loaded if the plugin requires them. A main.lua dropped loose into Resources/Server is not a plugin. Follow each plugin's own install notes for its config files.

Step 5: Restart and join

Start the server and watch the console for Lua errors. Join from the BeamMP launcher: you should see the mods downloading before the map loads.

The gotcha: everyone downloads everything

Every zip in Resources/Client goes to every player who joins, whether it is used or not. Five map mods in the folder means every player downloads five maps, even though the server only runs one. A bloated folder makes first joins take ages and can make slow connections give up.

Keep only what the current session uses. Store spare maps and car packs somewhere else (a folder outside Resources, or your PC) and swap them in when you change the map.

Common problems

• Players load into an empty grey void: the Map path does not match the folder name inside the zip, or the map zip is missing from Resources/Client.
• Joining stops at "done" or "start": an incompatible or broken mod, which the BeamMP docs call out. Remove mods one at a time to find it.
• Mod car is not in the vehicle list: the zip is nested inside another zip or folder, or it was extracted.
• Joins take forever: too many or too large zips in Resources/Client. Trim it.
• Plugin does nothing: it is not in its own folder, or main.lua is in a subfolder. Check the console for Lua errors.
• Lag and teleporting after adding cars: each car runs on every player's PC. Lower Max Cars per player instead of adding RAM.

Mods on GamezServers

On a BeamMP server from GamezServers, the map, max cars and server key are panel settings, and the mod zips go into Resources/Client through the file manager or the SFTP login in Settings. The file manager can also download a mod from a link straight to the server, so big map files never touch your upload. Click Backup before a big mod swap, and the server stays up whether or not your PC is on. For the auth key and ports, see how to host a BeamMP server.

FAQ

Do players need to download mods to join a BeamMP server?

Not by hand. Everything in Resources/Client downloads automatically when they connect through the BeamMP launcher.

Should I unzip mods for a BeamMP server?

No. Upload the zip as it is into Resources/Client. Unzipped folders do not load.

How do I find the map name for a modded map?

Open the zip, open the levels folder, and use the folder name you find there in /levels/<name>/info.json.

Where do BeamMP server plugins go?

In Resources/Server, each in its own folder with a main.lua at the top of that folder.