Upgrading Unity Version

Intermediate40-60 minutesWindowsUnity HubUnity Editor

Unturned™ has undergone several engine upgrades across its development history, each of which changed the required Unity Editor version for mod development. A mod developer who upgrades a Unity project from one LTS version to the next, or who inherits an older mod project that was authored for a previous Unity version, must navigate a specific set of migration steps to produce compatible asset bundles. Skipping a migration step produces bundles that load incorrectly (content appears with default or pink materials), fail to load entirely (the engine rejects the bundle format), or load but behave subtly differently from the author's intent.

This article covers every Unity version upgrade that Unturned™ has undergone, from the earliest documented transition (Unity 5 LTS to Unity 2017 LTS) through to the most recent (Unity 2018 LTS to Unity 2019 LTS), with a focus on the practical steps that a mod developer must perform to migrate a mod project across these version boundaries. The article also covers the Asset_Bundle_Version field in MasterBundle.dat, which controls shader consolidation behavior across Unity versions and is the single most important configuration field for maintaining bundle compatibility, and provides a compatibility table mapping Unturned™ game versions to their required Unity Editor versions.

For archival purposes, the older Unity versions of the game remain available through Steam beta branches. This means a mod developer who needs to reference or extract assets from an older game version can still install that version through Steam's betas interface, though newer mods should always target the current Unity LTS release that the main game branch requires.

Documentation source: This article documents the Unity version upgrade process as published in the official Smartly Dressed Games modding documentation, Chapter 13 (Upgrading Unity Version). The upgrade documentation is described by its author as "admittedly rather old" for some sections, but the information has been revised as recently as November 2024 and remains accurate for the current toolchain. Sections marked as archival in the source documentation are presented here with their archival context noted.

Who this article is for

This article is written for Unturned™ mod developers who need to upgrade their Unity project from one LTS version to a newer one, or who are encountering bundle compatibility errors after a game update changed the required Unity version. If you are starting a new mod project and have never installed the Unity Editor for Unturned™ development, begin with How to Install the Unity Editor and How to Import the Unturned Project Package before returning here. If you are maintaining a mod that was built for a Unity version two or more major releases behind the current target, this article describes the cumulative migration path from the earliest supported version through to the current one.

Understanding Unity version compatibility in Unturned

Unturned™ is built on Unity's Long Term Support (LTS) releases, which receive bug fixes and stability updates for an extended period beyond the initial release. The game's development has tracked through several LTS generations: Unity 5.5 LTS, Unity 2017.4 LTS, Unity 2018.4 LTS, and Unity 2019.4 LTS. Each transition brought changes to the asset bundle format, the shader system, the available platform targets, and the mod-development toolchain.

The fundamental compatibility rule is: an asset bundle must be built with the same Unity major version that the game client was built with. A bundle built in Unity 2017.4 will not load correctly in a game client built in Unity 2018.4, and a bundle built in Unity 2019.4 will not load correctly in a game client built in Unity 2018.4. The version match requirement extends to the minor version as well in practice: the cohort recommendation is to match the exact Unity version specified in the current game documentation rather than any version in the same LTS family.

When a game update moves Unturned™ to a new Unity LTS version, all existing mod bundles become incompatible and must be re-exported from the new Unity Editor version. The game provides beta branches that allow players to remain on older game versions, and these beta branches use the older Unity version, so mods that have not been updated remain playable for players who opt into the appropriate beta branch. However, the main game branch always requires the current Unity version, and Workshop mods that target the main branch must be built with that version.

As shown in the flowchart above, every Unity version upgrade triggers a mandatory re-export cycle for all mod content. The mod developer must install the new Unity Editor version, upgrade the project, re-import the project package to get the updated scripts and shaders, and re-export every master bundle. Skipping the re-import step and only re-exporting the bundle can produce bundles that appear to export correctly but fail at runtime because the shader or script references in the bundle point to versions that do not match what the new game client expects.

Asset Bundle Version: the shader consolidation control

The Asset_Bundle_Version field in MasterBundle.dat is a numeric value that controls whether the game performs shader consolidation on the bundle at load time. Shader consolidation is the process by which the game attempts to replace older shader references in a bundle with the current game shader equivalents, allowing bundles built for older Unity versions to function on newer game versions without requiring a full re-export. The Asset_Bundle_Version field determines whether consolidation is attempted:

Asset_Bundle_Version	Unity version	Shader consolidation	Description
(not set, or < 3)	Unity 2017 LTS and earlier	Attempted automatically	The game tries to consolidate older shaders with current versions during loading. This allows Unity 2017 bundles to load in Unity 2018+ game clients without re-export, provided the bundles do not use custom shaders.
3	Unity 2018 LTS and later	Disabled	Shader consolidation is skipped. The bundle's shader references are used as-is. This requires the bundle to have been built with the matching Unity version.

The transition from Asset_Bundle_Version below 3 to Asset_Bundle_Version 3 occurred at the Unity 2017 LTS to 2018 LTS upgrade. Bundles built with Unity 2018.4 or later should set Asset_Bundle_Version 3 in their MasterBundle.dat to disable the shader consolidation step, because consolidation is unnecessary when the bundle was built with the correct Unity version and can produce incorrect results if it attempts to modify shaders that are already current.

Asset_Bundle_Version compatibility table

Game version	Unity version	Asset_Bundle_Version	Notes
Unturned 3.x (legacy, pre-2017)	Unity 5.5 LTS	Not set	Available from `unity-5.5` beta branch. Mods from this era are incompatible with all later versions and require full re-authoring.
Unturned 3.x (pre-2018)	Unity 2017.4 LTS	Not set or < 3	Available from `unity-2017.4` beta branch. Shader consolidation is attempted at load time for bundles from this era.
Unturned 3.x (pre-2019)	Unity 2018.4 LTS	3	Available from `unity-2018` beta branch. `Asset_Bundle_Version 3` disables shader consolidation.
Unturned 3.x (current)	Unity 2019.4 LTS	3	Current main branch. `Asset_Bundle_Version 3`. Shader consolidation is disabled.

Unity 5 LTS to 2017 LTS migration

The upgrade from Unity 5.5 to Unity 2017.4 was the first major engine upgrade in Unturned's development history and the most disruptive to the mod ecosystem. Any mods created in Unity 5 are no longer compatible with the game on any current branch. The Unity 5.5 LTS version of the game remains available from the unity-5.5 beta branch on Steam for archival reference only.

Reasons for the upgrade

The official SDG documentation cites two key reasons for the upgrade. First, Unity 2017 marked the start of Unity's annual LTS release cadence, with a focus on stability and performance improvements that allowed the game to remove workarounds for Unity bugs that had been resolved in the newer engine version. Second, Apple deprecated OpenGL support on macOS, and Unity 2017.4's Metal graphics API support was essential for maintaining macOS compatibility for the game client.

Master bundles: the new export format

The most significant mod-development change in the Unity 2017 LTS era was the introduction of master bundles. Before Unity 2017 LTS, each asset bundle was exported as an individual .unity3d file. The master bundle system allows exporting multiple bundles into a combined .masterbundle file, which is more efficient for load time and runtime performance. Master bundles are not required (individual .unity3d bundles are still supported), but they are the recommended format for production mods.

A master bundle works by redirecting the game's file lookups. When the game traverses a folder hierarchy and finds a MasterBundle.dat file, it assumes all sub-folders should be redirected into that master bundle. For example, if a mod has the folder structure MyModBundles/Items/Guns/MyGunItem.dat, and MyModBundles contains a MasterBundle.dat file, the game will load all Unity assets for items under that path from the master bundle rather than from individual .unity3d files. The folder structure in the Unity project must match the folder structure in the mod's file hierarchy exactly (one-to-one) for the redirection to work.

Installing the master bundle tools

The master bundle export tools are located in Unturned/Bundles/Sources/Tools/. Copy all files from this directory into the Assets/Editor/ directory of the Unity project. After copying, the Master Bundle Tool becomes available from the Window > Unturned menu in the Unity Editor.

To use the Master Bundle Tool:

In the Unity Project Browser, select the folder that contains the bundles to export.
In the Inspector, assign the folder to an AssetBundle. If no AssetBundle has been created yet, create one through the AssetBundle dropdown at the bottom of the Inspector.
Open the Master Bundle Tool from Window > Unturned.
Select the AssetBundle from the dropdown.
If the mod must be compatible with macOS and Linux, check the "Multi-platform" option before exporting.
Click the "..." button to select a target location for the exported master bundle. The target location must contain a MasterBundle.dat file.

Multi-platform build time optimization

When actively iterating on a mod during development, do not enable the multi-platform option. Multi-platform builds take significantly longer because Unity must compile shader variants for each target platform. Enable multi-platform only for release candidates and final Workshop submissions. The option can be toggled at any time without affecting the bundle contents.

The MasterBundle.dat configuration file

Every folder that contains a master bundle must have a MasterBundle.dat file. This file tells the game that the folder contains a master bundle and provides the configuration needed to load it correctly. The MasterBundle.dat file supports the following fields:

