Upgrade Guide (Oct 10, 2015)

(Extraction from the user manual guide thus far)
Updated Nov 2, 2015

5.3 Upgrade Guide

Global Illumination
Lightmap Snapshot was renamed to Lighting Data asset. The internal format of the lighting data was changed after the upgrade to Enlighten 3. Snapshots from a previous versions of Unity are no longer supported and should be rebaked.

This also affects streamed scene AssetBundles with realtime GI. Lightmap data won’t be loaded and thus such bundles should be also rebuilt.

Light probes and environment lighting is now consistent in gamma and linear color space. Some differences in environment lighting compared to Unity 5.2 is to be expected. Output is matching Unity 4.x intensity wise now but since 4.x and our light projection code generates L2 coefficients and Enlighten only outputs L1, the falloff for the final light probes can appear different. L2 support for light probes will appear in a future release. Directional non-important lights should now match 4.x. Light probes are always passed to the shaders in linear color space and final gamma conversion happens on the GPU. If you are using Unity’s ShadeSHxxx functions for evaluating the spherical harmonics in the shader, you should not have to change your shaders. In UNITY_STANDARD_SIMPLE shaders the SH evaluation is not split between the pixel and vertex shader, so we limit the linear to gamma conversions to only happen once and only in the vertex shader. On more advanced GPUs the calculation is split between vertex and fragment shader.

Shuriken
The particle size in the Collision Module has been replaced by a new parameter: Radius Scale. This new parameter acts as a multiplier on the actual particle size. If you were using the old value to do anything other than approximate the particle sizes, then you will need to reconfigure your collision bounds using the new parameter.

Multi Scene Editing
The multi scene editing feature introduces new API through EditorSceneManager and SceneManager. Which means that many of the API’s on EditorApplication and Application has been deprecated.

• EditorApplication.NewScene
• EditorApplication.NewEmptyScene
• EditorApplication.OpenScene
• EditorApplication.OpenSceneAdditive
• EditorApplication.SaveScene
• EditorApplication.SaveCurrentSceneIfUserWantsTo
• EditorApplication.SaveCurrentSceneIfUserWantsToForce

The above all have equivalent APIs on EditorSceneManager

• EditorApplication.currentScene

Internally this will return the name of the active scene in the Scene Manager, but to get all currently open scenes use the EditorSceneManager APIs

• EditorApplication.MarkSceneDirty
• EditorApplication.isSceneDirty

Each scene now has its own dirty flag. Get the scenes through the EditorSceneManager and check their state. Setting scenes dirty is also done through the EditorSceneManager. The deprecated APIs all operate on the active scene only.

• Application.LoadLevel
• Application.LoadLevelAsync
• Application.LoadLevelAdditive
• Application.LoadLevelAdditiveAsync

Application.LoadLevel[Async](path) redirects to SceneManager.LoadScene[Async](path, false) and Application.LoadLevelAdditive[Async](path) redirects to SceneManager.LoadScene[Async](path, true)

• Application.loadedLevel
• Application.loadedLevelName

These respectively gets the Build Setting Index of the active scene and the name of the active scene. You should use the SceneManager to get the indices and names of all loaded scene.

Precompiled Shader Assets
Precompiled shader assets are no longer supported - this means you can no longer click “show compiled code” and copy the resulting disassembly into a new shader asset. Old shader assets that are precompiled will be marked as unsupported.

The “show compiled code” in the shader inspector will still work and will display the disassembly of the shader on each platform.

Likewise you can still view the generated code for a surface shader, modify it, and copy that into a new shader asset - since it is only the HLSL source you are modifying.

This will affect AssetBundles built in previous versions of Unity - they have compiled shader assets inside them by definition. Any shaders in such bundles will need to be rebuilt.

For more detailed information you can see this unity blog post about upcoming feature deprecation.

OpenGL 4.x support on desktop
As a new feature, the OS X Editor and Standalone now support the new GL backend, which enables the use of OpenGL 3.x and 4.x features such as tessellation and geometry shaders. However, as Apple restricts the OpenGL version on OS X desktop to 4.1 at most, it does not support all DirectX 11 features (such as Unordered Access Views or Compute Shaders). This means that all shaders that are configured to target Shader Level 5.0 (with #pragma target 50) will fail to load on OS X.

Therefore a new shader target level is introduced: #pragma target gl4.1. This target level requires at least OpenGL 4.1 or DirectX 11.0 Shader Level 5 on desktop, or OpenGL ES 3.1 + Android Extension Pack on mobiles.

AssetBundles
AssetBundle’s container format was changed in order to support new LZ4 compression and have a basis for further improvements. Bundles created in earlier version (2.x, 3.x) are deprecated and not supported. Bundles created in Unity 4.x, 5.0–5.2 are supported and could be loaded. But, if they were already cached on a user device using WWW.LoadFromCacheOrDownload method, they will be redownloaded. Also take in mind that data in such bundles might be a subject to change (see e.g. Global Illumination section).

GetComponent(s)InChildren
GetComponentsInChildren has a slightly changed behaviour in the case where you invoke it on a gameObject who has a parent that is inactive. Previously you would always get an empty array as a result. Because that is never what you want, and because that meant GetComponentsOnChildren didn’t work on prefabs, this has been changed to ignore any active state from the target game object’s parents. Also, the singular version GetComponentInChildren() now has an optional includeInactive argument.

UI/default shaders
Using a default new UI shader on non new UI objects is not longer supported by default. Previously there was a ‘if’ check to determine whether or not the _clipRect should be used but for performance reasons this check was removed. To continue using a new UI shader on a non new UI object you will need to specify a valid clipRect your self.

Point and spot shadow casting lights
Point lights that are selected to cast shadows now have a working Bias slider, to allow adjustment and balancing of shadowing artifacts (under shadowing vs. shadow acne). This means any existing point lights which may have had a Bias set before that wasn’t doing anything will now start having an effect, and this will change the shadow casting behaviour.

Spot lights that cast shadows now have a new slider which allows you to select the near clip distance. This is the distance to the light below which any objects won’t cast shadows. Low values include close-by objects, at the cost of greatly reduced precision for the shadows. In previous Unity versions this was calculated at 4% of the total range of the light, which could be much too high for large lights. Now it defaults to 0.2, which should work for most cases.