Level Config and Settings ​

Intermediate40-60 minutesWindowsUnturnedUnity Editor

The Config.json file is the central configuration document for every Unturned™ map. It controls everything from the map's presentation on the main menu (credits, version number, feedback URL) to its gameplay parameters (gravity, weather, building restrictions) to its performance settings (batching, clutter loading, culling). A map without a Config.json file uses engine defaults for every field, which produces a functional but unconfigured map that lacks version tracking, matchmaking visibility, presentation credits, and any gameplay customizations that distinguish it from the vanilla experience.

This article documents every Config.json field relevant to the map authoring workflow, organized by functional category. It covers the file format and location, the main menu and presentation fields, arena mode configuration, gameplay and environment parameters, HUD visibility settings, the per-difficulty override system, and the diagnostic procedures for the most common configuration failures. The companion article Level Config Reference provides the complete field reference table for every documented field.

Config.json file open in Notepad++ alongside the Unturned level editor showing the map folder structure

Documentation source: This article references the official Smartly Dressed Games modding documentation for the Level Config chapter, combined with empirical validation across 57 Studios cohort mapping projects.

Prerequisites ​

  • A custom map project with spawn points placed and spawn tables authored. See Spawn Tables and Loot Config for the spawn table workflow that precedes Config.json configuration.
  • A text editor capable of saving UTF-8 without BOM. The 57 Studios™ recommendation is Notepad++.
  • Familiarity with JSON syntax: objects, arrays, strings, numbers, booleans, and the distinction between trailing commas (invalid in JSON) and comma separators.

What you will learn ​

  • The file location and encoding requirements for Config.json.
  • How to configure main menu fields: creators, version, matchmaking visibility, and Workshop dependencies.
  • How to set up arena mode with randomized circles and spawn loadouts.
  • How to configure gameplay parameters: gravity, slope, electricity, weather, water, and batching.
  • How to enable or disable specific HUD elements.
  • How to use per-difficulty config overrides for Easy, Normal, and Hard modes.
  • How to diagnose and fix Config.json not taking effect, read-only file issues, and cache problems.

How Config.json is loaded ​

When a map is loaded, the engine looks for a file named Config.json at the root of the map's folder. If the file exists, the engine reads it at startup and applies its values. If the file does not exist, the engine uses defaults for every field.

As shown above, the config file is entirely optional. A malformed Config.json is logged but does not prevent the map from loading. A map without a Config.json is functional but lacks all custom configuration.

File location and naming ​

The file must be named Config.json with exact case sensitivity. The engine does not recognize config.json, CONFIG.JSON, or any other casing variant. The file must be at the map root directory, not inside Level/ or Bundle/.

YourMap/
├── Config.json              ← Correct location
├── Level/
│   ├── Level.dat
│   └── Spawns/
├── Bundle/
└── ...

File encoding ​

The file must be encoded as UTF-8 without BOM. Files saved as UTF-16 (the default encoding for some Windows text editors) or UTF-8 with BOM will fail to parse, and the engine will silently fall back to defaults. The 57 Studios cohort recommendation is to configure Notepad++ to save new files as UTF-8 without BOM (Encoding > Encode in UTF-8).

The main menu fields control how the map is presented on the Unturned™ main menu and server browser. These are the fields that players see before they enter the map.

Creators and credits ​

FieldTypePurpose
Creatorsstring[]Map author names displayed in the map credits section.
Collaboratorsstring[]Names displayed alongside creators in credits.
Thanksstring[]Names displayed in the thanks section of credits.
CustomCreditsobjectMaps header titles to arrays of contributor names. The header titles are keys translated through the level's localization file.

The CustomCredits field is useful for crediting contributors by role. Example:

json
"CustomCredits":
{
  "Music": ["ComposerName"],
  "Art": ["ArtistName"]
}

The keys in CustomCredits are not localized themselves; they are looked up in the level's localization file. If no localization entry exists for a key, the key itself is displayed as the section header.

Version and matchmaking ​