Field	Type	Required	Purpose
`Asset_Bundle_Name`	string	Yes	The filename of the Windows master bundle exported from Unity. For example, `hawaii.masterbundle`.
`Asset_Prefix`	string	Yes	The file path to the folder selected as the AssetBundle in Unity. For example, `Assets/MyModBundles`. The game uses this prefix to match in-game file paths to content within the bundle.
`Asset_Bundle_Version`	integer	No (see below)	Controls shader consolidation behavior. Set to `3` for Unity 2018 LTS and later bundles.

Additionally, individual .dat files within a master bundle's folder hierarchy can use two optional properties:

Property	Purpose
`Exclude_From_Master_Bundle`	A flag that causes the `.dat` file to ignore any parent master bundle and instead look for an individual `.unity3d` file. Use this for items that should remain as standalone bundles within a master-bundle-managed folder.
`Master_Bundle_Override`	Specifies the name of a master bundle to redirect to, overriding the parent folder's default master bundle.
`Bundle_Override_Path`	Allows multiple items to share the same setup in Unity. For example, the vanilla note objects share the same model. Can be combined with `Master_Bundle_Override` to use models from other master bundles (e.g., using the Eaglefire's model with custom stats).

Shader import for Unity 2017 LTS

Shaders can be imported from the All_Shaders.unitypackage file located in a subdirectory of the Sources folder. The official SDG documentation recommends using the official shaders to improve compatibility with base game content. In later Unity versions, the shader package was merged into the consolidated ExampleAssets.unitypackage, but for Unity 2017 LTS projects, All_Shaders.unitypackage is the correct import.

Upgrading a Unity 5 project to Unity 2017 LTS

Back up the entire Unity 5 project folder before proceeding. The Unity version upgrade process is one-way; there is no downgrade path.
Install Unity 2017.4 LTS through Unity Hub.
Open the backup copy of the project in Unity 2017.4. Unity will prompt to upgrade the project; accept the upgrade.
After the upgrade completes, import the updated Project.unitypackage from the current game version's Bundles/Sources/ directory.
Re-import shaders from All_Shaders.unitypackage.
Copy the master bundle tools to Assets/Editor/.
Re-assign AssetBundle names to the project folders if they were lost during the upgrade.
Create or update MasterBundle.dat files at each bundle target location.
Export all master bundles from the Master Bundle Tool.
Test the exported bundles in the current game version.

Common Unity 2017 LTS upgrade issues

Symptom	Cause	Resolution
Colors too light or dark in-game	Color Space setting in Unity project needs adjustment	Navigate to `Edit > Project Settings > Player`. Under Other Settings, change `Color Space` to `Linear`. If that does not resolve the issue, confirm that sRGB is enabled on the textures.
Devkit foliage renders incorrectly	Materials default to instancing disabled in Unity 2017+	Enable the `Instancing` flag in the Unity material inspector for foliage materials, then rebuild the asset bundle.
Master bundle does not load in game	`MasterBundle.dat` missing or misconfigured	Confirm the `Asset_Bundle_Name` matches the exported filename exactly and that `Asset_Prefix` matches the Unity folder path.
Items reference wrong models	Folder hierarchy mismatch between Unity project and mod folder structure	Confirm that the Unity project folder structure is a one-to-one match with the mod folder structure under the master bundle root.

Unity 2017 LTS to 2018 LTS migration

The upgrade from Unity 2017.4 LTS to Unity 2018.4 LTS was less disruptive than the 5-to-2017 transition, primarily because the master bundle system was already in place. The main changes were to the asset bundle format, the shader consolidation system, the Unity packages, the logging system, and the Workshop compatibility.

Asset bundle backward compatibility

Older .unity3d, .content, and .masterbundle files from Unity 2017 LTS should work in Unity 2018 LTS game clients without needing any update, unless the bundles use custom shaders. The game automatically attempts to consolidate older shader references with the latest versions during loading. This backward compatibility is a convenience for players who have mods that have not been updated; mod developers should still re-export their bundles with the new Unity version for full compatibility and to take advantage of performance improvements.

Once a bundle is re-exported from Unity 2018 LTS, Asset_Bundle_Version can be set to 3 in MasterBundle.dat to disable the shader consolidation step. Bundles with Asset_Bundle_Version 3 will not undergo shader consolidation at load time, which reduces load time and eliminates the risk of consolidation producing incorrect shader assignments for custom materials.

Asset validation

Some of the slower asset checks, such as finding missing meshes, have been made optional in Unity 2018 LTS. Running the game with the -ValidateAssets command-line option enables these checks. The cohort recommendation is to run validation during active content development and to disable it for normal gameplay to reduce load times. The validation checks are useful for catching missing mesh references, broken prefab links, and other asset integrity problems before they surface as in-game bugs.

Consolidated Unity packages

All example content was updated for Unity 2018 LTS and given a consistent export process. The separate individual packages (such as All_Shaders.unitypackage) were merged into a single ExampleAssets.unitypackage file located in Extras/Sources/Examples/. This consolidated package contains all shaders, example prefabs, example materials, and other reference content in a single import.

Logging and server console changes

Usage of Unity's built-in Debug.Log was replaced with logging to Client.log or Server_XYZ.log files in the Logs folder. This change resolved a conflict with standard output on the Linux dedicated server, so the -logfile redirect workaround that was previously necessary for Linux servers is no longer required. The -ThreadedConsole implementation was made the default, improving console performance on servers with high message volume. The -LegacyConsole flag can disable threaded console if compatibility issues arise.

Workshop compatibility

Uploads from Unity 2018 LTS are incompatible with past versions of the game. A warning message is shown when loading newer content in the Unity 2017 LTS version of the game. This means a Workshop mod published after upgrading to Unity 2018 LTS will not function for players who have opted into the unity-2017.4 beta branch. Mod developers who want to support multiple game versions must maintain separate Workshop items for each target version or must clearly document which game version the mod requires.

Platform changes

Linux 32-bit and macOS 32-bit platform targets were removed in favor of 64-bit versions. Servers that were using the outdated Linux 32-bit depot must update to the 64-bit Linux dedicated server depot. Headless server files were removed from the player Linux depot and are instead only available in the dedicated server Linux depot. Windows headless mode was added for the Windows dedicated server depot, allowing Windows servers to run without a graphical interface.

Upgrading a Unity 2017 LTS project to Unity 2018 LTS

Back up the entire Unity 2017 LTS project folder.
Install Unity 2018.4 LTS through Unity Hub.
Open the backup copy of the project in Unity 2018.4. Accept the project upgrade when prompted.
Import the updated Project.unitypackage from the current game version's Bundles/Sources/ directory.
Import ExampleAssets.unitypackage from Extras/Sources/Examples/ to get the updated shaders and example content.
Update every MasterBundle.dat file: set Asset_Bundle_Version to 3.
Re-export all master bundles from the Master Bundle Tool.
Test in the current game version with -ValidateAssets enabled to catch missing meshes and other asset integrity issues.
Upload the updated mod to the Steam Workshop as a new version. Note that players on older game branches will see a warning message when attempting to load the updated content.

Unity 2018 LTS to 2019 LTS migration

The upgrade from Unity 2018.4 LTS to Unity 2019.4 LTS introduced relatively few breaking changes for mod development. The official SDG documentation describes this upgrade as having "very few notable changes." The principal changes were to the animation import pipeline and to the recommendation to use exchange formats for model import.

Animation import changes

Unity 2019 LTS no longer supports importing multiple animations from a single .blend file by default. Mod developers who previously imported Blender files directly into Unity with embedded animation data must switch to exporting animations to an exchange format such as .fbx and importing the .fbx file into Unity. This change aligns the mod-development workflow with the base game's own asset pipeline: the base game has always handled its assets through exchange-format exports rather than direct .blend imports.

Exchange format recommendation

The official SDG documentation recommends exporting meshes and models to .fbx as well, not only animations. The base game has always handled its own assets through .fbx exchange files rather than through direct .blend imports, and the cohort recommendation for mod projects is to adopt the same workflow for consistency with the vanilla asset pipeline and to avoid Blender-version-specific import issues that can arise when the Unity Editor's Blender importer does not match the Blender version that authored the file.

Upgrading a Unity 2018 LTS project to Unity 2019 LTS

Back up the entire Unity 2018 LTS project folder.
Install Unity 2019.4 LTS through Unity Hub.
Open the backup copy of the project in Unity 2019.4. Accept the project upgrade when prompted.
Import the updated Project.unitypackage from the current game version's Bundles/Sources/ directory.
For any models that were imported directly from .blend files, re-export the models from Blender to .fbx format and re-import the .fbx files into Unity. Update prefab references to point to the .fbx-imported meshes.
Re-import ExampleAssets.unitypackage from Extras/Sources/Examples/ to get any updated example content.
Re-export all master bundles from the Master Bundle Tool.
Test in the current game version.

Determining the current required Unity version

The fastest way to determine which Unity Editor version the current game client requires is to consult the official Smartly Dressed Games modding documentation, which states the required Unity version on the documentation's landing page. Alternatively, the Unturned™ Steam community hub and the game's update changelog (accessible through the Steam library page for Unturned™) announce Unity version changes when they occur.

If the documentation and changelog are unavailable or ambiguous, the Project.unitypackage file distributed with the game client contains Unity version metadata in its internal structure. The file is located in Unturned/Bundles/Sources/Project.unitypackage relative to the game's installation directory. Opening this file in a text editor and searching for the Unity version string (which appears in the package's metadata header) reveals the Unity version that the package was exported from, which is the version the game was built with.

