Version: 2022.2
Language : English
Upgrading to Unity 5.5
5.4 Networking API Changes

Upgrading to Unity 5.4

When upgrading projects from Unity 5.3 to Unity 5.4, there are some changes you should be aware of which may affect your existing project.

Networking: Multiplayer Service API changes

Numerous changes to the Networking API.

Networking: WebRequest no longer experimental

The WebRequest interface has been promoted from UnityEngine.Experimental.Networking to UnityEngine.Networking. Unity 5.2 and 5.3 projects that use UnityWebRequest will have to be updated.

Scene View: Tone mapping not automatically applied

An image effect with the ImageEffectTransformsToLDR attribute will no longer be applied directly to the SceneA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info
See in Glossary
view if found. A new attribute exists for applying effects to the Scene viewAn interactive view into the world you are creating. You use the Scene View to select and position scenery, characters, cameras, lights, and all other types of Game Object. More info
See in Glossary
: ImageEffectAllowedInSceneView. The 5.4 Standard Assets have been upgraded to reflect this change.

Shaders: Renamed variables

A number of built-in shaderA program that runs on the GPU. More info
See in Glossary
variables were renamed for consistency:

  • _Object2World and _World2Object are now unity_ObjectToWorld and unity_WorldToObject
  • _World2Shadow is now unity_WorldToShadow[0], _World2Shadow1 is unity_WorldToShadow[1] etc.
  • _LightMatrix0 is now unity_WorldToLight
  • _WorldToCamera, _CameraToWorld, _Projector, _ProjectorDistance, _ProjectorClip and _GUIClipTextureMatrix are now all prefixed with unity

The variable references will be automatically renamed in .shader and .cginc files when importing them. However, after the import the shaders will not be usable in Unity 5.3 or earlier, without manually renaming the variables.

Shaders: Uniform arrays

In Unity 5.4, the way arrays of shader properties are handled has changed. Now there is “native” support for float/vector/matrix arrays in shaders (via MaterialPropertyBlock.SetFloatArray, Shader.SetGlobalFloatArray etc.). These new APIs allow arrays up to 1,023 elements.

The old way of using number-suffixed names for referring to individual array elements is deprecated (e.g. _Colors0, _Colors1) in both Material and MaterialPropertyBlock. Properties of this kind, serialized with the Material are no longer able to set array elements (but if any uniform array’s name is suffixed by a number it still works).

Shaders: Miscellaneous changes in 5.4

The default shader compilation target has changed to “#pragma target 2.5” (SM3.0 on DX9, DX11 9.3 feature level on WinPhone). You can still target DX9 SM2.0 and DX11 9.1 feature level with “#pragma target 2.0”.

The majority of built-in shaders target 2.5 now: Notable exceptions are Unlit, VertexLit and fixed function shaders. In practice, this means that most of built-in shaders and newly-created shaders, by default, will not work on PC GPUs that are made before 2004. See this blog post for details.

The Material class constructor Material(string), which was already deprecated, stops working in 5.4. Using it will print an error and result in the magenta error shader.

The internal shader used to compute screen-space directional light shadows has moved to the Graphics settings. If you were using a customized version of directional light shadows by having a copy of that shader in your project, it will no longer be used. Instead, select your custom shader under Edit > Project Settings, then select the Graphics category.

Reflection probes share a sampler between the two textures. If you are sampling them manually in your shader, and get an “undeclared identifier samplerunity_SpecCube1” error, you’ll need to change code from UNITY_PASS_TEXCUBE(unity_SpecCube1) to UNITY_PASS_TEXCUBE_SAMPLER(unity_SpecCube1,unity_SpecCube0).

UnityEditor.ShaderUtil.ShaderPropertyTexDim is deprecated; use Texture.dimension.

ComputeBuffers

The data layout of ComputeBuffers in automatically-converted OpenGL shaders has changed to match the layout of DirectX ComputeBuffers. If you use ComputeBuffers in OpenGL, remove any code that tweaks the data to match the previous OpenGL-specific layout rules. Please see Compute Shaders for more information.

Playables: Migrating to 5.4

  • PlayablesAn API that provides a way to create tools, effects or other gameplay mechanisms by organizing and evaluating data sources in a tree-like structure known as the PlayableGraph. More info
    See in Glossary
    are now structs instead of classes.

  • The Playable structs are handles to native Playable classes, instead of pointers to native Playable classes.

  • A non-null Playable struct doesn’t guarantee that the Playable is usable. Use the .IsValid method to verify that your Playable can be used.

  • Any method that used to return null for empty inputs/outputs will now return Playable.Null.

  • Playable.Null is an invalid Playable.

  • Playable.Null can be passed to AddInput, SetInput and SetInputs to reserve empty inputs, or to implicitly disconnect connected inputs.

  • Using Playable.Null or any invalid Playable as an input to any method, or calling a method on an invalid Playable will throw appropriate exceptions for the operation.

  • Comparing Playables with null is now meaningless. Compare with Playable.Null.

  • Playables must be allocated using the Create static method of the class you wish to use.

  • Playables must be de-allocated using the .Destroy method on the Playable handle.

  • Playables that are not de-allocated will leak.

  • Playables were converted to structs to improve performance by avoiding boxing/unboxing (more info on boxing).

  • Casting a Playable to an object, implicitly or explicitly, will cause boxing/unboxing, thus reducing performance.

  • Inheriting from a Playable class will cause boxing/unboxing of instances of the child class.

  • Since only animation is available for now, ScriptPlayables have been replaced by CustomAnimationPlayables.

  • It is no longer possible to derive from base Playables. Simply aggregate Playables in your custom Playables.

Oculus Rift: Upgrading your project from Unity 5.3