FieldTypeDefaultPurpose
VersionstringemptyVersion number in #.#.#.# format. Required for version tracking across Workshop updates.
Visible_In_MatchmakingbooldependsShould this map be listed in the matchmaking menu? Set to false during development, true when publishing.
Feedbackstringworkshop URLURL to discussions or feedback page.
RequiredWorkshopFileIdsulong[]emptyWorkshop file IDs that must be loaded for this map to function. Maps that depend on other Workshop items must list those items' IDs here.

The Version field uses a #.#.#.# format. The 57 Studios cohort recommendation is to increment the build number for every Workshop upload. Vanilla map version numbers use 3.Year.Update.Patch, but this format is optional for custom maps.

json
"Version": "1.0.0.0",
"Visible_In_Matchmaking": false,
"Feedback": "https://steamcommunity.com/workshop/filedetails/discussion/123456789",
"RequiredWorkshopFileIds": [123456789]

The RequiredWorkshopFileIds field in detail ​

Maps that depend on other Workshop items must list those items' Workshop file IDs in the RequiredWorkshopFileIds array. If the required items are not subscribed when a player or server attempts to load the map, the single-player and editor menus display a "Missing Dependencies" message and prevent entering the map.

json
"RequiredWorkshopFileIds":
[
  123456789,
  987654321
]

The 57 Studios cohort recommendation is to list every Workshop item that the map depends on, including all item mods, vehicle mods, and other map mods that the map references. Omitting a dependency leads to the "Missing Dependencies" error or, worse, silent asset-missing behavior at runtime where the map loads but custom assets are invisible.

Arena mode configuration ​

Arena mode transforms the survival map into a round-based competitive mode. The arena mode settings in Config.json define how the arena operates when the server starts in arena mode.

Enabling arena mode support ​

Arena mode is enabled by the server operator when launching the server. The map's Config.json provides the loadouts that players receive when they spawn into an arena round. The map does not need to enable arena mode explicitly; the server's game mode selection determines whether arena mode is active.

Arena_Loadouts format ​

The Arena_Loadouts array contains dictionaries with two keys: Table_ID (a spawn table ID) and Amount (an integer count of how many times to grant items from that table).

json
"Arena_Loadouts":
[
  {
    "Table_ID": 28007,
    "Amount": 1
  },
  {
    "Table_ID": 28008,
    "Amount": 1
  }
]
FieldTypePurpose
Table_IDuint16The ID of the spawn table to generate items from. References a spawn asset by legacy ID.
AmountintThe number of times to roll the spawn table for items.

The Table_ID references a spawn asset by its legacy ID (not a file name). To convert a legacy spawn table to a spawn asset, use the LegacySpawns export button in the Level Editor's pause menu.

Use_Arena_Compactor ​

The Use_Arena_Compactor field controls whether the arena's safe zone circles are randomized periodically. When set to true, the circle center shifts at each compactor phase, forcing players into smaller zones. When false, the circle is fixed.

Game mode configuration ​

The general gameplay fields control the map's physics, environment, and behavior parameters.

Mode_Config_Overrides ​

The Mode_Config_Overrides field allows the map to override server configuration properties for the duration of the session. This is useful for maps that require specific gameplay settings to function correctly.

json
"Mode_Config_Overrides":
{
  "Zombies.Min_Drops": 5,
  "Zombies.Max_Drops": 10,
  "Vehicles.Armor_Multiplier": 0.1,
  "Gameplay.Allow_Shoulder_Camera": false
}

Per-difficulty overrides ​

Three fields allow per-difficulty overrides on top of the Mode_Config_Overrides:

FieldPurpose
EasyDifficulty_Config_OverridesOverrides applied on Easy difficulty
NormalDifficulty_Config_OverridesOverrides applied on Normal difficulty
HardDifficulty_Config_OverridesOverrides applied on Hard difficulty

Each field uses the same key-value format as Mode_Config_Overrides. The per-difficulty overrides are merged on top of the base overrides when the map is played at the corresponding difficulty.

Environment and physics fields ​