Project backup before upgrade

Every Unity version upgrade is a one-way operation. Unity does not support downgrading a project to an earlier version. The following backup workflow is the cohort-validated pre-upgrade procedure:

Close the Unity Editor if it is open with the project.
In File Explorer, navigate to the project's root folder.
Copy the entire project folder to a separate backup location. The backup copy should have a name that includes the Unity version it was created with (e.g., MyModProject_Unity2018_backup).
Verify the backup by opening a random selection of files and folders to confirm the copy completed without errors.
Proceed with the upgrade using a copy of the project, not the original. The original remains at the backup location as a fallback.

The backup is essential because if the upgrade produces errors that cannot be resolved, the only recovery path is to discard the upgraded project and restore the backup. A mod developer who skips the backup step and encounters an unrecoverable upgrade error loses the entire project and must re-author every asset from scratch.

Package re-import after upgrade

After upgrading the Unity project to the new version, the Project.unitypackage must be re-imported to replace the previous version's scripts, shaders, and configuration with the new version's equivalents. The re-import ensures that Mod Hook scripts, shader references, and layer configuration match what the new game client expects.

The re-import workflow:

In the upgraded Unity project, open the Asset Store or the Import Package dialog (Assets > Import Package > Custom Package).
Navigate to the game installation directory: Unturned/Bundles/Sources/Project.unitypackage.
Select the file and click Open. Unity displays a list of all assets in the package.
Confirm that all assets are selected (the checkbox at the top of the list should be checked).
Click Import. Unity imports the package and overwrites any existing files with matching paths.
After the import completes, Unity may prompt to restart the Editor if script changes require recompilation. Accept the restart.

For Unity 2018 LTS and later projects, also import ExampleAssets.unitypackage from Extras/Sources/Examples/ to get the latest example content and shaders.

Re-exporting master bundles after upgrade

After the project upgrade and package re-import are complete, every master bundle in the project must be re-exported from the new Unity version. A bundle that was exported from an older Unity version and not re-exported will experience the shader consolidation step at load time if Asset_Bundle_Version is below 3, or will be rejected if Asset_Bundle_Version is 3 and the bundle format does not match the game client's expected format.

The re-export workflow for each master bundle:

Open the Master Bundle Tool (Window > Unturned).
Select the AssetBundle from the dropdown.
Confirm the target export location still contains a valid MasterBundle.dat file with the correct Asset_Bundle_Name and Asset_Prefix.
Confirm Asset_Bundle_Version is set to 3 for Unity 2018 LTS and later bundles.
Enable multi-platform export if this is a release build.
Click Export. Wait for the export to complete. Export times vary with project size.
Verify the exported .masterbundle file was created at the target location and has a plausible file size.
Test the exported bundle in the current game version before uploading to the Workshop.

Common upgrade issues and resolutions

The following diagnostic table documents the most common issues that the cohort has encountered during Unity version upgrades and their documented resolutions.

Symptom	Upgrade transition	Cause	Resolution
Pink/magenta materials on all assets	Any	Shaders not re-imported after upgrade	Re-import `Project.unitypackage` and `ExampleAssets.unitypackage`; confirm shaders are present in the project's Assets folder
Colors too light or dark	5 → 2017, 2017 → 2018	Color Space set to Gamma instead of Linear	Set `Color Space` to `Linear` in `Edit > Project Settings > Player > Other Settings`
Colors still wrong after Color Space fix	Any	sRGB not enabled on textures	Select each texture in the Project Browser; in the Inspector, check `sRGB (Color Texture)`
"Bundle format not supported" error at load time	2017 → 2018, 2018 → 2019	`Asset_Bundle_Version` still set below 3 on a bundle built with the new Unity version	Set `Asset_Bundle_Version 3` in `MasterBundle.dat`
Workshop warning: "This content was uploaded from a newer version"	2017 → 2018	Expected behavior: Workshop content built with Unity 2018+ shows a warning when loaded in Unity 2017 game client	Re-export the mod for the older game version if dual-version support is needed, or document the required game version in the Workshop description
Missing mesh references after upgrade	Any	Mesh files not migrated or re-imported	Re-import models from `.fbx` files; re-assign mesh references in prefabs
Animations no longer import from `.blend` files	2018 → 2019	Unity 2019 dropped support for multiple animations per `.blend` file	Export animations from Blender to `.fbx` format; import `.fbx` into Unity
Devkit foliage renders as solid color	2017 → 2018	Material instancing disabled by default in newer Unity versions	Enable `Instancing` flag on foliage materials in the Inspector
Mod scripts (hooks) do not appear in component menu	Any	`Project.unitypackage` not re-imported after upgrade	Re-import `Project.unitypackage`; confirm the Unturned components menu is populated in the Unity Editor
Linux server crashes on mod load	2017 → 2018	32-bit Linux depot removed; mod bundles built for 32-bit target	Rebuild bundles targeting 64-bit; update server to 64-bit Linux dedicated server depot
Exported bundle size much larger than before	Any	Multi-platform export enabled for a development build	Disable multi-platform export during development; enable only for release builds
Game hangs on loading screen with mod installed	Any	Bundle references point to assets that do not exist in the upgraded project	Run the game with `-ValidateAssets` flag; check the log for missing asset warnings; re-assign missing references in Unity
Master Bundle Tool does not appear in Window menu	Any	Tool scripts not copied to `Assets/Editor/`	Copy all files from `Unturned/Bundles/Sources/Tools/` into the project's `Assets/Editor/` directory

Diagnostic flowchart: troubleshooting a post-upgrade bundle

The diagnostic flowchart above provides the triage entry point for post-upgrade bundle failures. Each branch traces to a specific resolution that addresses the documented cause.

Step-by-step: full Unity version upgrade checklist

The following checklist consolidates every step in the upgrade process across all Unity version transitions into a single ordered procedure that the cohort uses when upgrading mod projects.

[ ] Confirm the target Unity version from the official SDG documentation or game changelog
[ ] Install the target Unity Editor version through Unity Hub
[ ] Back up the entire mod project folder to a separate location
[ ] Open a copy of the project in the new Unity Editor version
[ ] Accept the project upgrade prompt in Unity
[ ] Import the updated Project.unitypackage from the game's Bundles/Sources/ directory
[ ] Import ExampleAssets.unitypackage from Extras/Sources/Examples/ (for Unity 2018 LTS and later)
[ ] Copy the Master Bundle Tool scripts to Assets/Editor/
[ ] Re-import all model files in .fbx format (re-export from Blender if previously using .blend direct import)
[ ] Verify shaders are present and materials are assigned correctly (no pink materials in the Scene or Game view)
[ ] Enable Instancing on foliage materials (for Unity 2018 LTS and later)
[ ] Set Color Space to Linear in Player settings
[ ] Confirm Asset_Bundle_Version is set to 3 in every MasterBundle.dat file (for Unity 2018 LTS and later)
[ ] Confirm Asset_Bundle_Name and Asset_Prefix are correct in every MasterBundle.dat
[ ] Re-assign AssetBundle names to project folders if they were lost during the upgrade
[ ] Re-export every master bundle from the Master Bundle Tool
[ ] Enable multi-platform export for release builds only
[ ] Copy exported bundles to the mod's target folder in the game installation
[ ] Test in the current game version with -ValidateAssets enabled
[ ] Test in both singleplayer and on a dedicated server (if the mod is multiplayer)
[ ] Upload updated content to the Steam Workshop

Compatibility between Unturned versions and Unity versions

The following table provides a quick reference for which Unity Editor version corresponds to which Unturned™ game version. Mod developers should build content with the Unity version that matches their target game branch.

Unturned game version	Beta branch name	Unity Editor version	Asset_Bundle_Version	Status
Pre-2017 (legacy)	`unity-5.5`	Unity 5.5 LTS	Not set	Archival only. Mods from this era are incompatible with all later versions.
2017-era	`unity-2017.4`	Unity 2017.4 LTS	Not set or < 3	Backward-compatibility beta. Current mods should not target this version unless dual-version support is required.
2018-era	`unity-2018`	Unity 2018.4 LTS	3	Backward-compatibility beta. Transitional version with the shader consolidation change.
2019-era (current)	(main branch)	Unity 2019.4 LTS	3	Current target for all new mod development.

Beta branch compatibility

A mod built for the main game branch (Unity 2019 LTS) will not load correctly on beta branch game clients. If a mod must support multiple game versions, the mod developer must either maintain separate Workshop items for each target version or must build the mod for the oldest supported version and accept the backward-compatibility behavior (shader consolidation at load time). The cohort recommendation for Workshop mods that target the broadest player base is to build for the current main branch and to document the required game version in the Workshop description, because the beta branches exist for archival and compatibility-testing purposes and are not the primary player experience.

Worked example: upgrading an item mod from Unity 2017 to Unity 2019

The following example traces a hypothetical item mod (MyCustomGun) through the complete upgrade path from Unity 2017.4 LTS to Unity 2019.4 LTS, covering both the 2017-to-2018 and 2018-to-2019 transitions. This example consolidates the cumulative steps that a mod developer performs when upgrading a mod across two major version boundaries.

