Unity support

Summary

Nerdbank.MessagePack is ready for Unity, both for its mono and its IL2CPP backend. The NativeAOT readiness of this library makes it an ideal library for IL2CPP in your game.

Installation

1. Install NuGetForUnity into your project.
2. Use the new "NuGet -> Manage NuGet Packages" command in the Unity Editor to install the Nerdbank.MessagePack package. You may need to set the option to show prerelease versions.

Known issues

.NET Standard APIs only

Unity is currently limited to .NET Framework or .NET Standard 2.1 libraries. Some of the preferred APIs in Nerdbank.MessagePack are exposed uniquely to .NET 8+ projects. As a result, when reviewing documentation and samples for this library, be sure to look at the samples in their ".NET Standard" form.

PolyType name collisions

If you encounter a compilation error such as the following:

error CS0234: The type or namespace name 'ptSubject' does not exist in the namespace 'PolyType'"

Resolve it by taking the following steps:

1. Turn off "Auto Reference" for the conflicting assemblies.
   1. Within the Unity Editor, navigate to the Assets\Packages\PolyType.*\lib\libstandard2.x folder in your Project.
   2. Select the PolyType.dll file.
   3. Within the Inspector, uncheck the "Auto Reference" option. Click Apply.
   4. Repeat these steps to turn off Auto Reference from Assets\Packages\Nerdbank.MessagePack.*\lib\netstandard2.x as well.
2. Manually reference these two assemblies from your code.
   1. Within the Unity editor, create an Assembly Definition or select your existing one.
   2. In the Inspector, check the "Override References" option.
   3. Under Assembly References, click the Add button. Select the PolyType.dll assembly.
   4. Repeat the prior step, this time selecting to add a reference to the Nerdbank.MessagePack.dll.
   5. Scroll down as necessary in the Inspector and click Apply.

The type or namespace name 'GenerateShapeAttribute' could not be found

In projects with disabled auto references, you will need to add an assembly reference to PolyType.dll and Nerdbank.MessagePack.dll to your project manually.

Visual Studio complains that the Witness class has no ShapeProvider property

The witness class that your unity project requires for serialization should be attributed with GenerateShapeForAttribute and be declared as a partial class, after which the PolyType source generator should add a ShapeProvider property. Some configurations of Visual Studio will not re-run the source generator until you save your code file with these changes. If you see an error (or a lack of ShapeProvider in the completion list for your witness class), verify that you have the attribute and partial modifier as required, and save your code file.

Right-clicking the source file and asking Unity to "Reimport" that file is also reported to fixing this transient issue.

MissingMethodException: Unsafe.IsNullRef

When running your Unity project, you might see the following error:

MissingMethodException: Method not found: bool System.Runtime.CompilerServices.Unsafe.IsNullRef<!0>(!!0&)

This means your project is using an old version of System.Runtime.CompilerServices.Unsafe.dll.

To resolve the error, use NuGetForUnity to update this dependency to the latest.