Unturned Updated May 14, 2026

Unturned Steam Workshop Mods

Add Steam Workshop mods and curated maps to your Unturned server using WorkshopDownloadConfig.json. Covers the File_IDs array, automatic update detection, and client-side mod delivery.

UnturnedmodsSteam WorkshopWorkshopDownloadConfig.jsonplugins

Unturned Steam Workshop Mods

Unturned servers download Workshop content automatically at startup using a JSON configuration file. Players connecting to the server automatically receive the mods as well.

WorkshopDownloadConfig.json

File location:

Servers/<ServerName>/WorkshopDownloadConfig.json

Default file content (created on first launch):

{
  "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."
}

Adding Workshop Items

  1. Find the item on the Steam Workshop.
  2. The item ID is the number at the end of the Workshop URL: ?id=1234567890
  3. Add the ID to File_IDs:
{
  "File_IDs": [1234567890, 9876543210, 1975509500],
  "Query_Cache_Max_Age_Seconds": 600,
  "Should_Monitor_Updates": true
}
  1. Restart the server — it downloads all listed items before loading the map.

Key Configuration Options

Key Default Description
File_IDs [] Array of Steam Workshop item IDs to download
Ignore_Children_File_IDs [] IDs whose dependencies should NOT be auto-downloaded
Query_Cache_Max_Age_Seconds 600 How long to cache Workshop query results (seconds)
Max_Query_Retries 2 Retry count if Steam Workshop query fails
Use_Cached_Downloads true Use locally cached downloads instead of re-downloading unchanged files
Should_Monitor_Updates true Watch for mod updates and trigger auto-restart when found
Shutdown_Update_Detected_Timer 600 Seconds to wait before shutting down after update detected
Shutdown_Update_Detected_Message (see above) Warning message shown to players before update-shutdown; {0} is replaced with seconds remaining

Automatic Update Detection

When Should_Monitor_Updates is true, the server watches for Workshop item updates. When detected:

  1. Players receive the warning message (Shutdown_Update_Detected_Message) with a countdown.
  2. After Shutdown_Update_Detected_Timer seconds, the server shuts down.
  3. Your restart script or systemd Restart=on-failure brings it back up.
  4. On restart, the server downloads the updated mod files before loading.

Set Should_Monitor_Updates: false on servers where you want full control over when updates are applied.

Types of Workshop Content

Content Type Example How It Works
Curated maps Elver, Hawaii, Arid Listed in File_IDs; referenced by Map in Commands.dat
Mods (items, zombies) Custom item packs Listed in File_IDs; loads automatically at startup
OpenMod plugins Economy plugins Installed separately (see OpenMod guide)

Debugging Workshop Download Issues

If a mod fails to download:

  • Check the server startup log for Steam API errors.
  • Verify the Workshop item is still publicly available (not set to Friends-only or deleted).
  • Increase Max_Query_Retries to 5 if Steam API calls fail intermittently.
  • Clear the Workshop/ folder and restart to force a fresh download: 
    rm -rf Servers/<ServerName>/Workshop/
Back to Knowledgebase
Need help? Submit a Ticket →