The starting state: the mod was built in Unity 2017.4 LTS, has a MasterBundle.dat with Asset_Bundle_Version not set, uses All_Shaders.unitypackage for shaders, and the gun prefab includes a .blend file imported directly into Unity for the weapon mesh with embedded animations.

Step 1: 2017 to 2018. The developer installs Unity 2018.4 LTS, backs up the project, and opens a copy in Unity 2018.4. The project upgrade prompt appears; the developer accepts. After the upgrade, the developer imports the updated Project.unitypackage and the new ExampleAssets.unitypackage. The developer enables Instancing on the gun's foliage material (a vegetation attachment on the weapon). The developer sets Color Space to Linear in Player settings. The developer updates MasterBundle.dat to set Asset_Bundle_Version 3. The developer re-exports the master bundle and confirms the gun loads correctly in the Unity 2018 game client.

Step 2: 2018 to 2019. The developer installs Unity 2019.4 LTS, backs up the project again, and opens a copy in Unity 2019.4. The project upgrade prompt appears; the developer accepts. The developer re-imports the updated Project.unitypackage. The .blend file that was previously imported directly into Unity no longer imports its animations. The developer opens the .blend file in Blender, exports the mesh and animations to .fbx format, and imports the .fbx file into Unity. The developer reassigns the gun prefab's mesh reference to point to the .fbx-imported model. The developer re-exports the master bundle. The developer tests the gun in the Unity 2019 game client and confirms the model renders, the animations play, and the weapon fires correctly.

The complete upgrade spans approximately two hours for a single-item mod, including testing time. Multi-item mod projects with dozens of prefabs scale proportionally, and the cohort practice for large mod projects is to batch-upgrade all prefabs in a single session with a written checklist.

Best practices

Back up the entire project folder before every Unity version upgrade. The upgrade is one-way and irreversible.
Install the exact Unity Editor version specified in the official SDG documentation, not the latest patch in the same LTS family. Minor version mismatches can produce subtle incompatibilities that are difficult to diagnose.
Re-import Project.unitypackage and ExampleAssets.unitypackage after every upgrade, even if the previous version's imports appear to be present. The game client expects the scripts, shaders, and configuration that match its own build, and a stale import produces errors that are indistinguishable from upgrade corruption.
Set Asset_Bundle_Version 3 in every MasterBundle.dat for Unity 2018 LTS and later bundles. Leaving the field unset triggers the shader consolidation step, which is unnecessary for current-version bundles and can produce incorrect shader assignments.
Export models and animations to .fbx exchange format rather than importing .blend files directly into Unity. The .fbx workflow is version-independent and avoids the Blender-version compatibility issues that arise when the Unity Editor's Blender importer does not match the Blender version that authored the file.
Disable multi-platform export during development iteration. Multi-platform exports add significant build time because Unity must compile shader variants for every target platform. Enable multi-platform only for release candidates and final Workshop submissions.
Run the game with -ValidateAssets enabled after every upgrade to catch missing mesh references, broken prefab links, and other asset integrity issues before they surface as player-reported bugs.
Test upgraded mods on a dedicated server before uploading to the Workshop, even for mods that previously functioned correctly on dedicated servers. The platform target changes between Unity versions (32-bit removal, headless server changes) can affect mod behavior in server environments that singleplayer testing does not reveal.

The multi-platform export: when to use it

The multi-platform export option in the Master Bundle Tool compiles shader variants for every target platform that Unturned™ supports: Windows (DirectX), macOS (Metal), and Linux (Vulkan/OpenGL). A bundle exported without multi-platform support contains shader variants for the development platform only, which is typically Windows. Bundles exported with multi-platform support contain shader variants for all platforms, which increases the exported bundle size and the export time but ensures that the mod's materials render correctly on macOS and Linux clients.

The trade-off is primarily one of development iteration speed versus release compatibility. A single-platform export (Windows only) completes in a fraction of the time of a multi-platform export because Unity only needs to compile one set of shader variants. During active development, when the mod developer is exporting the bundle dozens of times per session to test incremental changes, the time savings from single-platform export is substantial. For a release candidate or a final Workshop submission, multi-platform export is essential because a significant portion of the Unturned™ player base uses macOS or Linux, and mods that render with pink materials on those platforms receive negative Workshop ratings and support requests.

The cohort practice for 57 Studios™ mod projects is to export single-platform (Windows) during development, to run a multi-platform export at the release-candidate stage and test the macOS and Linux rendering, and to export multi-platform for the final Workshop submission. The Master Bundle Tool's multi-platform checkbox can be toggled at any time without changing any other project configuration, so the workflow is entirely a matter of checking or unchecking a single box in the tool window.

Understanding the MasterBundle.dat file structure in detail

The MasterBundle.dat file is a plain text configuration file that the game's bundle loader reads when it traverses the mod's folder hierarchy. The file uses the same key-value syntax as other Unturned™ .dat files: one key-value pair per line, with the key and value separated by whitespace. The parser ignores lines that begin with // (comments) and blank lines.

A complete MasterBundle.dat for a current-version mod looks like this:

Asset_Bundle_Name MyModBundle.masterbundle
Asset_Prefix Assets/MyModBundles
Asset_Bundle_Version 3

The Asset_Bundle_Name value must match the filename that the Master Bundle Tool produces when it exports the bundle. If the Tool exports MyModBundle.masterbundle but the .dat file specifies MyModBundle_OLD.masterbundle, the game will look for the wrong file and the bundle will not load. The filename match is case-sensitive on Linux servers, so use consistent casing throughout the project.

The Asset_Prefix value is the Unity project folder path that was assigned to the AssetBundle in the Unity Editor. When the game attempts to load an asset (for example, an item at MyModBundles/Items/Guns/MyGunItem.dat), it strips the Asset_Prefix from the asset's Unity path to determine the bundle-internal path. If the Asset_Prefix is Assets/MyModBundles and the asset's Unity path is Assets/MyModBundles/Items/Guns/MyGunItem, the bundle-internal path becomes Items/Guns/MyGunItem. The game then looks up that path inside the bundle to find the asset. If the Asset_Prefix is incorrect, every asset in the bundle will fail to resolve, and the mod will load with no visible content.

MasterBundle.dat location rules

The MasterBundle.dat file must be placed in the folder that contains the exported .masterbundle file. The game checks each folder in the mod's hierarchy for a MasterBundle.dat file. If found, the game assumes all sub-folders under that folder should be loaded from the master bundle. If no MasterBundle.dat is found in a folder, the game continues traversing upward to the parent folder and checks again. This means a MasterBundle.dat at the mod's root folder affects every item in the mod, while a MasterBundle.dat in a subfolder affects only the items in that subfolder and below.

Multiple MasterBundle.dat files can coexist in different folders of the same mod, each pointing to a different master bundle. This pattern is used for large mods that have multiple asset bundles (for example, one bundle for items and another for vehicles) to keep individual bundle sizes manageable and to allow partial updates to the mod without re-exporting every bundle.

How the game determines which Unity version a bundle was built with

The game does not read a Unity version string from the bundle file directly. Instead, it infers the Unity version from the bundle's internal format and from the Asset_Bundle_Version field in MasterBundle.dat. When Asset_Bundle_Version is not set or is below 3, the game assumes the bundle was built with an older Unity version and attempts shader consolidation. When Asset_Bundle_Version is 3, the game assumes the bundle was built with the current Unity version and loads the shaders as-is.

