How to Add Workshop Maps to an Unturned Server

To add a Workshop map to an Unturned server, put the map's Workshop file ID in File_IDs in Servers/<ServerID>/WorkshopDownloadConfig.json, for example "File_IDs": [2136497468] for Elver, and set Map Elver in Servers/<ServerID>/Server/Commands.dat. Restart. The server downloads the map and players get it automatically when they connect. The Map line must be the map's folder name, not the Workshop title, or the server quietly loads PEI instead.

What you are working with

<ServerID> is the name the server starts with, from +InternetServer/<ServerID> on the launch line. Self hosted servers often use Default. On our servers it is the Server ID setting in the panel.

Curated maps need the Workshop too

PEI, Washington, Yukon, Russia and Germany ship with the server. Curated maps like Elver, Arid, Buak and Kuwait do not: they are only available through the Workshop, per the official server hosting docs. Some of the IDs from that page:

For community maps, copy the ID from the map's Workshop page.

Before you start

• Back up the server. Each map keeps its own save, but you will be editing Commands.dat.
• Stop the server before editing either file, or it may write over your changes.
• Check the map is maintained. Old community maps can fail to load on current Unturned versions. Check recent comments on the Workshop page.

Step 1: Add the file ID to WorkshopDownloadConfig.json

Open Servers/<ServerID>/WorkshopDownloadConfig.json. A fresh one looks like this:

{
  "File_IDs": [],
  "Ignore_Children_File_IDs": [],
  "Query_Cache_Max_Age_Seconds": 600,
  "Max_Query_Retries": 2,
  "Use_Cached_Downloads": true,
  "Should_Monitor_Updates": true,
  "Shutdown_Update_Detected_Timer": 600,
  "Shutdown_Update_Detected_Message": "Workshop file update detected, shutdown in: {0}",
  "Shutdown_Kick_Message": "Shutdown for Workshop file update."
}

Put the map's ID in File_IDs, as a number without quotes. Separate several IDs with commas:

"File_IDs": [2136497468, 1234567890],

The server also downloads the map's own required items. If one of those causes trouble, its ID goes in Ignore_Children_File_IDs to skip it.

Step 2: Start once to download the map

Start the server and let it finish. The console shows the Workshop download, and the map lands in Servers/<ServerID>/Workshop/Steam/content/304930/<file ID>/. Then stop the server.

Step 3: Find the map's real name

Open that download folder. Inside is a folder with a Map.meta file in it. That folder's name is the map's name. It is often close to the Workshop title, but not always: different capitalisation, no spaces, a version suffix, or something else entirely.

Step 4: Set the Map line in Commands.dat

Open Servers/<ServerID>/Server/Commands.dat and change the Map line to that exact folder name:

Map Elver
MaxPlayers 24
Mode Normal
Perspective Both
PvE
Owner 76561198000000000

Leave out PvE for a PvP server. Save and start the server.

Step 5: Join and check

The console shows Loading level: 100% when it is ready. Players connect as usual, and Unturned downloads the map for them while connecting. If you land on PEI, the map name did not match. See below.

The Map line uses the folder name, not the title

This is the step that sends most people back to PEI. Unturned does not stop with an error when the Map line names a map it cannot find. It loads the default map, PEI, and carries on. So the server starts, everything looks normal, and you are on the wrong island.

The fix is always the same: open Workshop/Steam/content/304930/<file ID>/, copy the name of the folder that contains Map.meta, and paste it on the Map line exactly. Copying the name off the Workshop page is how the mismatch happens.

If the download folder does not exist at all, the problem is one step earlier: the ID in File_IDs is wrong, has quotes or a typo, or the JSON is broken (a missing comma stops the whole file from loading).

Common problems

• Server loads PEI instead of the map: the Map name does not match the downloaded folder name exactly.
• Map never downloads: the ID is wrong, or WorkshopDownloadConfig.json has a syntax error. Check every comma and bracket.
• Server shuts down by itself with a message: Should_Monitor_Updates saw a Workshop update and restarted to install it. Set it to false to stop that, or keep it for automatic map updates.
• Players stuck downloading: large maps take a while on first join. Let it finish.
• Map loads but has no loot or vehicles: the map was made for an older version. Look for an updated release on the Workshop.

Workshop maps on GamezServers

On a GamezServers Unturned server, both files are a click away in the Files tab, under Servers/ and the folder named after your Server ID. Add the ID, start once, copy the map's folder name, set the Map line and restart. Press Backup first, and we make the Steam server token Unturned needs to appear in the server list. For the rest of Commands.dat and admin commands, see Unturned server commands.

FAQ

Where is WorkshopDownloadConfig.json on an Unturned server?

In Servers/<ServerID>/, next to the Server folder that holds Commands.dat. It appears after the server has started once.

Why does my Unturned server load PEI instead of my map?

The Map line does not exactly match the name of the downloaded map's folder, so the server falls back to PEI.

Do players need to subscribe to the Workshop map?

No. Players download the server's Workshop maps and mods automatically while connecting.

Can I add Workshop mods the same way?

Yes. Mods use the same File_IDs list. Only maps need a Map line in Commands.dat.