Follow these instructions to upgrade your Oculus VR project from Unity 5.3:

Re-enable virtual reality support.

  • Open the Player settings (menu: Edit > Project Settings, then select the Player category).
  • Select Other Settings and check the Virtual Reality Supported checkbox. Use the Virtual Reality SDK list displayed below the checkbox to add and remove Virtual Reality Devices for each build target.

Remove Oculus Spatializer.

  • Remove the Oculus Spatializer Audio Plugin from your project through the Audio settings (menu: Edit > Project Settings, then select the Audio category), using the Spatializer Plugin dropdown menu. It may conflict with the native spatializer and prevent building.

Reordering siblings

There has been a change to the events that are triggered when sibling GameObjectsThe fundamental object in Unity scenes, which can represent characters, props, scenery, cameras, waypoints, and more. A GameObject’s functionality is defined by the Components attached to it. More info
See in Glossary
are re-ordered in Unity 5.4. Sibling GameObjects are GameObjects which all share the same parent in the Hierarchy window. In prior versions of Unity, changing the order of sibling GameObjects would cause every sibling to receive an OnTransformParentChanged call. In 5.4, the sibling GameObjects no longer get this call. Instead, the parent GameObject receives a single call to OnTransformChildrenChanged.

This means that if you have code in your project that relies on OnTransformParentChanged being called when siblings are re-ordered, these calls will no longer occur, and you need to update your code to take action when the parent object receives the OnTransformChildrenChanged call instead.

This changed because the new behavior gives improved performance.

Rearranging large GameObject hierarchies at runtime

Due to optimisations in the Transform componentA Transform component determines the Position, Rotation, and Scale of each object in the scene. Every GameObject has a Transform. More info
See in Glossary
, using Transform.SetParent or Destroying parts of hierarchies involving 1000+ GameObjects may now take a long time. Calling SetParent on or otherwise rearranging such large hierarchies at runtime is not recommended.

Windows Store

The generated Visual Studio project format was updated for all .NET scripting backendA framework that powers scripting in Unity. Unity supports three different scripting backends depending on target platform: Mono, .NET and IL2CPP. Universal Windows Platform, however, supports only two: .NET and IL2CPP. More info
See in Glossary
SDKs. This fixes excessive rebuilding when nothing has changed in the generated project. You might need to delete your existing generated *.csproj, especially if it was built with the “Generate C# projects” option checked, so Unity can regenerate it.

Script serialization errors

There are two new script serialization errors to catch when the Unity API is being called from constructors and field initializers during deserialization (loading). Deserialization might happen on a different thread to the main thread and it is therefore not safe to call the Unity API during deserialization. There are more details at the bottom of the (Script Serialization)[script-Serialization] page in the Unity Manual.

Supporting Retina screens

The editor now supports Retina resolutions on Mac OS X with high-resolution text, UI(User Interface) Allows a user to interact with your application. Unity currently supports three UI systems. More info
See in Glossary
and 3D views.

The Editor GUI is now defined in point space rather than pixelThe smallest unit in a computer image. Pixel size depends on your screen resolution. Pixel lighting is calculated at every screen pixel. More info
See in Glossary
space. On standard resolution displays, there is no change because each point is one pixel. On Retina displays, however, every point is two pixels. The current screen to UI scale is available as EditorGUIUtility.pixelsPerPoint. Since Unity can have multiple windows, each on monitors with different pixel densities, this value might change between views.

If your editor code uses regular Editor/GUI/Layout methods, it is quite likely that you will not need to change anything.

If you are using Screen.width/height, switch to EditorWindow.position.width/height instead. This is because screen size is measured in pixels, but UI is defined in points. For custom Editors displaying in the InspectorA Unity window that displays information about the currently selected GameObject, asset or project settings, allowing you to inspect and edit the values. More info
See in Glossary
, use EditorGUIUtility.currentViewWidth, which properly accounts for the presence of a scroll bar.

If you are displaying other content in your UI, such as a RenderTexture, you are probably calculating its size in points. To support Retina resolutions, you will need to convert your point sizes to pixel sizes. There are new methods in EditorGUIUtility for this.

If you are using GUIStyles with custom backgrounds, you can add Retina versions of background textures by putting one texture with exactly doubled dimensions into a ‘GUIStyleState.scaledBackgrounds’ array.

Macs with underpowered graphics hardware may experience unacceptably slow editor frame rates in 3D views due to increased resolution. Retina support can be disabled by choosing “Get Info” on Unity.app in the Finder, and checking “Open in Low Resolution”.

Physics: Meshes and physics transform drift

There are:

  • Changes to reject physics meshes if they contain invalid (non-finite) vertices.
  • Changes to avoid physics transform drift by not sending redundant Transform updates.

The 5.3 behavior is that the animation system always sends Transform update messages for animation curvesAllows you to add data to an imported clip so you can animate the timings of other items based on the state of an animator. For example, for a game set in icy conditions, you could use an extra animation curve to control the emission rate of a particle system to show the player’s condensing breath in the cold air. More info
See in Glossary
which are constant. These messages wake up the RigidbodiesA component that allows a GameObject to be affected by simulated gravity and other forces. More info
See in Glossary
and fixing this proved very risky in 5.3.

The 5.4 behavior is that if there are no position changes, the Rigidbody does not wake up (as most people would expect).

If your project relies on the 5.3 behavior of waking Rigidbody all the time, it might not work as expected in 5.4.

Web Player

The Unity Web Player target has been dropped from Unity 5.4. If you upgrade your project to 5.4, you will not be able to deploy it to the Web Player platform.

If you have legacy Web Player projects that you need to maintain, do not upgrade them to 5.4 or later.

Upgrading to Unity 5.5
5.4 Networking API Changes