This inference mechanism means that a bundle built with Unity 2019 LTS but with Asset_Bundle_Version mistakenly not set (or set to a value below 3) will undergo shader consolidation unnecessarily. The consolidation may succeed (if the shader references in the bundle happen to match the game's shader consolidation table) or may produce incorrect results (if the bundle uses custom shaders that the consolidation table does not recognize). The cohort recommendation is to always set Asset_Bundle_Version 3 for bundles built with Unity 2018 LTS or later, regardless of whether shader consolidation would succeed, because the consolidation step adds load time and introduces a failure mode that is avoided entirely by disabling it.

Working with mods that target multiple game versions

Some mod projects choose to support multiple Unturned™ game versions simultaneously, typically the current main branch and one or two recent beta branches. Supporting multiple versions requires maintaining separate sets of exported bundles, because each game version expects bundles built with its corresponding Unity Editor version.

The cohort-validated multi-version support strategy is:

Maintain a separate Unity project for each target Unity version. Each project is a copy of the canonical project, upgraded to the target Unity version and with version-specific adjustments applied.
Export bundles from each project independently, placing the version-specific bundles in version-specific folders within the mod's distribution.
Use the Steam Workshop's branch or version system (if available) to deliver different bundle sets to players on different game versions, or ship a single mod package that includes bundles for all supported versions and instructs the game's loader to select the correct bundle set based on the detected game version.

Multi-version support approximately doubles the maintenance burden for each additional target version, because every change to the mod's content must be applied, exported, and tested in every target Unity project. The cohort recommendation for most Workshop mods is to target only the current main game branch and to document the required game version in the Workshop description, because the beta branch player population is a small fraction of the main branch population and the maintenance cost of multi-version support is rarely justified by the additional audience.

Post-upgrade validation workflow

After completing a Unity version upgrade and re-exporting the bundles, the following validation workflow catches the most common post-upgrade issues before the mod is distributed to players.

Launch the game with the -ValidateAssets command-line flag. This flag enables the slow asset checks that are disabled by default, including missing mesh detection and broken prefab reference detection. Add -ValidateAssets to the game's launch options in Steam (right-click Unturned™ in the Steam library, select Properties, and add it to the Launch Options field).
Load the mod in singleplayer. Spawn every item, vehicle, and object that the mod provides. For each spawn, confirm the model appears, the materials are correct (no pink surfaces), the animations play, and the item functions as expected.
If the mod includes custom maps or level content, load the map and traverse the entire playable area. Confirm props, terrain, and interactive objects appear correctly.
Check the game's log file (Client.log in the Logs folder) for warnings or errors related to the mod's content. Search for the mod's asset names and IDs. Any "missing asset," "failed to load," or "shader not found" messages require investigation.
If the mod is intended for multiplayer, deploy it to a dedicated server and connect with a client. Confirm that all content appears correctly for the client and that server-authoritative behavior (spawning, damage, interaction) functions as expected.
If the mod uses custom shaders, test the mod on a macOS or Linux client (or ask a community member with that platform to test) to confirm that the shaders compile correctly on non-Windows platforms.

The validation workflow above takes thirty to sixty minutes for a typical mod and catches the vast majority of post-upgrade issues. The cohort practice is to complete the validation workflow before uploading the updated mod to the Steam Workshop, because post-publication hotfixes create a negative impression for subscribers who experience bugs in the initial update.

Frequently asked questions

How do I know which Unity version the current game requires?

The required Unity version is stated on the landing page of the official Smartly Dressed Games modding documentation and is announced in the game's update changelog when a Unity version change occurs. The Project.unitypackage file distributed with the game client also contains Unity version metadata. If all of these sources are ambiguous, the Steam community hub for Unturned™ typically surfaces the required version in pinned announcements following a Unity upgrade.

Can I skip a Unity version and upgrade directly to the latest?

Yes, but the project must be opened in each intermediate Unity version sequentially. Unity supports opening a project from an older major version in a newer major version, but skipping multiple major versions (e.g., opening a Unity 5 project in Unity 2019) may produce upgrade errors that are not recoverable. The cohort recommendation is to upgrade one major version at a time (5 to 2017, then 2017 to 2018, then 2018 to 2019), testing at each step, rather than attempting a single multi-version leap.

Do I need to re-export every bundle after a Unity upgrade?

Yes. Every master bundle and individual .unity3d bundle must be re-exported from the new Unity Editor version. Bundles exported from older Unity versions may function through the shader consolidation system if Asset_Bundle_Version is below 3, but this is a backward-compatibility convenience for players, not a substitute for proper re-export. The shader consolidation step adds load time and can produce incorrect results for custom shaders. Re-exporting from the correct Unity version eliminates the consolidation step and ensures full compatibility.

What happens to Workshop subscribers when I update a mod for a new Unity version?

When you upload a mod built with a new Unity version to the Steam Workshop, subscribers who are on the matching game version receive the update and can use the mod normally. Subscribers who are on an older game version (e.g., on a beta branch) will see a warning message when loading the mod, indicating that the content was uploaded from a newer version and may not function correctly. The mod may or may not actually function on the older version depending on the specific changes between Unity versions. The cohort recommendation is to document the required game version in the Workshop description and to maintain separate Workshop items if dual-version support is needed.

Can I keep my old Unity version installed alongside the new one?

Yes. Unity Hub supports installing and managing multiple Unity Editor versions side by side. The cohort practice for active mod developers is to keep the previous LTS version installed during the transition period so that existing mods can still be built and tested for the older game version while new mods are migrated to the new version. Once all mods have been migrated and the older game version's beta branch usage has declined, the older Unity Editor version can be uninstalled to free disk space.

What is the purpose of the Asset_Bundle_Version field?

The Asset_Bundle_Version field controls whether the game performs shader consolidation on the bundle at load time. When set below 3 (or not set), the game attempts to replace older shader references in the bundle with the current game's shader equivalents, which allows bundles built for older Unity versions to function on newer game clients. When set to 3, shader consolidation is disabled and the bundle's shader references are used as-is, which is the correct configuration for bundles built with the matching Unity version. The field was introduced at the Unity 2017 to 2018 transition.

Why are my materials pink after upgrading?

Pink (magenta) materials are Unity's default "missing shader" visual. The cause after a Unity version upgrade is that the shader files from the new Project.unitypackage were not re-imported, so the materials are referencing shaders that do not exist in the upgraded project. Re-import Project.unitypackage and ExampleAssets.unitypackage, then confirm each material in the project has a valid shader assigned in the Inspector.

How do I fix devkit foliage that renders as solid blocks after upgrading?

Devkit foliage materials default to instancing disabled in Unity 2018 LTS and later, whereas earlier versions defaulted to instancing enabled. Select the foliage material in the Project Browser, and in the Inspector, check the Enable Instancing checkbox. Rebuild the asset bundle after enabling instancing on all foliage materials.

The Master Bundle Tool scripts are not included in the Project.unitypackage; they must be copied manually from the game installation directory. Navigate to Unturned/Bundles/Sources/Tools/ in the game's installation folder, copy all files from that directory, and paste them into the Unity project's Assets/Editor/ directory. After the copy completes, the Master Bundle Tool appears in Window > Unturned in the Unity Editor.

Can I use a newer Unity LTS version than the one the game requires?

No. The Unity version match between the mod-development environment and the game client is a hard requirement. Building a bundle with a Unity version newer than the game's build version produces a bundle with a format that the older game client cannot read. Building with an older Unity version and relying on shader consolidation is a backward-compatibility convenience that works for some version pairs but is not a supported mod-development workflow. Always build with the exact Unity version specified in the game's documentation.

How long does a Unity version upgrade typically take for a mod project?

The wall-clock time depends primarily on the number of assets in the project and the number of master bundles that must be re-exported. For a single-item mod with one master bundle, the upgrade process (including backup, project upgrade, package re-import, and bundle re-export) typically takes thirty to sixty minutes. For a large mod project with dozens of items, multiple master bundles, and custom shaders, the process can take four to eight hours, primarily due to the re-export time for each bundle. The cohort recommendation for large projects is to allocate a full work session to the upgrade and to use the checklist in this article to track progress.

Appendix A: Unity version upgrade quick-reference card

Transition	Key changes	Critical action	Asset_Bundle_Version
Unity 5 → 2017	Master bundles introduced; Metal graphics for macOS; annual LTS cadence begins	Install master bundle tools; create `MasterBundle.dat` files; re-import shaders from `All_Shaders.unitypackage`	Not set
Unity 2017 → 2018	Shader consolidation control; consolidated packages; 32-bit platforms removed; `-ValidateAssets` flag added	Set `Asset_Bundle_Version 3`; import `ExampleAssets.unitypackage`; enable foliage instancing; remove 32-bit build targets	3
Unity 2018 → 2019	`.blend` animation import removed; minimal other breaking changes	Re-export models and animations to `.fbx`; re-import from `.fbx`; update prefab mesh references	3 (unchanged)
Any → Current	Cumulative: all changes from previous transitions	Follow the full upgrade checklist in this article	3 (for current target)

Appendix B: MasterBundle.dat field reference

Field	Type	Required	Example	Purpose
`Asset_Bundle_Name`	string	Yes	`hawaii.masterbundle`	The filename of the exported master bundle. Must match the filename produced by the Master Bundle Tool exactly. Case-sensitive on Linux.
`Asset_Prefix`	string	Yes	`Assets/MyModBundles`	The Unity project folder path that was assigned as the AssetBundle. The game uses this to match file paths to bundle content.
`Asset_Bundle_Version`	integer	No (defaults to pre-3 behavior)	`3`	Controls shader consolidation. Set to `3` for Unity 2018 LTS and later bundles. Leave unset or below 3 for Unity 2017 LTS bundles to enable backward-compatibility consolidation.

Appendix C: Per-item .dat properties for master bundle control

Property	Scope	Purpose
`Exclude_From_Master_Bundle`	Per `.dat` file	Flag that causes this item to ignore parent master bundles and load from an individual `.unity3d` file instead. Use for items that should remain as standalone bundles.
`Master_Bundle_Override`	Per `.dat` file	Specifies a master bundle name to use instead of the parent folder's default. Use to redirect specific items to a different bundle than the one the folder hierarchy would resolve to.
`Bundle_Override_Path`	Per `.dat` file	Specifies a path within the bundle to use for this item. Allows multiple items to share the same Unity setup (as with vanilla note objects sharing a single model). Can be combined with `Master_Bundle_Override` to reference models from other master bundles.

Appendix D: External references

Resource	URL	Notes
Smartly Dressed Games modding documentation	https://docs.smartlydressedgames.com/en/stable/	Official upgrade documentation in Chapter 13.
Unturned on Steam	https://store.steampowered.com/app/304930/Unturned/	Game page; update changelog notes announce Unity version changes.
Unity Hub	https://unity.com/download	The tool for installing and managing multiple Unity Editor versions side by side.
Unity LTS releases	https://unity.com/releases/lts	Official Unity LTS release archive with download links for every LTS version.
How to Install the Unity Editor	/unity-setup/how-to-install-unity-editor	The prerequisite article covering Unity Editor installation for Unturned mod development.
How to Import the Unturned Project Package	/unity-setup/how-to-import-the-unturned-project-package	The prerequisite article covering `Project.unitypackage` import workflow.
Master Bundle Export	/items/master-bundle-export	The bundling workflow article; covers the Master Bundle Tool export process in detail.

Document history

Version	Date	Author	Notes
1.0	2026-07-26	57 Studios	Initial publication. Complete Unity version upgrade reference covering all transitions (5 to 2017, 2017 to 2018, 2018 to 2019), Asset_Bundle_Version documentation, upgrade checklists, diagnostic tables, multi-platform guidance, MasterBundle.dat reference, shader management, beta branch reference, upgrade timing estimates, FAQ, and appendices.

Cross-references

How to Install the Unity Editor, the prerequisite article; covers Unity Hub and Editor installation for the correct version.
How to Import the Unturned Project Package, the prerequisite article; covers Project.unitypackage import workflow after upgrade.
Unity Project Overview, the previous article in this section; covers the structure of an Unturned Unity project before upgrade.
Master Bundle Export, the Master Bundle Tool and bundling workflow; the export step that follows every upgrade.
Smartly Dressed Games modding documentation, official upgrade documentation, Chapter 13.
Unturned on Steam, game page and update changelog.

Appendix E: Beta branch reference for mod compatibility testing

The following Steam beta branches provide access to older Unturned™ game versions, which are useful for testing whether a mod is compatible with a specific game version or for extracting assets from an older version of the game.

Beta branch name	Unity version	Game version era	Access method
`unity-5.5`	Unity 5.5 LTS	Pre-2017 (legacy)	Steam library → Unturned → Properties → Betas → select `unity-5.5`
`unity-2017.4`	Unity 2017.4 LTS	2017-era	Steam library → Unturned → Properties → Betas → select `unity-2017.4`
`unity-2018`	Unity 2018.4 LTS	2018-era	Steam library → Unturned → Properties → Betas → select `unity-2018`
(none, default)	Unity 2019.4 LTS	Current	Steam library → Unturned → Properties → Betas → select `None`

To switch between beta branches: right-click Unturned™ in the Steam library, select Properties, navigate to the Betas tab, and select the desired branch from the dropdown. Steam will download the version-specific game files. The beta branch download replaces the current game installation, so switching between branches requires a download each time. The cohort practice is to maintain a separate Steam library folder for each beta branch if frequent switching is needed, or to use the beta branches only for one-time compatibility testing and asset extraction.

Appendix F: Common upgrade timings for planning purposes

The following table provides approximate wall-clock times for each phase of the Unity version upgrade process, based on the cohort's experience across mod projects of varying sizes. Times assume a mid-range development workstation with an NVMe SSD and a modern CPU.

Upgrade phase	Single-item mod	Medium mod (10-20 items)	Large mod (50+ items or custom map)
Project backup (file copy)	< 1 minute	1-5 minutes	5-30 minutes
Unity project upgrade (open in new version, accept prompts)	5-15 minutes	10-30 minutes	30-90 minutes
Package re-import (Project.unitypackage + ExampleAssets)	2-5 minutes	5-15 minutes	10-30 minutes
Model re-export to .fbx (if applicable)	5-15 minutes per model	30-60 minutes total	1-4 hours total
Master bundle re-export (single-platform)	2-5 minutes per bundle	5-15 minutes per bundle	15-45 minutes per bundle
Master bundle re-export (multi-platform)	10-20 minutes per bundle	20-60 minutes per bundle	1-3 hours per bundle
In-game testing and validation	15-30 minutes	30-60 minutes	1-2 hours
Total estimated time	40-90 minutes	2-4 hours	4-12 hours

The timings above are estimates. Actual times vary with the specific hardware configuration, the complexity of the mod's assets, and whether the mod uses custom shaders or scripts that require manual adjustment after the upgrade. The cohort recommendation is to allocate the upper end of the estimated range for the first upgrade of a given project and to use the actual times from the first upgrade to plan subsequent upgrades.

Appendix G: Shader management across Unity version upgrades

Shader management is the single most common source of post-upgrade rendering issues. The transition from the separate All_Shaders.unitypackage (Unity 2017 LTS era) to the consolidated ExampleAssets.unitypackage (Unity 2018 LTS and later) changed how shaders are distributed and imported, and mod developers who skip the shader re-import step after an upgrade encounter pink materials, incorrect lighting, and missing transparency effects.

The following table documents the shader package for each Unity version era and the import procedure:

Unity version era	Shader package	Location	Import procedure
Unity 5.5 LTS	`All_Shaders.unitypackage` (separate)	`Unturned/Bundles/Sources/` subdirectory	`Assets > Import Package > Custom Package`, select the file
Unity 2017.4 LTS	`All_Shaders.unitypackage` (separate)	`Unturned/Bundles/Sources/` subdirectory	Same as above
Unity 2018.4 LTS	`ExampleAssets.unitypackage` (consolidated)	`Extras/Sources/Examples/`	`Assets > Import Package > Custom Package`, select the file
Unity 2019.4 LTS	`ExampleAssets.unitypackage` (consolidated)	`Extras/Sources/Examples/`	Same as above

The shader consolidation system that activates when Asset_Bundle_Version is below 3 is a backward-compatibility mechanism, not a replacement for proper shader re-import. Relying on shader consolidation for a mod that uses custom shaders produces unpredictable results because the consolidation table maps only the vanilla shader set. Custom shaders that are not in the consolidation table will be left as references to shaders that do not exist in the current game client, and the materials that reference them will render pink.

The cohort practice for custom-shader mods is:

Maintain the shader source files in the mod project's Assets/ folder, not only in the exported bundle.
After a Unity version upgrade, re-import the shader source files and confirm they compile without errors in the new Unity Editor version. Shader compilation errors appear in the Unity Console and must be resolved before bundle export.
Re-assign the compiled shaders to each material that uses them. Unity sometimes loses shader-to-material assignments during the project upgrade process, and materials that appear correct in the Inspector may reference a stale shader GUID internally.
Re-export the bundle and verify that all materials render correctly in the game before uploading to the Workshop.

Appendix H: Understanding the -ValidateAssets command-line flag

The -ValidateAssets flag is a game launch option that enables slow asset integrity checks that are disabled by default for performance reasons. The flag was introduced in the Unity 2017 to 2018 transition and is the primary diagnostic tool for catching post-upgrade asset problems.

When enabled, -ValidateAssets performs the following additional checks during asset loading:

Scans for missing mesh references: every mesh that a prefab references is verified to exist in the bundle. Missing meshes produce log warnings that identify the prefab and the missing mesh path.
Scans for broken prefab links: every GameObject reference in the bundle's internal hierarchy is verified to resolve to a valid GameObject. Broken links produce log warnings.
Validates material assignments: every material slot on every renderer is verified to reference a valid material.
Validates shader references: every shader that a material references is verified to exist in the bundle or in the game's shader library.

The checks increase asset loading time, particularly for large mods with many prefabs, which is why they are disabled by default. The cohort recommendation is to enable -ValidateAssets during the post-upgrade testing phase and to disable it for normal gameplay and for Workshop subscribers.

To enable the flag: right-click Unturned™ in the Steam library, select Properties, and in the Launch Options field, enter -ValidateAssets. Launch the game normally. The flag takes effect on the next game launch and persists until removed from the Launch Options field.

How to prepare a mod project for future Unity version upgrades

The cumulative experience of the Unturned™ modding community across four major Unity version transitions has produced a set of defensive project practices that minimize the friction of future upgrades. These practices do not eliminate the upgrade effort but reduce the number of manual corrections required after an upgrade and the number of post-upgrade bugs that surface during testing.

Use exchange formats for all imported assets. Import models and animations as .fbx files rather than as .blend files directly. The .fbx format is an industry-standard exchange format that is independent of any specific 3D authoring tool's version, and Unity's .fbx importer is more stable across Unity version upgrades than any tool-specific importer. When a Unity version upgrade drops support for a tool-specific import format (as happened with .blend animation import in Unity 2019), mods that already use .fbx are unaffected.

Maintain source assets outside the Unity project. Store the Blender files, Photoshop files, Substance files, and other authoring-format assets in a separate folder outside the Unity project directory. The Unity project contains only the exchange-format imports (.fbx, .png, .tga). When a Unity version upgrade requires re-importing assets (as happened with .blend to .fbx migration), the source assets remain available in their authoring tools and can be re-exported to the required exchange format without data loss.

Document custom shader sources and dependencies. If the mod uses custom shaders, maintain the shader source files (.shader, .cginc, .hlsl) in a version-controlled directory within the project and document which materials depend on which shaders. When a Unity version upgrade changes the shader compilation pipeline, the documented dependencies allow the developer to identify every material that requires shader reassignment without hunting through the project manually.

Version-control the Unity project with Git or equivalent. A version-controlled project can be rolled back to its pre-upgrade state if the upgrade produces unrecoverable errors. The version-control history also provides a record of which files changed during the upgrade, which is diagnostically useful when a specific asset breaks after the upgrade and the developer needs to identify what the upgrade process changed about that asset.

Keep the previous Unity Editor version installed. Unity Hub's multi-version management makes it practical to keep the previous LTS version installed alongside the new one. This allows the developer to open the backup copy of the project in the old version to verify behavior or to extract configuration values that the upgrade process may have altered, without needing to reinstall the old Unity version.

Build and test on all target platforms before the Workshop submission. A Unity version upgrade can change shader compilation behavior for non-Windows platforms in ways that are not visible during Windows-only development. The cohort practice is to perform at least one multi-platform build and test cycle (or to request testing from a community member on macOS or Linux) before uploading the updated mod to the Workshop.

Historical note: why the upgrade documentation is structured this way

The official SDG documentation for Unity version upgrades (Chapter 13) is organized chronologically by upgrade transition rather than by topic, and this article follows the same structure. The chronological organization reflects the fact that each upgrade transition is a distinct event with its own set of changes, and a mod developer upgrading from Unity 5 to Unity 2019 must understand the changes from each intermediate transition because the project must be opened in each intermediate Unity version sequentially.

The source documentation describes some of its own sections as "admittedly rather old" and notes that certain information "should eventually be moved to a better spot." These annotations indicate that the upgrade documentation is a living document that is revised as the game's toolchain evolves, and sections marked as archival are preserved for the benefit of developers working with older mod projects rather than as guidance for current development. This article presents the archival sections with their archival context preserved, so that a developer working with an older mod project can trace the complete upgrade path without needing to consult multiple versions of the official documentation.

Authoring new mods after an upgrade: restarting from the new version

When a game update moves Unturned™ to a new Unity version, mod developers who are starting new mod projects rather than upgrading existing ones can begin directly with the new Unity version. The process is simpler than upgrading an existing project because there is no legacy content to migrate and no backup-and-restore cycle to perform. The new-project workflow for the current Unity version is:

Install the current Unity Editor version through Unity Hub.
Create a new Unity project with the correct 3D template and the project name matching the mod's identifier.
Import the Project.unitypackage from the current game version's Bundles/Sources/ directory. This configures layers, imports Mod Hook scripts, and sets up the Unity project for Unturned™ compatibility.
Import ExampleAssets.unitypackage from Extras/Sources/Examples/ to get the current shaders and example content.
Copy the Master Bundle Tool scripts to Assets/Editor/ from the game's Bundles/Sources/Tools/ directory.
Create the AssetBundle folder structure in the Project Browser.
Create or copy MasterBundle.dat files at each bundle target location, with Asset_Bundle_Version set to 3.
Author the mod content (prefabs, materials, textures, animations) and export the master bundles.

A new project started on the current Unity version does not require the .blend-to-.fbx migration, the foliage instancing fix, the Color Space correction, or any of the other upgrade-specific corrections that apply only to projects migrated from older Unity versions. The new project inherits the correct defaults from the Project.unitypackage import, and the only configuration the developer must verify is the MasterBundle.dat content and the Material instancing flags on any foliage materials.

The cohort recommendation for mod developers who maintain both upgraded legacy projects and new projects is to keep the new project's configuration as a reference for correcting the upgraded legacy projects. If a material renders correctly in a new project but incorrectly in an upgraded project, the difference is almost always a residual setting from the upgrade process that the new project's default configuration resolves. Comparing the two projects' Player Settings, Quality Settings, and material Inspector panels side by side identifies the specific setting that the upgrade process did not migrate correctly.

What to do when a game update changes the required Unity version without announcement

On rare occasions, a game update changes the required Unity version without a prominent announcement in the changelog, and the change is discovered when Workshop subscribers report that the mod no longer loads correctly. When this occurs, the diagnostic workflow is:

Check the official Smartly Dressed Games modding documentation landing page for the stated required Unity version. The documentation is typically updated within a day of a game version change.
Check the game's Project.unitypackage file in the installation directory. The Unity version metadata in the package file reveals the version the package was exported from.
Compare the discovered version against the developer's current Unity Editor version. If they differ, the game has updated its required Unity version.
Install the new required Unity version through Unity Hub.
Follow the upgrade checklist in this article, treating the change as a one-version upgrade (e.g., 2018 to 2019) and applying the documented steps for that specific transition.

The cohort practice for staying ahead of unannounced version changes is to monitor the official SDG documentation landing page and the game's Steam community hub announcements after each game update, even for updates whose changelog does not explicitly mention Unity version changes.

How to verify that an upgraded bundle loads correctly

After completing the upgrade process and re-exporting the master bundle, the following targeted tests verify that the upgrade was successful and that the bundle functions correctly in the current game version. These tests are faster than a full validation pass and should be run immediately after export to catch obvious problems before investing time in detailed testing.

Bundle file check. Verify the exported .masterbundle file exists at the correct path and has a non-zero file size. A zero-byte bundle file indicates the Master Bundle Tool encountered an error during export that did not produce a visible error message.
Single-item spawn test. Launch the game, spawn one item from the mod using @give <itemID>, and confirm the item appears in the player's inventory with the correct name and icon.
Model render test. Equip or place the spawned item and confirm the 3D model renders correctly. Look for pink materials (missing shaders), invisible meshes (missing prefab references), or incorrect scale (model import scaling issues).
Functionality test. Test one core function of the mod: fire the gun, swing the melee weapon, drive the vehicle, interact with the barricade. Confirm the core functionality works as expected.
Log check. Open the game's log file (Client.log) and search for the mod's item IDs or asset names. Look for "error," "failed," "missing," or "shader" messages. Any such messages require investigation before the mod is distributed.
Quick server test (if multiplayer). Deploy the bundle to a test dedicated server, connect with a client, and confirm the mod content appears correctly for the client.

These six tests can be completed in ten to fifteen minutes for a single-item mod and catch the most common upgrade problems (shader issues, prefab reference breaks, export tool errors) before the developer invests time in the full validation workflow documented earlier in this article.

Cross-version testing: verifying backward compatibility

When a mod developer maintains a mod that supports multiple Unturned™ game versions (both the current main branch and one or more beta branches), the upgrade process must include cross-version testing to confirm that the re-exported bundles function correctly on every target game version. The cross-version testing workflow is:

Export one set of bundles from the current Unity version for the main game branch.
If supporting an older game version, export a separate set of bundles from the older Unity version (using the older Unity project that was backed up before upgrade) for the beta branch.
Install the main branch of the game through Steam (no beta selected) and test the main-branch bundles.
Switch to the target beta branch through Steam's Betas tab, wait for the download to complete, and test the beta-branch bundles.
Confirm that both bundle sets function correctly on their respective game versions.

Cross-version testing approximately doubles the testing time for each supported game version, because each bundle set must be tested independently in its target game environment. The cohort recommendation for mod developers who are considering multi-version support is to estimate the additional testing time and to decide whether the beta branch player population justifies the effort. For most Workshop mods, targeting only the main branch and documenting the required game version is the appropriate trade-off.

Documentation references within the game files

Several game files distributed with Unturned™ contain internal documentation relevant to Unity version upgrades. These files are located in the game's installation directory and are readable with any text editor.

File	Location	Content
`MasterBundle.dat` (example)	`Unturned/Bundles/Sources/` or mod bundle directories	Template and example `MasterBundle.dat` configuration with all supported fields documented inline.
`Project.unitypackage`	`Unturned/Bundles/Sources/`	The Unity project package containing scripts, shaders, and layer configuration for the current Unity version.
`ExampleAssets.unitypackage`	`Extras/Sources/Examples/`	Consolidated example content including shaders, prefabs, and materials (Unity 2018 LTS and later).
`All_Shaders.unitypackage`	`Unturned/Bundles/Sources/` subdirectory	Shader package for Unity 2017 LTS projects (superseded by `ExampleAssets.unitypackage` in later versions).
Master Bundle Tool scripts	`Unturned/Bundles/Sources/Tools/`	The C# scripts that implement the Master Bundle Tool; copy to `Assets/Editor/` in the Unity project.

The cohort recommendation is to browse these files before beginning an upgrade, because they contain the canonical field names, expected values, and configuration templates that the upgrade process references. The MasterBundle.dat example file in particular is a useful template for creating new MasterBundle.dat files when upgrading a project from a pre-master-bundle Unity version or when restructuring a mod's bundle layout.

Differences between upgrading a personal mod and upgrading a team mod

When a mod project is maintained by multiple developers (a team or cohort), the Unity version upgrade process carries additional coordination requirements beyond the technical steps documented in this article. The following practices are the cohort-validated approach for team-based mod upgrades:

Designate one developer as the upgrade lead. The lead performs the upgrade on their workstation first, documents every step and every issue encountered, and produces an upgrade runbook before the rest of the team upgrades.
The upgrade lead verifies the upgraded project against the full validation checklist and confirms all tests pass before the team upgrades their copies.
Each team member upgrades their local copy of the project following the lead's runbook. The runbook captures version-specific issues that may not appear in the general upgrade documentation.
After all team members have upgraded, perform a cross-workstation bundle comparison: export the same master bundle from two different workstations and confirm the bundles are byte-identical or functionally equivalent. Differences in bundle output between workstations indicate a configuration discrepancy that must be resolved.
Update the project's version control repository with the upgraded project files. Include the upgrade runbook in the repository so that future team members or future upgrades can reference it.

The team coordination overhead adds approximately fifty percent to the total upgrade time but eliminates the scenario in which different team members produce different bundle output from nominally identical projects, which is a recurring source of "it works on my machine" bugs during team mod development.

Recovering from a failed Unity version upgrade

If the upgrade process fails partway through -- the project opens but produces compilation errors, assets are missing, the Master Bundle Tool does not function, or the exported bundle causes the game to crash -- the recovery path depends on the point of failure and whether a backup was made before the upgrade.

Recovery with backup (recommended):

Close the Unity Editor.
Delete the upgraded project folder entirely.
Restore the backup copy of the pre-upgrade project.
Re-attempt the upgrade using the diagnostic information gathered from the failed attempt. If the failure was caused by a specific asset (a shader that did not compile, a prefab that broke), address that asset before re-attempting the upgrade.
If the failure recurs, upgrade the project to an intermediate Unity version first, verify that the intermediate version loads correctly, and then upgrade from the intermediate version to the target version.

Recovery without backup (last resort):

Create a new Unity project in the target Unity version.
Import Project.unitypackage and ExampleAssets.unitypackage into the new project.
Manually copy the mod's asset files (prefabs, materials, textures, meshes, .dat configurations) from the failed upgraded project into the new project.
Re-assign AssetBundle names to the project folders.
Re-create MasterBundle.dat files.
Re-export the master bundles and test.

This "clean project" recovery path is time-consuming because every asset reference must be manually verified, but it produces a project that is guaranteed to have the correct default configuration for the target Unity version, which eliminates configuration-inheritance problems that are the most common cause of failed upgrades.

Document history

Version	Date	Author	Notes
1.0	2026-07-26	57 Studios	Initial publication. Complete Unity version upgrade reference covering all transitions (5 to 2017, 2017 to 2018, 2018 to 2019), Asset_Bundle_Version documentation, upgrade checklists, diagnostic tables, multi-platform guidance, MasterBundle.dat reference, shader management, beta branch reference, upgrade timing estimates, FAQ, and appendices.

Cross-references

How to Install the Unity Editor, the prerequisite article; covers Unity Hub and Editor installation for the correct version.
How to Import the Unturned Project Package, the prerequisite article; covers Project.unitypackage import workflow after upgrade.
Unity Project Overview, the previous article in this section; covers the structure of an Unturned Unity project before upgrade.
Master Bundle Export, the Master Bundle Tool and bundling workflow; the export step that follows every upgrade.
Smartly Dressed Games modding documentation, official upgrade documentation, Chapter 13.
Unturned on Steam, game page and update changelog.

Upgrading Unity Version ​

Who this article is for ​

Understanding Unity version compatibility in Unturned ​

Asset Bundle Version: the shader consolidation control ​

Asset_Bundle_Version compatibility table ​

Unity 5 LTS to 2017 LTS migration ​

Reasons for the upgrade ​

Master bundles: the new export format ​

Installing the master bundle tools ​

The MasterBundle.dat configuration file ​

Shader import for Unity 2017 LTS ​

Upgrading a Unity 5 project to Unity 2017 LTS ​

Common Unity 2017 LTS upgrade issues ​

Unity 2017 LTS to 2018 LTS migration ​

Asset bundle backward compatibility ​

Asset validation ​

Consolidated Unity packages ​

Logging and server console changes ​

Workshop compatibility ​

Platform changes ​

Upgrading a Unity 2017 LTS project to Unity 2018 LTS ​

Unity 2018 LTS to 2019 LTS migration ​

Animation import changes ​

Upgrading a Unity 2018 LTS project to Unity 2019 LTS ​

Determining the current required Unity version ​

Project backup before upgrade ​

Package re-import after upgrade ​

Re-exporting master bundles after upgrade ​

Common upgrade issues and resolutions ​

Diagnostic flowchart: troubleshooting a post-upgrade bundle ​

Step-by-step: full Unity version upgrade checklist ​

Compatibility between Unturned versions and Unity versions ​

Worked example: upgrading an item mod from Unity 2017 to Unity 2019 ​

Best practices ​

The multi-platform export: when to use it ​

Understanding the MasterBundle.dat file structure in detail ​

MasterBundle.dat location rules ​

How the game determines which Unity version a bundle was built with ​

Working with mods that target multiple game versions ​

Post-upgrade validation workflow ​

Frequently asked questions ​

How do I know which Unity version the current game requires? ​

Can I skip a Unity version and upgrade directly to the latest? ​

Do I need to re-export every bundle after a Unity upgrade? ​

What happens to Workshop subscribers when I update a mod for a new Unity version? ​

Can I keep my old Unity version installed alongside the new one? ​

What is the purpose of the Asset_Bundle_Version field? ​

Why are my materials pink after upgrading? ​

How do I fix devkit foliage that renders as solid blocks after upgrading? ​

What do I do if the Master Bundle Tool does not appear in the Window menu? ​

Can I use a newer Unity LTS version than the one the game requires? ​

How long does a Unity version upgrade typically take for a mod project? ​

Appendix A: Unity version upgrade quick-reference card ​

Appendix B: MasterBundle.dat field reference ​

Appendix C: Per-item .dat properties for master bundle control ​

Appendix D: External references ​

Document history ​

Cross-references ​

Appendix E: Beta branch reference for mod compatibility testing ​

Appendix F: Common upgrade timings for planning purposes ​

Appendix G: Shader management across Unity version upgrades ​

Appendix H: Understanding the -ValidateAssets command-line flag ​

How to prepare a mod project for future Unity version upgrades ​

Historical note: why the upgrade documentation is structured this way ​

Authoring new mods after an upgrade: restarting from the new version ​

What to do when a game update changes the required Unity version without announcement ​

How to verify that an upgraded bundle loads correctly ​

Cross-version testing: verifying backward compatibility ​

Documentation references within the game files ​

Differences between upgrading a personal mod and upgrading a team mod ​

Recovering from a failed Unity version upgrade ​

Document history ​

Cross-references ​

Upgrading Unity Version

Who this article is for

Understanding Unity version compatibility in Unturned

Asset Bundle Version: the shader consolidation control

Asset_Bundle_Version compatibility table

Unity 5 LTS to 2017 LTS migration

Reasons for the upgrade

Master bundles: the new export format

Installing the master bundle tools

The MasterBundle.dat configuration file

Shader import for Unity 2017 LTS

Upgrading a Unity 5 project to Unity 2017 LTS

Common Unity 2017 LTS upgrade issues

Unity 2017 LTS to 2018 LTS migration

Asset bundle backward compatibility

Asset validation

Consolidated Unity packages

Logging and server console changes

Workshop compatibility

Platform changes

Upgrading a Unity 2017 LTS project to Unity 2018 LTS

Unity 2018 LTS to 2019 LTS migration

Animation import changes

Upgrading a Unity 2018 LTS project to Unity 2019 LTS

Determining the current required Unity version

Project backup before upgrade

Package re-import after upgrade

Re-exporting master bundles after upgrade

Common upgrade issues and resolutions

Diagnostic flowchart: troubleshooting a post-upgrade bundle

Step-by-step: full Unity version upgrade checklist

Compatibility between Unturned versions and Unity versions

Worked example: upgrading an item mod from Unity 2017 to Unity 2019

Best practices

The multi-platform export: when to use it

Understanding the MasterBundle.dat file structure in detail

MasterBundle.dat location rules

How the game determines which Unity version a bundle was built with

Working with mods that target multiple game versions

Post-upgrade validation workflow

Frequently asked questions

How do I know which Unity version the current game requires?

Can I skip a Unity version and upgrade directly to the latest?

Do I need to re-export every bundle after a Unity upgrade?

What happens to Workshop subscribers when I update a mod for a new Unity version?

Can I keep my old Unity version installed alongside the new one?

What is the purpose of the Asset_Bundle_Version field?

Why are my materials pink after upgrading?

How do I fix devkit foliage that renders as solid blocks after upgrading?

What do I do if the Master Bundle Tool does not appear in the Window menu?

Can I use a newer Unity LTS version than the one the game requires?

How long does a Unity version upgrade typically take for a mod project?

Appendix A: Unity version upgrade quick-reference card

Appendix B: MasterBundle.dat field reference

Appendix C: Per-item .dat properties for master bundle control

Appendix D: External references

Document history

Cross-references

Appendix E: Beta branch reference for mod compatibility testing

Appendix F: Common upgrade timings for planning purposes

Appendix G: Shader management across Unity version upgrades

Appendix H: Understanding the -ValidateAssets command-line flag

How to prepare a mod project for future Unity version upgrades

Historical note: why the upgrade documentation is structured this way

Authoring new mods after an upgrade: restarting from the new version

What to do when a game update changes the required Unity version without announcement

How to verify that an upgraded bundle loads correctly

Cross-version testing: verifying backward compatibility

Documentation references within the game files

Differences between upgrading a personal mod and upgrading a team mod

Recovering from a failed Unity version upgrade

Document history

Cross-references