FieldTypeDefaultPurpose
Gravityfloat-9.81Acceleration of gravity.
Max_Walkable_Slopefloat59Steepest ground angle players can walk without sliding.
Has_Global_ElectricityboolfalseWhen true, all powerable objects have power by default.
Weather_OverridestringnoneLocks weather to "rain" or "snow".
Snow_Affects_TemperatureboolfalseWhen true, snow areas inflict cold damage.
Use_Legacy_Clip_BordersbooltrueCreates invisible walls at map boundaries.
Use_Legacy_GroundbooltrueCreates the default terrain ground plane. Set to false when using landscape tiles.
Use_Legacy_WaterbooltrueCreates the global water plane. Set to false when using water volumes.
Use_Legacy_Snow_HeightbooltrueEnables snow effects above the configured snow height threshold.
Use_Legacy_Oxygen_HeightbooltrueTraveling vertically past a certain point depletes oxygen.
Use_Underground_WhitelistboolfalseTeleports underground players to the surface unless inside a whitelist volume.
Is_Aurora_Borealis_VisibleboolfalseEnables aurora borealis visual effects.
Allow_Underwater_FeaturesboolfalseRestricts legacy details and navigation bounds underwater.
Prevent_Building_Near_Spawnpoint_Radiusfloat16Minimum distance from spawn points where building is allowed.
Enable_Clutter_OptionboolfalseWhen true, players can toggle the "Load Clutter" graphics option.
Allow_Holiday_RedirectsboolfalseWhen true, seasonal asset variants load during holidays.

Batching fields ​

FieldTypeDefaultPurpose
Batching_Versionintnot presentEnables level batching when set. Set to 2 for current version.
Batching_Max_Texture_Sizeint128Overrides the maximum texture size included in the level batching atlas.

The 57 Studios cohort recommendation is to set Batching_Version to 2 for all new maps and to verify compatibility by testing in single-player before publishing.

HUD settings ​

The HUD fields control the visibility of specific elements of the heads-up display. Each field is a boolean that defaults to true.

FieldDefaultPurpose
PlayerUI_HealthVisibletrueShow the health indicator
PlayerUI_FoodVisibletrueShow the food indicator
PlayerUI_WaterVisibletrueShow the water indicator
PlayerUI_VirusVisibletrueShow the virus indicator
PlayerUI_StaminaVisibletrueShow the stamina indicator
PlayerUI_OxygenVisibletrueShow the oxygen indicator
PlayerUI_GunVisibletrueShow the gun/ammo indicator
Allow_CraftingtrueAllow access to the crafting menu
Allow_SkillstrueAllow access to the skills menu
Allow_InformationtrueAllow access to the information menu

The 57 Studios cohort recommendation is to disable HUD elements that are not relevant to the map's gameplay. A map that does not use the food or water system should set PlayerUI_FoodVisible and PlayerUI_WaterVisible to false to reduce UI clutter.

Minimal working Config.json ​

The following minimal configuration is sufficient for a functional map that appears in matchmaking and uses level batching.

json
{
  "Version": "1.0.0.0",
  "Visible_In_Matchmaking": true,
  "Batching_Version": 2,
  "PlayerUI_HealthVisible": true,
  "PlayerUI_FoodVisible": true,
  "PlayerUI_WaterVisible": true,
  "PlayerUI_StaminaVisible": true,
  "Allow_Crafting": true,
  "Allow_Skills": true
}

This configuration enables matchmaking visibility, enables level batching, and makes all core HUD elements visible. All other fields retain their engine defaults.

Config not taking effect: diagnostic workflow ​

When Config.json edits do not appear in-game, the cause is almost always in one of three categories: file location, file encoding, or file syntax.

Diagnostic flowchart ​

Common Config.json failures ​

SymptomMost likely causeResolution
Config.json has no effectFile not in map root, wrong encoding, or malformed JSONValidate JSON syntax; confirm UTF-8 encoding; check file location
Map does not appear in matchmakingVisible_In_Matchmaking is false or not setSet to true and restart
Batching not activeBatching_Version missing or set to unrecognized valueSet to 2
HUD element still visible after setting to falseConfig.json not being read; field name misspelledVerify JSON validity; check field name spelling
Arena loadouts not applyingMap not loaded in arena mode or Arena_Loadouts emptyStart server with arena mode; populate Arena_Loadouts array
Missing Dependencies error on select screenRequiredWorkshopFileIds missing an IDAdd all required Workshop file IDs
Version not showing in server browserVersion field missing or not incrementedSet Version and increment on each upload

