Upgrading to Unity 5.6

This page lists any changes in 5.6 which might affect existing projects when you upgrade from earlier versions of Unity.

For example:

• Changes in data format which may require re-baking.

• Changes to the meaning or behavior of any existing functions, parameters or component values.

• Deprecation of any function or feature. (Alternatives are suggested.)

Script serialization errors no longer work

The script serialization errors introduced in Unity 5.4 and described in detail in this blog post, will always throw a managed exception from 5.6 onwards.

Behaviour in Unity 5.5 is the same as in Unity 5.4.

PlayerSettings.apiCompatibilityLevel deprecated

This is now a per-platform setting. Use PlayerSettings.SetApiCompatibilityLevel and PlayerSettings.GetApiCompatibilityLevel instead. PlayerSettings.apiCompatibilityLevel will continue to function, but it will only affect the current active platform.

Lighting changes

Directional specular lightmapA pre-rendered texture that contains the effects of light sources on static objects in the scene. Lightmaps are overlaid on top of scene geometry to create the effect of lighting. More info
See in Glossary has been removed.

As a consequence, LightmapsMode.SeparateDirectional has been removed. Use LightmapsMode.CombinedDirectional instead.

Here are the prefered ways to get specular highlights in Unity 5.6:

• For direct specular, stationary lights with real-time direct lighting provide high quality specular highlights in all modes but the subtractive one. Please see the Mixed Lighting documentation in the online lighting section of the 5.6 User Manual.

• For indirect specular, use Reflection ProbesA rendering component that captures a spherical view of its surroundings in all directions, rather like a camera. The captured image is then stored as a Cubemap that can be used by objects with reflective materials. More info
  See in Glossary, Screen Space Reflection (SSR), or both.

Mixed mode lighting has evolved

Mixed mode lighting in Unity 5.5 has been replaced with stationary lighting modes in Unity 5.6. This implies a lot of changes, and we advise you to carefully read the Lighting Modes documentation, and in particular the Stationary Modes draft documentation in the online lighting section of the 5.6 User Manual which details the newly available options.

Projects from pre-Unity 5.6 will be upgraded to Subtractive mode (see the Subtractive Light Mode in the online lighting section of the 5.6 User Manual. This is the closest match to the Mixed lighting from Unity 5.5.

However this mode is the lowest quality mode for Unity 5.6, so try other modes to see if they are a better fit for your projects. We highly recommend the ShadowmaskA Texture that shares the same UV layout and resolution with its corresponding lightmap. More info
See in Glossary (see the Shadowmask page and the Distance Shadowmask page in the online lighting section of the 5.6 User Manual, especially if you were using the now-defunct Directional Specular lightmaps before).

The default for new Unity 5.6 projects is Distance shadowmaskA version of the Shadowmask lighting mode that includes high quality shadows cast from static GameObjects onto dynamic GameObjects. More info
See in Glossary mode. (See the Distance shadowmask page in the online lighting section of the 5.6 User Manual).

Light probesLight probes store information about how light passes through space in your scene. A collection of light probes arranged within a given space can improve lighting on moving objects and static LOD scenery within that space. More info
See in Glossary

In Unity 5.6 you can no longer choose whether direct lighting is added to Light Probes from the lighting window. This now happens automatically based on the lights types and the stationary modes. This ensures that direct lighting is not missing and that there is no double lighting on dynamic objects using Light Probes, greatly simplifying the process.

New GPU instancing workflow

You must now check the new Enable Instancing checkbox for all Materials used for GPU instancing. This is required for GPU instancing to work correctly.

Note that the checkbox is not checked automatically as it’s impossible for Unity to determine if a Material uses a pre–5.6 ShaderA small script that contains the mathematical calculations and algorithms for calculating the Color of each pixel rendered, based on the lighting input and the Material configuration. More info
See in Glossary.

An upgrade error is also imposed on SpeedTree AssetsAny media or data that can be used in your game or Project. An asset may come from a file created outside of Unity, such as a 3D model, an audio file or an image. You can also create some asset types in Unity, such as an Animator Controller, an Audio Mixer or a Render Texture. More info
See in Glossary to help you regenerate the SpeedTree Materials, so that you can have Enable Instancing checked.

Note: The newly introduced procedural instancing Shaders (those with #pragma instancing_options procedural:func) don’t require this change because Shaders with the PROCEDURAL_INSTANCING_ON keyword are not affected.

Particle systemA component that simulates fluid entities such as liquids, clouds and flames by generating and animating large numbers of small 2D images in the scene. More info
See in Glossary changes

Custom Vertex Streams in the Renderer Module may now require you to manually upgrade your Particle Systems, if you use the Particles/Alpha Anim Blend Shader. In this situation, it is sufficient to simply remove the duplicated UV2 stream.

This is required because, in some cases, the duplicated stream is needed to maintain backwards compatibility, so there is no fully reliable auto-upgrade solution. The Normal and AnimFrame streams are also not required, but causes no problems if they exist. The fixed Particle System setup should look like this:

Secondly, the upgraded Emission Module will cause Animation Bindings attached the Burst Emission to be lost. It will be necessary to rebind those properties.

Animator change

Animate Physics: Rigidbodies attached to objects where the Animator has Animate Physics selected now have velocities applied to them when animated. This will give correct physical interactions with other physics objects, and bring the Animator in line with the behaviour of objects animated by the Animation Component.

This will affect how your animated Rigidbodies interact with other Rigidbodies (the Rigidbodies are moved instead of teleported every frame), so make sure to verify that your Animators with Animate Physics are behaving as you expect.

Dynamic batching 2D sprites

You should use dynamic batching in upgraded projects that contain 2D sprites. This avoids significant sprite rendering performance issues on devices with Adreno and Mali chipsets.

To use Dynamic Batching, open the PlayerSettings (menu: Edit > Project SettingsA broad collection of settings which allow you to configure how Physics, Audio, Networking, Graphics, Input and many other areas of your Project behave. More info
See in Glossary > Player). Open the Other Settings section and, under RenderingThe process of drawing graphics to the screen (or to a render texture). By default, the main camera in Unity renders its view to the screen. More info
See in Glossary, tick the Dynamic BatchingAn automatic Unity process which attempts to render multiple meshes as if they were a single mesh for optimized graphics performance. The technique transforms all of the GameObject vertices on the CPU and groups many similar vertices together. More info
See in Glossary checkbox and untick the Graphics Jobs (Experimental) checkbox. Note that these are the default settings for projects created in 5.6.

Graphics Jobs should not affect dynamic batching, but can sometimes cause unexpected behaviors on platforms that use Vulkan and DirectX12.

NUnit library updated

The Unity Test Runner uses a Unity integration of the NUnit library, which is an open-source unit testing library for .NET languages. In Unity 5.6, this integrated library is updated from version 2.6 to version 3.5. This update has introduced some breaking changes that might affect your existing tests. See the NUnit update guide for more information.

* 2017–05–19 Page amended with editorial review