Upgrade MLAPI to Netcode for GameObjects
Use this guide to upgrade from MLAPI 0.1.0 to Netcode for GameObjects (Netcode) 1.0.0.
It is recommended to upgrade to Netcode from MLAPI as soon as possible. MLAPI isn't maintained and won't have future updates. MLAPI should be considered a deprecated product.
Backup your MLAPI project
Consider this step a required: Upgrading to the package version of Netcode can cause issues with your current project. The new version modifies files and locations that are drastically different than previous MLAPI versions.
Backup your project using the following recommended methods:
- Create a copy of your entire project folder.
- Use source control software, like Git.
We recommend using both methods to backup your project. This gives you a copied project and tracking through committed changes and history.
Use the Upgrade Tool on your MLAPI project
Manually upgrading from the
.dll version installed by MLAPI to the new package version breaks all MLAPI component references in your scenes and prefabs. Netcode references components using GUIDs that work differently for packages than for
To help with the upgrade process to Netcode, we have created an upgrade tool.
To start upgrading, add the upgrade tool to your project by using the Add package from git URL.. option in the Package Manager window. Use the following URL:
After installing the patcher package, you can continue the upgrade process.
Install the Netcode Package
Follow the installation guide to install Netcode.
After installing the package, you will have error messages in the console, which is expected behavior because your project now has MLAPI and Netcode at the same time. This will be remedied by the end of this guide.
Installing the Netcode package will also install some other packages such as
Unity Burst etc.
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 isn't compiling anymore.
Don't remove the old version of MLAPI yet. It will still be used in the next step.
Updating Script References
Open the Netcode patcher window by selecting Window > Netcode Patcher in the menu bar. The patcher will ask you whether you are using the Installer version of MLAPI or the Source version.
Previously there were two major ways to use MLAPI in projects. You can either download a release version of MLAPI using the MLAPI installer or manually copy the source files into your project.
If you aren't sure which way of MLAPI you are using check whether you have the
Assets/MLAPI/Lib/MLAPI.dll file in your project. If that's the case you are using the
In the Patcher window, select Installer or Source button:
- Upgrading from installer version.
- Upgrading from source version.
- Select Installer.
- Select Update Script References.
- Select Source.
- The window prompts you to link a MLAPI source directory.
- Take the directory in your project containing the MLAPI source and drop it into the field.
- Select Update Script References.
After you complete the Update Script References process of the patcher, the Netcode components on your
GameObjects should have been updated to their new names.
There is also a Replace Type Names button in the Patcher window. This step is optional. It automatically renames old type names in your scripts to the API changes made in Netcode, saving you some time to manually rename it. It performs a simple global replace of some of the type names. You may want to manually do this process instead if you want more control over changes.
Remove older MLAPI versions
Remove all the folders containing the existing non-package version of MLAPI from your project. Usually this means removing the
Assets/Editor/MLAPI folders from the project.
Upgrade your code to the new Netcode APIs
Upgrading your code is a manual and long process. If you run into difficulties while upgrading please join our Discord, and we will support you.
The Unity Multiplayer team 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) won't 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.
Scene Management changes
The scene management had some changes unifying the way users uses it. First, it's now under the
NetworkManager Singleton. Consequently, you directly access it by:
var sceneManager = NetworkManager.Singleton.SceneManager;
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.
Changes in behavior
We tried to keep the behavior changes minimal but 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.
The way RPCs are invoked has changed with this version of Netcode. Please read our new documentation about RPCs and replace your existing RPCs with the new system.
We replaced the old
INetworkSerializable interface with a new
INetworkSerializable interface. The interface works a bit different. See
The page also includes information on nested serial types.
SyncVars have been removed in Netcode. Convert your existing SyncVars into NetworkVariables.
Remove the Patcher Package
After you are done upgrading your project, you can remove the Netcode Patcher package from your project in the Unity Package Manager as it's no longer needed.
Error: The type or namespace name 'MLAPI' can't be found
This error will pop up if your project uses Assembly definition (
.asmdef) files. After switching to the package version your assembly definition files will need to reference
Error: The type or namespace name 'NetworkedBehaviour' can't be found
If you get an error message like this (or for another Netcode type than
NetworkedBehaviour) in the console it's most likely because your code has outdated APIs. Open the script indicated in the error messagea and update all APIs to the new names.
Error: SerializedObjectNotCreatableException: Object at index 0 is null
If this appears whenever you enter playmode or save a scene, close the Unity Editor and open it again and this should be gone.
After migrating and updating to the Netcode package, we recommend looking into the following:
- Consider using the Hello World and Golden Path series to learn some basics of Netcode for GameObjects.
- Explore the educational samples content for a deeper exploration into Netcode for GameObjects: