This upgrade guide targets projects using the MLAPI version which was installed by the MLAPI installer or by cloning the source code from Github. If your project uses a Package Manager version of MLAPI then 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 MLAPI 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 MLAPI references components using GUIDs, which work differently for packages than for
To smoothly upgrade you to the new version of MLAPI, 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 MLAPI.
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 MLAPI patcher window by selecting Window > MLAPI 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 MLAPI 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 Unity MLAPI, 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 MLAPI 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 MLAPI. 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
SyncVars no longer exist in MLAPI. Convert your existing SyncVars into NetworkVariables.
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
If you get an error message like this (or for another MLAPI 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.
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 MLAPI Patcher package from your project in the Unity Package Manager as it is no longer needed.