Migrating Unity from 2.x to 3.0

❗️

You cannot upgrade from 1.x straight to 3.x

If your Beamable Unity project is using Beamable 1.x, then you must update to 2.x before updating to 3.x. The 3.0 release removes migration services that are required to upgrade 1.x projects. Please see the Migrating Unity from 1.19.23 to 2.0.0

What is New in 3.0?

The Beamable Unity 3.0 SDK has several big new features. The following sections will talk about each of these topics.

1. Better CLI Integration
2. A brand new Editor Login flow,
3. A brand new Content Manager,
4. Consolidated com.beamable.server Package

Better CLI Integration

The Beam CLI version 5.3 is automatically installed in your project when you update to the Unity Beamable 3.0 SDK. Starting in SDK 3.0, your Unity project no longer requires that the .beamable folder exist at the Unity project's root folder. This can be helpful if your project is made up of multiple Unity projects or other game projects that integrate with the Beam CLI.

The SDK connects to the CLI by spawning a CLI process that becomes a server process. In 3.0, the server is configured to automatically shut down when the Unity editor process terminates. This means that there will be less dangling CLI processes in the background.

New Editor Login flow

The SDK gets editor authentication information for Beamable from the CLI workspace folder, instead of the Unity project's /Library folder. This means that when you log in and out of the Unity editor, you are logging in and out of the CLI workspace as well. Vice versa, if you log into the CLI, Unity should pick up the change quickly.

The new source of truth for log-in information required a re-write of the editor login window. The new flow is simpler, and delegates some functionality to the Beamable Portal for managing account information.

Once you have signed in, you'll notice that the Account screen has 2 major columns instead of 1. On the left are the runtime connection strings the Beamable SDK will use. On the right are the editor connection strings.

New Content Manager

Perhaps the biggest change in 3.0 is that the Beamable content objects have been removed from Unity's AssetDatabase flow. Previously, all the content objects were ScriptableObjects and lived inside the Assets/Beamable/Editor/Resources folder. In 3.0, the content objects live as raw .json files in the .beamableworkspace. This is beneficial for several reasons,

1. Unity doesn't get in the way of asset modifications, so content is generally faster to index and operate on. You can still edit content as before, by clicking on it in the Content Manager and changing values in the Inspector. The SDK is materializing the .json as a ScriptableObject in memory, but not writing the Unity form back to disk. Instead, the in-memory ScriptableObject is converted back to .json, and written to disk.
2. The Beamable content is no longer constrained to Unity's proprietary .yaml format. This means you can edit the content files directly in a text editor if you want to. You can also share the content with other projects at the same time.
3. There is a CLI command suite for interacting with content that allows you to sync and publish content from the terminal or CI/CD machines.

The new Content Manager uses the CLI directly to manage the content. The CLI has a long-running command that listens to content publications from other developers on your realm and automatically updates your content. When someone else modifies content on your realm, there are 2 possibilities,

1. you haven't touched that piece of content, or
2. you have also modified the content

In the case where you haven't modified the content, the content is automatically downloaded and presented as unmodified. When you go to publish your content later, you will only see the content changes that you actually made.

In the case where you did modify the content, then it will appear in a special conflict status. Conflicted content needs to be resolved manually, and you can either accept your own local version or the remote version.

Additionally, the new Content Manager has a version of your content per Realm. Previously, when you switched Beamable Realms, all of your content would be compared to the new Realm selection. However, in 3.0, when you switch Realms, the Content Manager will swap to show your local version of the content on the given Realm.

Consolidated com.beamable.server Package

All of the code in com.beamable.server has been moved into the com.beamable package in 3.0. After you update to 3.0, you can safely remove the reference to com.beamable.server and only worry about keeping one Beamable package in your project.

Migration Notes

The biggest concern when updating to Beamable Unity SDK 3.0 is the Content. Follow these steps as you update your existing project.

Setup

Make sure you have a backup! If you're using source-control, make sure you make a commit with your working 2.x project before continuing on.

Upgrade the com.beamable and com.beamable.serverpackage to 3.0.0.
Once Unity re-compiles and there are no errors, you can safely remove the reference to com.beamable.server. The package is empty, and all the code was moved into the com.beamable package. You don't need to remove the dependency, and we will continue to ship no-op versions of the package until we release the 4.0 SDK.

You may need to re-log into the editor, because the login information is kept in the .beamable workspace rather than the Unity project's /Library folder.

Content

Open the Beam Content window, and you should see a content migration message.

Your existing ContentObjects are stored in the /Assets/Beamable/Editor/Resources folder. The migration process is going to load each of your content objects and save them as the raw .json format to the .beamable/content folder.

After the migration is successfully completed, the migration tool will delete your old content files in the /Assets/Beamable/Editor/Resources folder.

All of your content will appear as modified, because the checksum algorithm used in the Content algorithm was updated from md5 to sha-1.

Publish your content, and verify that the content appears correctly in Portal.

Moving forward, you can continue to use the Beam Content window to edit content by selecting a content item and modifying the properties in the Inspector.

Services

Any Microservices you have may need to upgraded to work with the new CLI 5.3 dependency. Please refer to the CLI update document, Upgrading. However, if you open the Beam Services window, it should prompt you with all required changes, and then perform an automatic fix.