This guide is a simple recipe to upgrade from MLAPI 0.1.0 to Netcode for GameObjects (Netcode) 1.0.0. This document will help you kickstart your upgrade process. It may not fix everything, but it should guide you in the overall process.
There are five main steps in the upgrade process.
- Install the new package
- Changes in the naming
- Changes in the API
- Changes in behaviour
This step is the easiest one. First, uninstall the old MLAPI package. For that, go to your package manager (Windows -> Package Manager) and uninstall MLAPI. After that, still in the package manager, install the package:
com.unity.netcode.gameobjects. You now have plenty of compilation errors since there are quite some changes between the two libraries.
Installing the Netcode package will also install three other packages :
Unity Transport: the low-level transport layer recommended for Netcode
Netcode adapter for UTP: the Netcode adapter created by Unity for Unity Transport
Burst: a requirement for Unity Transport
You must note that the
Burst package requires an Editor restart. So restart your Unity after the installation. Unity will ask you to enter Fail Safe mode at the next boot, which is normal behaviour since all your network code is not compiling anymore.
Unity also recommends installing the multiplayer tools package:
com.unity.multiplayer.tools. This package will enable the Unity profiler to understand the Netcode library and add counters for network traffic.
Unity renamed MLAPI into Netcode for GameObjects. This renaming has an impact on library and namespace naming. First, go to all your ASMDEF files referencing MLAPI and change the reference for
Unity.Netcode.Runtime. Next, you can upgrade your using namespaces
using namespace MLAPI to
using namespace Unity.Netcode. Change this namespace in code to if you are not using
Unity Multiplayer Teams tried to keep most of the MLAPI intact in Netcode. However, a successful compilation still requires some changes.
NetworkVariable type is now generic only and the type specified in the generic needs to be a value type. First, change all your
NetworVariable* types for their generic counterpart. For example,
NetworkVariable<int>, NetworkVariableFloat becomes
NetworkVariable<float> and so on. Now, some of your types (string, for example) will not match the new type requirements for
NetworkVariable<T>. If your type is a string, you can use
FixedString32Bytes instead. One should note that this type does not allow you to change the size of the string. For custom structs that only contain value types, you can implement
INetworkSerializable, and it will work. Finally, for the other types, you will need to create your own
NetworkVariable. To achieve that, create a new class, inherit from
NetworkVariableBase, and implement all the abstract members. If you already had custom
NetworkVariable, read and write functions now uses our
FastBuffer to read or write from and to the stream.
The scene management had some changes unifying the way users uses it. First, it is now under the
NetworkManager Singleton. Consequently, you directly access it like so :
Next, there is now only one scene event instead of many:
OnSceneEvent. You can subscribe to it and get scene events information from the
SceneEvent class. In this class, you will find the
SceneEventType, which will give you precisions on what type of event is coming from the Scene Manager. Finally, the primary function to switch between scenes has changed to match the Unity Scene Manager. Instead of
SwitchScene, you now call
LoadScene with two parameters: the scene name and the
LoadSceneMode, which is the standard way to load a scene in Unity.
There are two main changes in
NetworkBehavior. First, the
NetworkStart method becomes
OnNetworkSpawn, and we introduced
OnNetworkDespawn to keep things symmetrical. Second,
OnDestroy now needs to be overridden since NetworkBehavior already uses it.
We tried to keep the behaviour changes minimal put two changes may cause errors in your scripts. First, the
NetworkManager now does its connection shut down when the application quits. If you were doing it by yourself, you would end up with an error saying that you tried to disconnect twice. Second, the library now fires all the
OnValueChanged events from the
NetworkVariable after the
OnNetworkSpawn (previously known as
NetworkStart) method has returned. You will need to refactor any scripts depending on this order accordingly.
For instructions on how to install Netcode for GameObjects please see here