This upgrade guide targets projects using the MLAPI version 12.1.7 and earlier that were installed by the MLAPI installer or by cloning the source code from Github.
If your project uses a Package Manager version of Netcode for GameObjects (Netcode), this guide is not relevant.
The aqcuisiton of MLAPI has been a unique event in Unity history. In our efforts to integrate MLAPI into the Unity ecosystem, we are providing it in a Unity package.
What this means for you is:
- MLAPI will be easily accessible from the Unity Editor in the Package Manager window.
- Updating MLAPI in the future will work directly from the Package Manager.
- You will have full access to the MLAPI source in your project making it easier to debug and inspect MLAPI.
- Upgrading from the last MLAPI version to the new package version is a bit complicated. We are sorry for that.
This step is required: Upgrading to the package version of Netcode can cause issues with your current project. The new version modifies files and locations that will be 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.
Manually upgrading from the
.dll version installed by MLAPI to the new package version breaks all MLAPI component references in your scenes and prefabs. This is the case because Netcode references components using GUIDs, which work differently for packages than for
To smoothly upgrade you to the new version of 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 are good to go. Complete the following steps to upgrade.
Follow the installation guide for installing the package version of Netcode.
After installing the package, you will have error messages in the console, which is expected behavior because your project now contains two different versions of MLAPI at the same time. No worries, we will later clean up the old MLAPI version.
Do not remove the old version of MLAPI yet. It will still be used in the next step.
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 could either download a release version of MLAPI using the MLAPI installer or manually copy the source files into your project.
If you are not 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. You can verify by checking if the
NetworkingManager component is now called
Most likely at this point you will get a warning telling you that the script cannot be loaded. No need to panic, this is expected and your serialized data won't be lost. As soon as you finish up migrating and clean up all error messages your data will appear again.
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 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.
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.
With our latest release we introduced a number of breaking API changes. With the move to Unity Packages, we took this chance to clean up the code base and provide an API that is easier to understand and use. We understand that upgrading to a new version with many breaking changes can be frustrating, and we are sorry for that.
See the Release Notes for a list of all new features, refactored name changes, issue fixes, and more.
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.
Error: The type or namespace name 'MLAPI' could not 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' could not be found
If you get an error message like this (or for another Netcode type than
NetworkedBehaviour) in the console it is most likely because your code contains outdated APIs. Open the script indicated in the error messagea and update all APIs to the new names. You can find a table of what we renamed in the Release Notes .
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 you are done upgrading your project, you can remove the Netcode Patcher package from your project in the Unity Package Manager as it is no longer needed.
After migrating and updating to the Netcode package, we recommend looking into the following:
- Release Notes - Learn more about updated and changed features, bug fixes, and known issues for Unity MLAPI.
- First Steps with Netcode for GameObjects - Learn how to create your first networked game with a Hello World sample. If you have existing projects or are new to Netcode, this will give you an initial review of Netcode projects.