Adding mods to a BeamMP server is one folder and one line. Every vehicle or map mod goes into Resources/Client as the original .zip, unopened, and the server sends it to each player as they join. A custom map additionally needs the Map key in ServerConfig.toml pointed at that map's info.json, written as /levels/<folder>/info.json, where <folder> is the folder name inside the zip, not the name on the download page. Restart, and you are done.
The part nobody warns you about is the cost. Every byte in Resources/Client is downloaded by every player who does not already have it, through your server's upstream, before they can drive. A 3 GB pack is a five-minute wait for a first-time joiner on a good connection and a lost player on a bad one. This guide is about doing the simple part correctly and keeping the expensive part under control: the zip rules, the map path, how pack size turns into join time and traffic, how to keep a pack consistent across updates, and how to find and remove the mod that broke everything.
If the server itself is not running yet, start with the BeamMP server guide, which covers the auth key, the rest of ServerConfig.toml, ports and Lua basics.
How BeamMP distributes mods#
BeamMP has no workshop integration and no mod manager on the server. The model is deliberately blunt: the server owns a folder of zips, and a client that joins must end up with exactly those zips loaded.
On join, the server tells the client which files it serves. The launcher compares that list against what it already holds and downloads whatever is missing or different over the TCP side of port 30814. Only when every file has arrived does the game load the level and drop the player in. A returning player who already has an identical copy downloads nothing, which is why the first join is slow and later ones are not - and why changing a file, even slightly, puts every player back on the slow path.
Two consequences follow from this design:
- There is no partial pack. A player cannot skip a mod they do not want. If it is in
Resources/Client, it is a mandatory download for everyone. - Server-side and client-side are separate worlds.
Resources/Clientis content for players.Resources/Serverholds Lua plugins, which are never sent to anyone. A mod zip dropped intoResources/Serverdoes nothing, and a Lua plugin dropped intoResources/Clientis shipped to every player as a useless download. The BeamMP Lua plugins guide covers the server side.
The zip rules for Resources/Client#
BeamNG.drive mods are zip archives with the game's own folder layout at their root. A vehicle mod looks like vehicles/<model>/..., a map looks like levels/<mapname>/..., and some mods carry ui/, art/ or lua/ folders beside them. BeamMP sends these archives as they are, so the rules are the game's rules plus one of its own.
| Rule | Why it matters |
|---|---|
Keep the .zip packed | The server sends archives, not folders |
| Layout at the zip root | vehicles/ or levels/ must be top level |
| No zip inside a zip | The game will not look inside it |
| One copy of each mod | Two versions fight over the same paths |
| Plain file names | Spaces and odd characters cause grief |
The first rule catches people on every host with a web file manager. Upload a mod, see an archive, click "unpack" out of habit, and you now have a folder that the server does not send and a player base that cannot see the car. If you unpacked something by accident, delete the folder and upload the zip again.
The second rule catches people who download from forums. A mod shared as CoolCar_v2.zip sometimes contains a folder CoolCar_v2/ with the real vehicles/ folder one level down, or contains CoolCar.zip itself because somebody zipped the zip. Neither loads. Open the archive before uploading it: the first thing you see inside must be vehicles, levels or another of the game's top-level folders. If it is not, repack it so it is. On Linux the fix looks like this:
$ mkdir fix && cd fix$ unzip ../CoolCar_v2.zip$ lsCoolCar_v2$ cd CoolCar_v2 && zip -r ../../coolcar.zip . && cd ../..$ unzip -l coolcar.zip | headThe last command lists the repacked archive; the paths it prints should start with vehicles/.
Vehicle mods need nothing else. Once the zip is in Resources/Client and the server has restarted, the car appears in the vehicle selector for everyone who joined after the restart. If you want to stop people spawning a particular model, that is a Lua job at onVehicleSpawn, not something the mod folder can express.
Custom maps and the Map path#
The Map key is a path into the game's virtual file system, pointing at the level's info.json. For a stock level that is the folder name from the base game:
[General]Map = "/levels/west_coast_usa/info.json"A modded map works the same way. The zip goes into Resources/Client, and the path names the folder under levels/ inside that zip. The steps, in order:
- Upload the map zip to
Resources/Client. - List the archive's contents and find the line ending in
info.jsonunderlevels/. - Copy that folder name exactly, including case, into
Map. - Restart the server and join it yourself before telling anyone.
$ unzip -l Resources/Client/some_map_v3.zip | grep info.json 812 2026-08-02 14:10 levels/somemap/info.jsonThat output gives you Map = "/levels/somemap/info.json". Note how little the folder name has to do with the zip name: some_map_v3.zip contains somemap. Guessing from the download page is how most "my map does not load" posts start.
Three details trip people up:
- The leading slash and the `info.json` belong in the value.
levels/somemap,/levels/somemap/andsomemapare all wrong. Copy the format of the default line and change only the folder. - Case matters. BeamMP servers usually run on Linux, where
SomeMapandsomemapare different folders. Use exactly what the archive says. - Only one map per server. Every player is on the level named in
Map. Changing it means editing the file and restarting, which drops everyone. Servers that rotate maps do it on a schedule with a restart, or run a second server.
Some maps depend on a separate content pack - shared assets that several maps from the same author use, published as their own zip. The map's page usually says so. If a map loads with missing textures, purple surfaces or absent buildings, a dependency is missing; it goes into Resources/Client beside the map.
When the path is wrong, what happens depends on the version: some builds fall back to a default level, others leave clients stuck on a loading screen. Either way, the fix is the same: list the zip again and compare character by character. When a map is too new or too old for the players' game version, it typically loads partly or throws errors in the game's own log; that is a version problem, not a path problem, and moving the zip aside proves it.
Mod size, join time and what players tolerate#
Join time is arithmetic. The first-time download is the size of everything in Resources/Client divided by the slower of two numbers: what your server can push to that player, and what their connection can take in. Players joining at the same moment share the server's upstream between them.
| Pack size | At 50 Mbit/s | At 10 Mbit/s |
|---|---|---|
| 300 MB | about 50 seconds | about 4 minutes |
| 1 GB | about 3 minutes | about 14 minutes |
| 3 GB | about 8 minutes | about 40 minutes |
Those are ideal figures for one player with the line to themselves; real downloads run slower. The numbers make the trade-off concrete. A 300 MB pack is invisible. A 1 GB pack is fine for a regular group who download it once. A 3 GB pack on a public server means that most people who click your name in the server list are gone before it finishes, and some of them will try again later and start from scratch.
What makes a pack large is usually not what server owners expect. A single detailed vehicle mod is commonly tens to a few hundred megabytes, and maps are the heavy items - a large custom map can be well over a gigabyte on its own. Sizes vary a great deal between authors, so check the zips rather than trusting a rule of thumb:
$ du -h Resources/Client/*.zip | sort -h$ du -sh Resources/ClientRun that before and after every change. The list sorted by size tells you where the weight is, and it is very often one map and two enormous car packs that between them account for most of the total.
Practical limits that work:
- Public servers: keep the total under about 1 GB and say the size in the server description or
Descriptiontext, so people know what they are agreeing to. - Private groups: size matters less, because each person downloads once. Tell people to join the evening before an event to get the download out of the way.
- Event servers: one map, the event cars, nothing else. A race does not need forty spare vehicles in the pack.
If you are tempted to add "a few popular cars" to make a server more attractive, look at the join numbers first. A smaller, faster server tends to fill; a large, slow one tends to be skipped.
Bandwidth: who pays for the downloads#
Every mod download goes out through the server's uplink. Multiply the pack by the number of first-time joiners and the figure gets large fast. A public server with a 2 GB pack and fifty new players in a week sends about 100 GB of mod traffic, on top of the ordinary vehicle state. After a restart that changes a file, every regular is a first-time joiner again.
On top of that sits the in-game traffic, which scales with players multiplied by cars, because each client receives updates for every vehicle. Game server bandwidth per player gives a method for estimating it; for BeamMP the useful lesson is that MaxCars affects both client performance and traffic.
The burst matters as much as the total. Ten people joining together after a restart all pull the pack at once, and they share the upstream between them, so each of them sees a slower download than they would alone. Players then time out, retry and add to the load. If you run scheduled restarts, put them at a quiet hour, and if you have to change the pack, do it once rather than in five small steps over an evening.
On a host that does not bill per gigabyte, none of this costs extra money, but it is still a shared uplink, and bandwidth and fair use explains what "unmetered" means in practice. The disk side matters too: BeamMP plans on RE:NODE run from 10 GB of NVMe on the smallest plan up to 30 GB on the largest, and a pack plus its backups has to fit.
Keeping a mod pack consistent#
Most mod trouble on BeamMP is version trouble: a mod updated by its author, a game patch that changed something the mod relied on, or two versions of the same mod in the pack at once. A little discipline avoids nearly all of it.
Keep one copy of each mod. When you update a mod, delete the old zip before uploading the new one. Two archives that both contain vehicles/coolcar/ overwrite each other in an order you do not control, and the result is a car that sometimes has the new parts and sometimes does not. This is the same problem that mod load order describes for other games, with the difference that BeamNG gives you no load order to manage - you simply must not have duplicates.
Name files with versions. coolcar_v2.1.zip rather than coolcar.zip. When something breaks, you can see at a glance what changed since last week.
Keep a manifest. A plain text file beside the server, or in your Discord, listing each zip, its version, its size and where it came from. It is the thing you will reach for when a game update lands and you have to decide which mods to check first.
somemap_v3.zip 1.4 GB map, requires somemap_assetssomemap_assets.zip 310 MB dependency of somemapcoolcar_v2.1.zip 180 MB vehiclepickup_pack_v1.0.zip 95 MB vehicleMind the players' local mods. A player who has their own copy of a mod in their regular BeamNG mods folder, at a different version from yours, can see odd behaviour. BeamMP keeps the files it downloads apart from a player's own mods, but how the two interact has changed between launcher versions. When one player reports a problem nobody else has, ask them to disable their local mods and rejoin before you touch the server.
Update on purpose. After a BeamNG.drive release, players update their game, BeamMP follows, and some vehicle and map mods stop working until their authors catch up. Do not chase updates on a night people are waiting to drive. Take a backup of Resources/Client and ServerConfig.toml first, update the server, then add mods back in a controlled way. What to do when a mod update breaks describes the general routine.
Finding and removing a broken mod#
A broken BeamMP mod shows itself on the players' side, not the server's. The server does not load the mods, it only sends them, so the server console usually looks clean while players see a car that will not spawn, a vehicle with missing parts, a Lua error box in the game, a level that never finishes loading, or a crash to desktop.
The fastest diagnosis is bisection, and it works because there is no world state to damage:
- Stop the server and move everything out of
Resources/Clientinto a folder beside it, such asResources/Disabled. - Start the server with the stock map and confirm that a clean join works.
- Move half the mods back, restart, test.
- If the problem returns, the culprit is in that half. If not, it is in the other half. Repeat with the suspect half.
With twenty mods that is about five restarts. Keep the map in the first half you test if the map is a suspect, and set Map back to a stock level while you test the vehicles, so a map problem cannot hide a vehicle problem.
Players are your second source of evidence. The game writes a log, beamng.log, in the user folder, and the error near the end of it usually names the mod's folder. Ask one affected player to send it rather than describing what they saw.
To remove a mod for good:
- Delete the zip from
Resources/Client, not just rename it - a renamed.zipis still a zip and may still be sent. - If a map was removed, change
Mapback to a stock level or another map you still have. - Restart the server.
- Update your manifest and tell your players, so nobody keeps reporting a car that no longer exists.
Moving files into a sibling folder like Resources/Disabled is a safe way to park a mod without deleting it; the server only reads the folders it is configured to read. Do not leave disabled mods inside Resources/Client with a changed extension and assume they are ignored on every version.
Before adding a replacement, think about where it came from. Every zip you serve runs on other people's PCs, and vehicle mods can contain Lua. Use mods from authors and sites you can name, and treat a mod that appeared only as a file in a chat with suspicion. Malicious plugins and mods and keeping a modded server clean go into this properly.
Uploading packs and keeping backups#
Uploading a multi-gigabyte pack through a browser works, but a browser upload that stalls at 90% is lost time. For anything over a few hundred megabytes, use SFTP: it resumes in most clients, and it lets you drop a whole set of zips in one go. SFTP and the file manager covers the connection; on RE:NODE every server has its own SFTP credentials and the browser file manager is there for quick edits to ServerConfig.toml.
Because the server keeps no world state, a BeamMP backup is about the setup, and it is easy to forget until a bad update forces you to rebuild from memory. What is worth keeping:
ServerConfig.toml, which holds your map choice and settings.Resources/Server, your Lua plugins, which you cannot download again.Resources/Client, the exact set of mod versions that last worked together, or at least the manifest that lists them.
Large packs make full backups heavy, so a sensible split is a backup of the config and plugins before every change, and a full backup including Resources/Client when the pack is in a known good state. On RE:NODE, game plans carry backup slots you can run on demand or on a schedule and restore with a button; they are stored off the machine, and the panel's backups guide explains the controls. Backups that actually restore is the reminder to test one.
FAQ#
Do players need to install the mods themselves?
No. Anything in Resources/Client is downloaded automatically by the BeamMP launcher when a player joins and loaded for that session. Players only need BeamNG.drive and BeamMP. Asking them to install mods by hand usually makes things worse, because their manual copy may be a different version.
Can I have two maps on one BeamMP server?
You can upload several map zips, but only the one named in Map is used, and everyone is on it together. The others are still sent to every player, so unused maps are pure download cost. Keep only the map you are running, and switch by editing Map and restarting.
Why does my custom map load the default level instead?
The Map path does not match a level that exists. List the zip, find the folder under levels/ that holds info.json, and write it as /levels/<folder>/info.json with the same case. Check that the zip is still packed and sits directly in Resources/Client.
Does BeamMP support Steam Workshop or the in-game repository?
Not for servers. The server serves only the zips in its own Resources/Client folder. To use a mod from the BeamNG repository, download the zip yourself and upload it, keeping a note of the version.
Why do returning players have to download everything again?
Because a file changed. The launcher downloads any file that is missing or differs from the copy it has. Replacing, repacking or updating a zip counts as a change, so batch your pack changes together rather than making them one at a time.
How big can a BeamMP mod pack be?
There is no fixed limit beyond your disk, but join time sets a practical one. Under about 1 GB is comfortable for a public server; private groups can go larger because each person downloads once. Measure with du -sh Resources/Client and tell players the total.