Read-only file issues ​

Windows may mark the Config.json file as read-only, particularly if it was copied from a protected directory or extracted from a ZIP archive. A read-only Config.json can still be read by the engine but cannot be overwritten by the map author during iterative editing.

Resolution: Right-click the file in File Explorer, select Properties, and uncheck Read-only. If the read-only attribute is persistent, the file may be in a directory that inherits its read-only status from a parent directory. Check the parent directory's properties.

JSON validation workflow ​

Before saving Config.json after any edit, validate the JSON syntax. A single syntax error causes the entire file to be silently ignored by the engine.

The 57 Studios cohort-recommended validation workflow is:

  1. Open the file in Notepad++.
  2. Install the JSON Viewer plugin (or use any JSON validator plugin) to highlight syntax errors.
  3. Alternatively, run a PowerShell validation command:
    Get-Content Config.json -Encoding UTF8 | ConvertFrom-Json
    If the command returns the parsed JSON object without errors, the syntax is valid. If the command returns a parsing error, fix the indicated line and re-validate.
  4. After validation, confirm the file encoding is UTF-8 without BOM (Notepad++: Encoding menu shows "Encode in UTF-8").
  5. Confirm the file name is Config.json and not Config.json.txt (Windows may append the .txt extension if file extensions are hidden in File Explorer).

Cache issues ​

When testing Config.json changes on a server, the server must be completely shut down and restarted. Config.json is read only at map load time; it cannot be hot-reloaded. If the server process is restarted but the map has not changed, the server may load the cached version of the map from the previous session.

Resolution: Use the Shutdown command in the server console to trigger a clean shutdown, then restart the server. If the issue persists, delete the server's Level/ save directory for the map to force a fresh load of the map data including Config.json.

Frequently asked questions ​

Can I have a Config.json with only a few fields? ​

Yes. Config.json is merged with engine defaults. Any field not present in the file retains its default value. A minimal Config.json with only Version and Batching_Version is perfectly valid.

What happens if I set a field to an invalid value? ​

The engine logs an error but does not prevent the map from loading. The field is silently skipped, and the default value is used.

Can I override server config values for my map? ​

Yes, through the Mode_Config_Overrides field. This field can override many server configuration properties, including zombie drop rates, vehicle armor multipliers, and gameplay settings. The overrides apply only while the map is loaded; they do not modify the server's base configuration.

How do I configure per-difficulty overrides? ​

Use the EasyDifficulty_Config_Overrides, NormalDifficulty_Config_Overrides, and HardDifficulty_Config_Overrides fields. Each field uses the same key-value format as Mode_Config_Overrides.

Do I need a Level Asset if I use Config.json? ​

No. Config.json and Level Assets are independent systems. Config.json handles main menu presentation, gameplay parameters, and performance settings. A Level Asset contains gameplay information like weather, skills, and terrain colors. Many custom maps use Config.json without a Level Asset.

How do I add custom tip messages to the loading screen? ​

Set the Tips field to the number of tip messages defined in the level's localization files. Each tip is a Tip_# key in the localization file. The loading screen randomly selects from the available tips on each load.

Can I hide specific HUD elements for specific areas of the map? ​

No. HUD visibility is a global map setting. The HUD fields in Config.json apply across the entire map. Per-area HUD customization requires a custom plugin.

My map uses legacy water but I want to disable bubble effects. Can I? ​

Yes. Set Use_Legacy_Water to true (to keep the global water plane) and Use_Vanilla_Bubbles to false (to disable bubble effects).

Why does my map show "Missing Dependencies" even though I have all the items? ​

The most common cause is that a RequiredWorkshopFileIds entry is incorrect or missing. Verify each Workshop file ID by opening the Workshop item page in a browser and checking the file ID in the URL.

Can I set Gravity to a positive value? ​

Gravity uses a negative value for downward acceleration. Setting Gravity to a positive value would produce upward gravity. While technically possible, this breaks most gameplay mechanics and is not a standard configuration.

Can I use Comments in Config.json? ​

