Integrate Realm with Unity - .NET SDK¶
On this page
This page contains information on how to install and integrate MongoDB Realm into your Unity project.
The following is a list of known issues when integrating Realm with Unity:
- The Realm .NET SDK only supports Intel64 Macs and does not yet support Macs with the Apple M1 chip. Set your build settings: Architecture to "Intel64" in order to allow building for MacOS.
- On Windows, your project may crash when running multiple instances of your project since multiple processes are attempting to access the same realm. To avoid these crashes, explicitly specify different names for each respective realm.
- Unity 2020.3.12f1 (LTS)
The Realm .NET SDK may be compatible
with other versions of Unity, but
2020.3.12f1 (LTS) is the version that
the Realm team uses for testing and development. We recommend
using this version to ensure your project works with Realm and
that the install steps match the steps below since Unity's UI often changes
Realm provides various ways to install the Realm .NET SDK for use with Unity. Experienced Unity developers may find installing Realm manually with a tarball to be intuitive. However, we recommend installing the Realm .NET SDK via npm since it provides notifications of version updates through Unity's package manager.
Using Realm in Your Unity Project¶
When developing with Realm .NET SDK, the API methods are the same regardless of whether you use Unity or another platform. However, since Unity has some scripting restrictions, you should keep the following additional considerations in mind when developing your project:
dynamic Keyword Support¶
Unity does not support the dynamic keyword when using IL2CPP. This means all types used in C# scripts must be known at compile time. When you use the Realm .NET SDK with Unity, you must convert dynamic types to concrete types. To view the full list of limitations, see the Unity scripting limitations documentation. Although the Realm .NET SDK exposes the Dynamic API, we recommend it only when performing migrations.
Managed Code Stripping¶
Unity performs managed code stripping, discarding any unused code from a build to reduce binary size. This may lead to issues when deserializing BSON into C# classes. For platforms that use IL2CPP, such as iOS, managed code stripping is enabled by default. When working with BSON, use the [Preserve] attribute to prevent managed code stripping on types properties that are only populated by the serializer. Since those properties use reflection, Unity cannot statically infer that the property setter is used. This means that unless you apply the
[Preserve] attribute, Unity will strip those properties away. For examples of when you may perform BSON deserialization, check out the Query MongoDB and Call a Function documentation.
Using Realm While the Application is Quitting¶
The Realm .NET SDK cannot be accessed within the AppDomain.DomainUnload Event or the Application.quitting event. This means you cannot write data to a Realm while the player application is quitting. If you need to store some data just before the app exits, consider using the Application.wantsToQuit event instead.
The MongoDB Realm community has created many projects that demonstrate the usage of the Realm .NET SDK. Check out the examples below that demonstrate the usage of the Realm .NET SDK with Unity!
The MongoDB Documentation team does not directly maintain these examples.
- MongoDB Devhub: Unity with Realm Articles
- MongoDB Youtube Channel: Getting Started with the Realm SDK for Unity
- MongoDB Youtube Channel: Build an Infinite Runner Game with Unity and the Realm Unity SDK
- dodoTV42 Youtube Channel: How to SAVE and LOAD data in Unity3D with Realm SDK
- Chris Paliqaw's Blog Post: Migrating from Unity PlayerPrefs to MongoDB Realm