3.28.0.0 Upgrade Guide

Modding info on updating workshop content to 3.28.0.0.

Unity 2017.4 LTS

Why does this guide exist? Unturned has updated from Unity 5.5 to Unity 2017.4 LTS, which means older .unity3d files will need updating to the new engine version.

To make the update process easier there's a new bundling feature: Master Bundles
Further detailed below, this tool will allow you to export all your bundles at once rather than as individual .unity3d files. I've transitioned all of the vanilla content along with Hawaii and Greece to this new system, and Vilespring was kind enough to transition France.

The primary reasons for this engine upgrade are stability related. 5.5 released back at the end of 2016 prior to Unity's focus on improving stability, whereas 2017.4 will be getting patches for another year. Quite a few longtime bugs are fixed in this new version, and as a result I've been able to clean up some workarounds and improve performance in a few areas. Apple has also decided to deprecate OpenGL support, so it's important to have 2017.4's Metal integration.

Master Bundles

Difference between .masterbundle and old .unity3d:

Rather than exporting each bundle to an individual .unity3d asset bundle, you can export multiple bundles into a combined .masterbundle. It's more efficient both time and performance wise. Note: You don't have to use masterbundles, it can be easier to iterate using the .unity3d bundles and enable/disable the masterbundle as-needed.

This is really how it should have been from the first place. If the game detects a master bundle file, it will load bundles from sub-directories using their relative folder path. To help explain, here's an example:

MyModBundles / Items / Gun / Gun.dat
If MyModBundles contains a master bundle, it will try to load all of the Unity files using the relative path /Items/Gun. This means it's important for the .dat folders and Unity folders to line up 1:1.

Installing the files:

Copy all of the files from Unturned/Bundles/Sources/Tools to YourUnityProject/Assets/Editor. MasterBundleTool will now be available from Window > Unturned.

Most shaders used by the vanilla game are now available as a unity package in Unturned/Bundles/Sources/Complete_Packages/All_Shaders.unitypackage. Using them improves compatibility with the base game content.

Exporting from Unity:

Begin by selecting a folder within the Unity Project Browser that contains your bundles, and assigning it to an AssetBundle from the Unity Inspector. Most of the vanilla bundles are in an assetbundle called "core.masterbundle", and map-specific bundles are in assetbundles named like "hawaii.masterbundle" or "france.masterbundle".

Open the Master Bundle Tool and click the Asset Bundles dropdown arrow. You should see the assetbundle you just created listed here. Clicking the checkbox next to its name will flag it as a masterbundle.

Now when click the Master Bundles dropdown arrow you will see your masterbundle listed. Clicking the '...' button will let you select a folder to export the masterbundle into. This will warn you that you need a MasterBundle.dat file which we cover in the next section.

Note that for your masterbundle to be fully compatible with mac and linux you will need to check Multi-platform when exporting a final copy. Previously assetbundles were not properly compatible with those platforms.

Data setup:

Each folder containing a master bundle needs a MasterBundle.dat file. When the game traverses the file hierarchy it will check for a MasterBundle.dat, and if one is present it will assume all sub-folders should be redirected into this master bundle. You can configure these keys in the MasterBundle.dat file:

Asset_Bundle_Name: File name of the windows masterbundle exported from Unity. e.g. greece.masterbundle
Asset_Prefix: Path to the folder you selected as an assetbundle in Unity. Building on the MyModBundles example from earlier, you might use Assets/MyModMasterBundle in which case the game would look for the gun in Assets/MyModMasterBundle/Items/Gun.

There are some keys configurable per-dat as well:

Exclude_From_Master_Bundle: If included this .dat will ignore any parent masterbundles and instead look for an individual .unity3d file.
Master_Bundle_Override: Name of a masterbundle to redirect to, for example core.masterbundle. Useful when using Bundle_Override_Path like for an item with custom stats but uses the vanilla bundle, or a note that uses the vanilla note object.

Workshop Versions

You can safely upload your updated content to the workshop ahead of time. Players using pre-3.28 versions will receive a message that the workshop version is using a newer Unity build. Conversely, players on the 3.28+ client will receive a message for workshop items that have not yet been updated to the newer version of Unity.

Troubleshooting

Colors too light or dark in-game:

Most likely the Color Space setting in your Unity project needs adjusting. Navigate to Edit > Project Settings > Player. Under the Other Settings section change Color Space to Linear.

If that doesn't work, double-check that sRGB is enabled on your textures.

Devkit Foliage:

Materials default to instancing disabled now, so enable the Instancing flag in the Unity material inspector and rebuild the asset bundle.

[mentalkot]

Nelson, pls, write "Hello!" in my steam

[K-1684]

welcome to the creator please tell me how to build objects for maps (I create a map and I really need to know this ) - I want a good ditalization and optimization for my map - so some locations that involve building are located off the map .... but you can't build there . how to make it so that you can build ?

[Michaelangelo Gakko]

Hi Nelson,i was going to ask you for something but it would be nice if you put zeus in the game in the next update.If you ask what Zeus is, if you play arma 3, you will see a system used to extract bots, objects, objects, vehicles, enemy bots and vehicles on youtube.

[< blank >]

I have the same problem, when i run the game, scareen freezes and later game crushes. Can someone please help?

[Harry]

My brother can’t play the game anymore ever since the update any reason why?

[Fuzzy Knuckles]

(This comment I have to split into 4 comments, I'll have them numbered so they can be read in order):

1) Also, is there a way to add objects from (for example) Hawaii assets master bundle so that the game sees both master bundles at the same time? What I mean is, I'd like to add any new bundles in such a way that they are modular, as opposed to making a new master bundle from Hawaii and vanilla.

[Fuzzy Knuckles]

2) This so I can keep the vanilla files separate from the new content. Would I simply edit the masterbundle.dat with a list of the custom master bundles in some way? If so, please say exactly how it's done. Or is there some other way I can just add objects and keep them in their own folder? If this is not possible, can you make changes to the game so to allow this?

[Fuzzy Knuckles]

3) Here's an example of what I mean, I'll use a different game to illustrate:
In Doom 3 the DVD version, (not the steam or BFG versions) in the games main directory you can simply create a folder with the same name as you want the mod to be called. Then ALL of the mod's content would be contained in that folder, such as models, guns stats, ammo, custom maps, etc.

[Fuzzy Knuckles]

4) This way the vanilla files could be kept separate from any mod files and any number of mods could be added or uninstalled with ease. The game would simply load each mod from an in-game menu and if you wanted to run multiple mods at once you would simply add the contents of each mod you wanted into the same folder of the parent mod. Or a better way, simply copy all the mods into a new folder of a different name you chose for the collective mods in the games directory. This way you can choose to play each mod separately or in any combination you desire.

It would be great if you made the game load mods in this way, please add this feature to the game in the future if possible.

[Fuzzy Knuckles]

This guild mentions "unity 2017.4", however on the unity website there are 29 versions ranging from 2017.4.0f1 (oldest) to 2017.4.29f1 (newest). So do I go with the newest 2017 LTS version or is there an exact version I should download and use to update my mods to?