Quick Start for Unity - .NET SDK
On this page
This quick start demonstrates how to install and integrate Atlas Device SDK for .NET into your Unity project.
Prerequisites
Create a Unity project using 2020.3.12f1 (LTS)
Note
The .NET SDK may be compatible
with other versions of Unity, but 2020.3.12f1 (LTS) is the version that
the SDK team uses for testing and development. We recommend
using this version to ensure your project works with the SDK and
that the install steps match the steps below since Unity's UI often changes
between versions.
Install the SDK
You could install the SDK manually with a tarball. However, we recommend installing the .NET SDK through npm since it provides notifications of version updates through Unity's package manager.
Import the SDK
Tip
Atlas Device SDK was previously named Realm. The SDK library names still reflect Realm naming. To import Atlas Device SDK, you 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 SDK package:
using Realms;
Using the SDK in Your Unity Project
When developing with .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
Access MongoDB and Call a Function documentation.
Using the SDK While the Application is Quitting
The .NET SDK cannot be accessed within the AppDomain.DomainUnload Event or the Application.quitting event. This means you cannot write data to a database 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.
Important
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 database. If you are using a non-synced database, you are able to run multiple instances of your project without crashes.
Additional Examples
Check out the examples below for community-authored projects that demonstrate using the .NET SDK with Unity!
Note
The MongoDB Documentation team does not directly maintain these examples.