JSON does not support comments. Any line that is not valid JSON syntax (including comments with // or /* */) will cause the parser to fail and the engine to fall back to defaults. Remove all comments from Config.json before saving.

How do I configure the map to have no water? ​

Set Use_Legacy_Water to false. This disables the global water plane. If the map uses water volumes instead, the volumes will still render. If no water volumes are placed, the map will have no water at all.

Can I disable the safezone indicator on the HUD? ​

There is no Config.json field to disable the safezone indicator specifically. To hide all non-essential HUD elements, disable the individual PlayerUI_* fields. The safezone indicator is tied to the damage protection system and cannot be independently hidden through Config.json.

My Config.json was working but stopped after a Windows update. What happened? ​

Windows updates can change the default file encoding or file association behavior. Check that the file is still saved as UTF-8 without BOM and that its name has not been changed to Config.json.txt by a Windows file association reset.

Best practices ​

  • Always set Version and increment it for every Workshop upload. The version number is the engine's mechanism for detecting stale cached versions.
  • Set Visible_In_Matchmaking to false during development and to true only when the map is ready for publication.
  • Enable Batching_Version: 2 for all new maps and test in single-player before publishing.
  • Disable HUD elements that are not relevant to the map's gameplay mode to reduce UI clutter.
  • Use RequiredWorkshopFileIds for all dependencies, including item mods. Omitting a dependency produces broken custom assets at runtime.
  • Save Config.json as UTF-8 without BOM. Confirm the encoding after every edit.
  • Validate JSON syntax with a validator tool before saving. A single missing comma invalidates the entire file.
  • Test Config.json changes in single-player before updating a published map.
  • Restart the server completely after Config.json edits. The file cannot be hot-reloaded.
  • Use per-difficulty overrides to tune gameplay across difficulty levels without maintaining separate Config.json files.

Advanced considerations ​

Config.json in a multi-map server environment ​

When a server runs multiple maps, each map has its own Config.json. Players experience the Config.json settings of the currently loaded map. Server operators who run multiple maps with different gameplay configurations should ensure that the Mode_Config_Overrides and per-difficulty overrides are consistent with the server's expected gameplay behavior for each map.

Config.json and Level Asset interaction ​

Some gameplay settings can be configured either in Config.json or in the Level Asset. Config.json handles presentation, performance, and top-level gameplay settings. The Level Asset handles specific gameplay mechanics such as weather schedules, skill overrides, and terrain colors. When a setting exists in both files, the behavior depends on the specific field. The 57 Studios cohort recommendation is to avoid duplicating settings across both files.

Managing Config.json across multiple branches ​

Map authors who maintain multiple versions of a map should maintain separate Config.json files for each branch. The Visible_In_Matchmaking field should be false on testing branches to prevent players from accidentally joining a test server. The Version field should clearly distinguish between branches, such as "1.0.0.1-dev" for a development build.

Worked example: Modifying Config.json for specific gameplay scenarios ​

The following worked examples demonstrate how to configure Config.json for common map gameplay scenarios. Each example starts from the minimal template and adds the fields needed for the specific scenario.

Worked example 1: Arena-focused map ​

For a map designed primarily for arena mode, the Config.json should configure arena loadouts, enable the compactor, and disable survival-oriented HUD elements that are not relevant in round-based play.

json
{
  "Version": "1.0.0.0",
  "Visible_In_Matchmaking": true,
  "Batching_Version": 2,
  "Use_Arena_Compactor": true,
  "Arena_Loadouts":
  [
    { "Table_ID": 28007, "Amount": 1 },
    { "Table_ID": 28008, "Amount": 1 }
  ],
  "PlayerUI_FoodVisible": false,
  "PlayerUI_WaterVisible": false,
  "PlayerUI_VirusVisible": false,
  "PlayerUI_OxygenVisible": false,
  "Allow_Crafting": false,
  "Allow_Skills": false
}

This configuration hides food, water, virus, and oxygen indicators because these survival mechanics are not relevant in arena mode. Crafting and skills are disabled because arena mode uses loadout-based gear acquisition.

Worked example 2: Hardcore survival map ​

For a hardcore survival map with severe resource scarcity, the Config.json should hide non-essential HUD information and configure gameplay parameters for increased difficulty.

json
{
  "Version": "1.0.0.0",
  "Visible_In_Matchmaking": true,
  "Batching_Version": 2,
  "Gravity": -9.81,
  "Snow_Affects_Temperature": true,
  "Has_Global_Electricity": false,
  "PlayerUI_StaminaVisible": false,
  "PlayerUI_OxygenVisible": true,
  "PlayerUI_GunVisible": false,
  "Mode_Config_Overrides":
  {
    "Zombies.Min_Drops": 1,
    "Zombies.Max_Drops": 3,
    "Gameplay.Allow_Shoulder_Camera": false
  }
}

This configuration enables snow temperature effects, disables global electricity (generators must be found), hides stamina and gun indicators (players must estimate their stamina and ammo), and reduces zombie loot drops to create scarcity.

Worked example 3: Creative or building-focused map ​

For a creative or building-focused map, the Config.json should remove survival pressure and grant maximum building freedom.

json
{
  "Version": "1.0.0.0",
  "Visible_In_Matchmaking": true,
  "Batching_Version": 2,
  "Has_Global_Electricity": true,
  "Prevent_Building_Near_Spawnpoint_Radius": 4,
  "PlayerUI_FoodVisible": false,
  "PlayerUI_WaterVisible": false,
  "PlayerUI_VirusVisible": false,
  "PlayerUI_StaminaVisible": false,
  "PlayerUI_OxygenVisible": false,
  "Allow_Crafting": true,
  "Allow_Skills": true
}

This configuration grants global electricity (no generators needed), reduces the building restriction radius near spawn points, and hides all survival indicators. Crafting and skills remain enabled for maximum player agency.

Appendix A: Complete Config.json template ​

json
{
  "Creators": ["YourName"],
  "Collaborators": [],
  "Thanks": [],
  "CustomCredits": {},
  "Version": "1.0.0.0",
  "Visible_In_Matchmaking": false,
  "Feedback": "",
  "RequiredWorkshopFileIds": [],
  "Asset": {},
  "Use_Legacy_Ground": true,
  "Use_Legacy_Water": true,
  "Enable_Clutter_Option": false,
  "Batching_Version": 2,
  "PlayerUI_HealthVisible": true,
  "PlayerUI_FoodVisible": true,
  "PlayerUI_WaterVisible": true,
  "PlayerUI_VirusVisible": true,
  "PlayerUI_StaminaVisible": true,
  "PlayerUI_OxygenVisible": true,
  "PlayerUI_GunVisible": true,
  "Allow_Crafting": true,
  "Allow_Skills": true,
  "Allow_Information": true
}

Appendix B: Config.json diagnostic table ​

SymptomMost likely causeResolution
Config.json has no effectFile not in map root, wrong encoding, or malformed JSONValidate JSON syntax; confirm UTF-8 encoding; check file location
Map does not appear in matchmakingVisible_In_Matchmaking is false or not setSet to true and restart
Batching not activeBatching_Version missing or set to unrecognized valueSet to 2
HUD element still visible after setting to falseConfig.json not being read; field name misspelledVerify JSON validity; check field name spelling
Arena loadouts not applyingMap not loaded in arena mode or Arena_Loadouts emptyStart server with arena mode; populate Arena_Loadouts array
Missing Dependencies errorRequiredWorkshopFileIds missing or incorrectVerify file IDs from Workshop item pages
Gravity feels wrongGravity set to incorrect float valueDefault is -9.81
Clutter option not appearingEnable_Clutter_Option not set to trueEnable the field in Config.json
Overrides not applying on specific difficultyPer-difficulty override field name misspelledVerify exact field name

Cross-references ​

Document history ​

VersionDateAuthorNotes
1.02026-07-2657 StudiosInitial publication. Complete level config and settings guide with main menu fields, arena mode, game mode configuration, HUD settings, and diagnostic procedures.
57 Studios logo with slogan

Beginner-friendly guides for Unturned modding, tools, publishing, server operations, and troubleshooting.

Learn

Getting StartedSteam SetupInstalling Unturned

Explore

ItemsSelf-HostingTroubleshootingHome

Built for Unturned creators, server staff, and 57 Studios™ contributors.

Copyright © 57 Studios™. All rights reserved. 57 Studios™, its branding, guides, and associated original content are protected by applicable copyright and trademark law.