An Unturned server gets workshop content from one file: WorkshopDownloadConfig.json in the server's instance folder. Put the numeric workshop IDs of a map and its asset packs in File_IDs, set Map in Commands.dat to the map's internal name, and restart. The server downloads every item at boot, and when a player joins it sends them the same list, so their client downloads it from Steam automatically - nobody has to subscribe by hand. Almost every workshop problem on an Unturned server is one of four things: a missing dependency, a wrong map name, two mods using the same IDs, or a workshop item that updated while the server was running.
This guide covers the file and every field in it, maps and the name that loads them, content mods, dependencies, what happens when an item updates, and the errors players actually see. For the rest of the server - Commands.dat, ports and the login token - see Unturned server setup.
How workshop content reaches a server and its players#
Workshop items for Unturned are hosted by Steam, under the game's app ID 304930. The dedicated server does not need anyone's Steam account to fetch them: it reads the ID list at boot, downloads anything missing or out of date, and loads the assets.
When a player connects, the server tells them which items it is running. The client compares that with what it has, downloads anything missing from Steam, and loads in. A player's first join to a heavily modded server can take a while for exactly this reason.
That handshake is why the ID list is the right place for workshop content rather than files copied into folders by hand. Content copied manually onto a server is not in the list, so clients are never told to fetch it, and they arrive in a world full of things they cannot load.
WorkshopDownloadConfig.json, field by field#
The file sits at Servers/<ServerID>/WorkshopDownloadConfig.json and is created on the server's first start. Stop the server before editing it. A typical file:
{ "File_IDs": [ 1234567890, 1234567891, 2345678901 ], "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}"}| Field | What it does |
|---|---|
File_IDs | The workshop items to download and load. Numbers, comma-separated |
Ignore_Children_File_IDs | Items to skip even if something in File_IDs lists them as required |
Query_Cache_Max_Age_Seconds | How long the server trusts its last look at item details |
Max_Query_Retries | Retries when Steam does not answer |
Use_Cached_Downloads | Reuse items already downloaded if they are current |
Should_Monitor_Updates | Watch for workshop updates while running |
Shutdown_Update_Detected_Timer | Seconds of warning before shutting down for an update |
Shutdown_Update_Detected_Message | The warning shown to players; {0} is replaced with the time left |
The fields and their defaults have grown over several updates, so treat the file your server generated as the reference for your build. The ones you will touch are File_IDs and the update fields.
The workshop ID is the number at the end of the item's Steam page address, after ?id=. It is a number, not a name, and JSON wants it without quotes. A missing comma between IDs, or a trailing comma after the last one, makes the file invalid; the server then either ignores it or fails to start, and the console says which. SFTP and the file manager covers editing it, and an in-browser editor with syntax highlighting makes the stray comma easier to spot before you restart.
Maps: the ID and the name#
A workshop map needs two things: its ID in File_IDs, and its name in Commands.dat.
Map Example IslandThe name is the map's internal name - the name of the map's folder inside the workshop item - not necessarily the title on its workshop page. Most map authors state the exact name to use on the page. If they do not, look in the downloaded item after the server has fetched it: the map folder's name is the value you want.
If the server cannot find the map you named, it does not fail. It loads PEI, the small default map, and starts normally. A server that keeps starting on PEI after you added a map has one of three problems: the name does not match exactly, the workshop item did not download (check the console at boot for the download), or the map was added to File_IDs but the server was not restarted.
The official maps - PEI, Washington, Russia and Yukon among them - ship with the game and need no workshop entry. Curated maps, the community maps featured inside the game, are hosted on the workshop. Recent server builds can resolve a curated map from its name, but adding its workshop ID to File_IDs is the dependable way to make sure the server has it.
Only one map runs at a time. Changing Map gives you a different world with its own save; the old map's save stays on disk under its own name, so switching back later returns to it.
Asset packs and dependencies#
Many large maps are not one workshop item. They come as a map item plus one or more asset packs: the buildings, props, vehicles and items the map uses, published separately so they can be updated or shared between maps.
If the server or a player is missing an asset pack, the map loads without those objects. Players see gaps in the world, floating red error text where objects should be, or a kick on join when the server and client disagree about what exists.
Two mechanisms handle this.
Required items. A workshop item can list other items it requires. When the server downloads it, it pulls those children in as well. This is why many maps work with only the map's own ID listed.
`Ignore_Children_File_IDs`. Occasionally a required child is one you do not want - an outdated pack, or one you are replacing with a different version. Listing it here skips it.
Not every author sets required items correctly. Read the map's workshop page for anything it says to install alongside it, add those IDs explicitly, and check the console at boot to confirm everything downloaded. Listing an ID that would also be pulled in as a child does no harm.
Workshop collections are a convenient way for players to subscribe to a set of items, but whether a collection ID behaves like a list of IDs on the server has varied between builds. Listing items individually is predictable and makes it obvious what the server is running.
Content mods: items, vehicles and the ID problem#
Content mods - new guns, vehicles, clothing, buildables - are added exactly like maps: workshop ID in File_IDs, restart. The server loads their assets alongside the game's own.
The old trouble with Unturned mods is IDs. Every item, vehicle and object in the game has a numeric ID within its category, and legacy mods picked their own numbers. Two mods that both define item 30000 conflict, and one of them wins - so a player spawns, buys or loots something that turns out to belong to the other mod. Newer assets also carry a GUID, which is unique by design, but plenty of popular content still depends on numeric IDs, and spawn tables, shops and plugins frequently refer to items by number.
The defence is mostly attention:
- Read the server log at boot. Asset conflicts are reported while assets load. A clean log with your mod list is worth checking after every addition.
- Add one mod at a time. Restart, check the log, check in game, then add the next.
- Prefer maintained mods. An active author resolves reported conflicts; an abandoned one will not.
- Check plugin configs against IDs. Kits, shops and loot plugins refer to item IDs. When you add or remove a mod, the IDs your plugin configs list may now point at something else, or at nothing.
Mods that a map depends on are a special case: removing them breaks the map. Mods nothing depends on can be removed, but anything players own from that mod vanishes - from inventories, storage and vehicles. Removal is a decision to announce, not a quick fix.
Updates while the server is running#
Workshop authors update their items whenever they like. The danger is the gap: the server is running the old version, a player joins, Steam gives them the new one, and the two sides disagree. Depending on what changed, the player is kicked with a mismatch, or joins and then sees errors.
Should_Monitor_Updates is the built-in answer. With it on, the server watches its items, and when one updates it warns players with Shutdown_Update_Detected_Message and shuts down after Shutdown_Update_Detected_Timer seconds. On the next start it downloads the update, and server and players agree again.
That only works if something starts the server again. Check how your host treats a clean exit: on some setups the server comes straight back, on others it waits to be started. If it waits, a server that shuts itself down for a mod update at 4am stays down until somebody notices. The alternatives are to keep monitoring on and make sure it is restarted, or to turn it off and pick up updates with a nightly restart at an hour when nobody plays.
On RE:NODE the Schedules tab can run that nightly routine as ordered tasks: a say command warning players, a delay, save, a restart, then a backup. A restart re-reads WorkshopDownloadConfig.json and fetches any updated items on the way up. Restart schedules that help covers choosing the hour.
Server size and download time#
Workshop content costs the server memory and disk, and costs players download time.
| Content | Memory impact | Disk |
|---|---|---|
| Official map, no mods | Baseline, around 2 GB server | A couple of GB install |
| Curated map | Small to moderate | Hundreds of MB |
| Large community map with asset packs | Moderate to large | Up to several GB |
| Large map plus many content mods | Large | Several GB |
The map is usually the biggest single factor, because a large map holds far more objects than an official one. Content mods add up when there are many of them. The setup guide has a full sizing table by player count.
Downloads hit players more than the server. A server with several gigabytes of workshop content means a long first join for every new player, and a full re-download of anything that updates. Keep the list to what the server actually uses, and mention the download size in your server description so new players know to wait. Steam Workshop mods on dedicated servers covers how downloads work across games, including items that get unlisted.
Troubleshooting#
The server always loads PEI. The Map name does not match the internal map name, the map did not download, or the server was not restarted after the change.
Players see red error text and missing buildings. A missing asset pack. Find what the map requires on its workshop page and add the IDs.
Players are kicked on join with a workshop or asset mismatch. An item updated and the server has not restarted. Restart it; turn on Should_Monitor_Updates or schedule nightly restarts.
The server ignores WorkshopDownloadConfig.json. The JSON is invalid - usually a missing or trailing comma - or the file was edited while the server ran and overwritten on shutdown.
An item spawns as the wrong thing. Two mods share a numeric ID. Check the boot log for conflicts and remove one of them.
First joins take a very long time. Players are downloading the workshop list. Trim unused items and state the download size in the server description.
A plugin's kit or shop gives the wrong items. Item IDs changed after a mod was added or removed. Update the plugin config.
FAQ#
Do players need to subscribe to my workshop maps?
No. The server sends its item list on join and the client downloads everything from Steam automatically. Players only need to wait for the download on their first join.
Where do I find a map's internal name?
On the map's workshop page, where most authors state it. Otherwise, look at the folder name inside the downloaded workshop item on the server. That folder name is what goes after Map in Commands.dat.
Can I add mods without restarting?
No. WorkshopDownloadConfig.json is read at boot. Add the ID, then restart, ideally at a quiet hour.
Why does my map load without its buildings?
It depends on an asset pack the server or player does not have. Add every item the map's page says it needs to File_IDs, restart, and check the boot log.
Can I put a workshop collection ID in the file?
Listing individual item IDs is the dependable method. How collections behave on a server has varied between builds, and an explicit list makes it clear what you are running.
What happens to players' items if I remove a mod?
Anything that came from that mod disappears from inventories, storage and vehicles. Announce removals, and keep a backup from before the change in case you need to undo it.
Comments
Completely anonymous: no account, no email, no cookie. We store the name you type, the text and the time - nothing else. Links are limited and markup is not rendered.