How to Add Mods to Your BeamMP Server

Mods are what make BeamMP servers unique. Whether you want a fleet of JDM imports, a custom drift map, or a full roleplay setup with police vehicles, it all comes down to putting the right files in the right places. This guide covers everything: where to find mods, how to install them, dealing with compatibility issues, and keeping your mod collection organised as your server grows.

How BeamMP Mods Work

Before installing anything, it helps to understand the system.

BeamMP has two types of server resources:

• Client mods (Resources/Client/) — these are .zip files that get downloaded to every player who joins. Vehicle mods, map mods, and UI mods go here. Players don't need to install anything manually — the server pushes mods automatically.
• Server plugins (Resources/Server/) — these are Lua scripts that run server-side. Think admin tools, race systems, economy plugins, and anti-cheat. Players never download these.

This guide focuses on client mods. For server-side Lua scripting, check the BeamMP documentation on plugins.

Where to Find Mods

BeamNG.drive Repository (Official)

The BeamNG.drive mod repository is the primary source. It has thousands of mods — vehicles, maps, props, and more — all vetted by the community. Most mods here work with BeamMP, though not all.

BeamMP Forum

The BeamMP Forum has server-specific resources, including all-in-one management tools like BeamJoy — a popular mod that adds races, derbies, deliveries, bus routes, and admin moderation to your server.

Community Discords

Many mod creators share their work on Discord servers. The official BeamMP Discord has a resources channel, and there are dedicated BeamNG modding communities. Just be careful with mods from random sources — stick to established communities.

What to Avoid

• Paid mods behind sketchy paywalls — the BeamNG community is largely free and open. Genuine creators may have a Patreon, but be wary of random sites selling "exclusive" mod packs.
• Outdated mods — mods that haven't been updated in 2+ years may crash your server or cause desyncs. Check the last update date before downloading.
• Pirated content — some mods are stolen from other games or creators. Besides being wrong, these often have broken physics and licensing issues.

Installing Vehicle Mods

This is the simplest part.

1. Download the mod (you'll get a .zip file)
2. Do not extract it — keep it as a .zip
3. Drop the .zip file into your server's Resources/Client/ folder
4. Restart the server

That's it. When players join, the mod downloads automatically.

Example

Say you downloaded CherryPeakCustoms_S15.zip from the BeamNG repository:

BeamMP-Server/
├── Resources/
│   ├── Client/
│   │   └── CherryPeakCustoms_S15.zip    ← drop it here
│   └── Server/
├── ServerConfig.toml
└── BeamMP-Server.exe

Players will see the new vehicle in their vehicle selector next time they join.

Multiple Mods

You can add as many vehicle mods as you want. Just keep dropping .zip files into Resources/Client/. Be aware that more mods = longer download times for players joining for the first time.

Tip: If your server has 20+ vehicle mods, consider whether players actually use all of them. A curated selection of 5-10 quality mods gives a better experience than 50 random ones that bloat the download.

Installing Custom Maps

Maps are slightly more involved because you need to update your server config.

Step 1: Add the Map File

Download the map mod and drop the .zip into Resources/Client/ (same as vehicle mods — don't extract it).

Step 2: Find the Map's Level Name

Open the .zip file (don't extract, just browse it) and look inside the levels/ folder. You'll see a folder with the map's internal name — something like derby_island or east_coast_usa_custom.

This folder name is what you need.

Step 3: Update ServerConfig.toml

Open ServerConfig.toml and update the Map line:

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

Replace derby_island with whatever the folder name was in the .zip.

Step 4: Restart the Server

Players will download the map automatically on join.

If the Map Doesn't Load

Sometimes the level name isn't obvious from the zip structure. Here's a foolproof method:

1. Install the map in your singleplayer BeamNG.drive
2. Load into the map
3. Open the console with the ~ (tilde) key
4. Type: print(getMissionFilename())
5. The output shows the exact level path to use

Default Maps (No Download Required)

These maps are built into BeamNG.drive and work without adding any files:

• /levels/gridmap_v2/info.json — Grid Map (flat sandbox)
• /levels/east_coast_usa/info.json — East Coast USA
• /levels/west_coast_usa/info.json — West Coast USA
• /levels/italy/info.json — Italy
• /levels/jungle_rock_island/info.json — Jungle Rock Island
• /levels/industrial/info.json — Industrial Site
• /levels/small_island/info.json — Small Island
• /levels/utah/info.json — Utah
• /levels/driver_training/info.json — Driver Training

Just change the Map line in your config — no downloads needed.

Managing Mod Compatibility

This is where most server owners hit problems. Here's how to handle it.

The "done" or "start" Screen Issue

If players get stuck on "done" or "start" when joining, a mod is incompatible or corrupted. This is the most common mod-related issue.

Fix:

1. Remove ALL mods from Resources/Client/
2. Restart the server and confirm players can join
3. Add mods back one at a time, testing after each
4. When the issue returns, you've found the problem mod

Mod-to-Mod Conflicts

Two mods can individually work fine but break when used together. This usually happens with:

• Two maps that modify the same terrain files
• Vehicle mods that override the same base vehicle
• UI mods that conflict

If you suspect a conflict, the same isolation approach works — test pairs of mods together.

Version Mismatches

Mods built for an older version of BeamNG.drive or BeamMP may not work. When BeamNG.drive updates, some mods break until the creator updates them. Check the mod's page for the supported game version.

Client-Side Mod Conflicts

Players might have local mods installed that conflict with your server mods. If one specific player has issues while others are fine, ask them to:

1. Go to their BeamNG.drive mods folder
2. Temporarily remove all local mods
3. Try joining again

Organising Your Mods

As your server grows, keeping mods organised saves headaches.

Keep a Mod List

Create a simple text file or spreadsheet tracking:

• Mod name
• Source URL (where you downloaded it)
• Version
• Date added
• Any known issues

This makes it easy to check for updates and troubleshoot problems.

Backup Your Resources Folder

Before adding new mods, back up your Resources/ folder. If something breaks, you can roll back instantly.

# Quick backup on Linux
cp -r Resources/ Resources_backup_$(date +%Y%m%d)/

Set Up a Test Server

If you run a popular public server, don't test new mods on your live server. Spin up a second private server for testing, verify everything works, then move the mods over.

Server-Side Plugins (Lua)

While this guide focuses on client mods, it's worth knowing about server-side plugins:

• Put plugin folders in Resources/Server/
• Each plugin is a folder containing at least one .lua file
• Lua files are hot-reloaded — edit them and changes apply without restarting
• Popular plugins: BeamJoy (all-in-one), admin panels, race systems, economy systems

Check the BeamMP Forum for community plugins.

Performance Considerations

More mods = more resources needed. Here's what to watch:

• Download time: Each mod adds to the initial download when players first join. 100MB of mods is reasonable; 500MB will frustrate players on slow connections.
• Memory usage: Each vehicle mod uses RAM on both the server and clients. Monitor your server's memory if you're running many mods.
• Physics complexity: Some vehicle mods have more complex physics than others (realistic suspension, detailed damage models). These use more CPU per player.

Rule of thumb: Start with fewer, high-quality mods. Add more based on what your community actually wants, not just because you can.

Quick Reference

Running mods on Connect Hosting? Our one-click mod manager makes adding and removing mods effortless — no FTP, no file management, just pick your mods and go. See our BeamMP plans →