Docs Menu

Docs Home → Develop Applications → Atlas Device SDKs

Quick Start for Unity - .NET SDK

On this page

  • Prerequisites
  • Install
  • Add NPM as a Scoped Registry
  • Add Realm to the Project Manifest
  • Verify the Realm Dependency and Check for Updates
  • Download the Latest Realm .NET SDK Release
  • Add the Tarball to Your Projects Package Manager
  • Import Realm
  • Using Realm in Your Unity Project
  • Managed Code Stripping
  • Using Realm While the Application is Quitting
  • Additional Examples

This page contains information on how to install and integrate Realm into your Unity project.

Prerequisites

Note

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 between versions.

Install

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.

Import Realm

Create a C# script or use a C# script you have already created. Open that script in Visual Studio or another text editor and add the following line to import your Realm package:

using Realms;

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:

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.

Note

Known Issue When Developing With Unity on Windows

On Windows, if you are using Device Sync, your project may crash when running multiple instances of your project since multiple processes are attempting to access the same synced realm. If you are using a local realm, you are able to run multiple instances of your project without crashes.

Additional Examples

The 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!

Note

The MongoDB Documentation team does not directly maintain these examples.

← Quick Start - .NET SDK
Work with Realm Files - .NET SDK →

On this page