Microservices - Custom Content

Create and deploy server-authoritative C# [CLCP-Microservices-05]

Beamable Microservices supports references to various built-in and custom data types. Some situations require additional consideration.

🚧

Warning!

Here are hints to help explain some of the trickier concepts:

  • Microservices does not support passing/returning any child of UnityEngine.Object. This is by design
  • Microservices does not support passing/returning any child of Beamable.Common.Content.ContentObject. This is a serialization limitation which may be resolved in the future. See below for a workaround

Easy Setup :green-heart:
Passing/returning no values requires no particular setup.

namespace Beamable.Server
{
   [Microservice("MyCustomMicroservice")]
   public class MyCustomMicroservice : Microservice
   {
      [ClientCallable]
      public async void MyMethod01()
      {

      }
   }
}

Intermediate Setup :large-blue-circle:
Passing/returning built-in C# primitive data types requires simply adding the appropriate "using" statements.

using System.Threading.Tasks;

namespace Beamable.Server
{
   [Microservice("MyCustomMicroservice")]
   public class MyCustomMicroservice : Microservice
   {
      [ClientCallable]
      public async Task<int> MyMethod01(string myMessage)
      {
         return 10;
      }
   }
}

Advanced Setup :black-circle:

Passing/returning custom C# primitive data types requires both...

using System.Threading.Tasks;
using Examples.MyCustomContentMicroserviceExample.Shared.MyCustomContent;

namespace Beamable.Server
{
   [Microservice("MyCustomMicroservice")]
   public class MyCustomMicroservice : Microservice
   {
      [ClientCallable]
      public async Task<MyCustomData> MyMethod01()
      {
      }
   }
}

Why Asmdef?

During the maturity of the Unity product, the concept of Asmdef was added. Asmdefs continue to be an optional feature for some Unity projects. In this situation it is required.

See Learning Fundamentals for more info on Asmdefs.

Unity C# Code execution is designed with key principles

  • A typical Unity project may have none, some, or all of its C# code sitting within Asmdefs
  • C# code not inside an Asmdef can access any code
  • C# code inside an Asmdef can access only code inside an Asmdef. The rules are set by configuring each Asmdef
  • An Asmdef cannot make any circular references

Beamable C# Microservices is designed with key principles

  • Microservices run in a unique server environment instead of the typical Unity client environment
  • Microservices live in an Asmdef so limit which code a Microservice can access. This is safer and more appropriate scoping

Example

Here are examples which cover common programming needs.

📘

Beamable SDK Examples

The following example code is available for download at GitHub.com/Beamable_Microservices_Examples

1. Asmdef Setup

The requirement here is for each Asmdef to reference only the other Asmdef(s) it must reference. Depending on the complexity of your project, you may have more or less total Asmdefs than are shown here.

🚧

Do Not "Use GUIDs"

Unity's Assembly Definition References have an optional flag for "Use GUIDs". This is not currently supported by Beamable Microservices, so it is advised to leave this box unchecked.

The Project's Asmdefs

495495

The Project's Asmdef References

The interrelation between some of the Asmdefs is shown here. This is only part of the story. It is strongly recommended to download this project and view each of these 4 Asmdefs within the Unity inspector for more info.

FromTo: AutoGenTo: RuntimeTo: ServerTo: Shared
AutoGen ✔️
Runtime ✔️✔️
Server ✔️
Shared

2. Code Setup

Data Design

Let's assume a C# Microservice method is designed to return a MyCustomDataContent data type. However, due to the limitations discussed above, that is not currently possible.

The workaround is to populate MyCustomDataContent with a MyCustomData data type which holds all the data of interest. The Microservice can properly fetch the content yet return only data within. The proper data design is shown here.

using System;
using Beamable.Common.Content;

namespace Examples.MyCustomContentMicroserviceExample.Shared.MyCustomContent
{
    [ContentType("my_custom_content")]
    
    public class MyCustomContent : ContentObject
    {
        public MyCustomData MyCustomData = new MyCustomData();
    }
    
    [Serializable]
    public class MyCustomData : System.Object
    {
        public int Attack;
        public int Damage;
    }
}

Calling MyCustomContentMicroservice

Here the example calls to MyCustomContentMicroservice which returns the MyCustomData.

private async void SetupBeamable()
{
    var beamableAPI = await Beamable.API.Instance;
    
    Debug.Log($"beamableAPI.User.id = {beamableAPI.User.id}");
    
    _myCustomContentMicroserviceClient = new MyCustomContentMicroserviceClient();
    
    // #1 - Call Microservice
    MyCustomData myCustomData = 
        await _myCustomContentMicroserviceClient.LoadCustomData();
        
    // Hardcoded guess. Feel free to update via Content Manager
    bool isSuccess = myCustomData.Attack == 22; 
    
    // #2 - Result 
    Debug.Log ($"LoadCustomData() myCustomData.Attack = {myCustomData.Attack}, Success={isSuccess}");
}

Implementing MyCustomContentMicroservice

Here the Content service returns the MyCustomContent and the Microservice returns just the MyCustomData within.

using System.Threading.Tasks;
using Examples.MyCustomContentMicroserviceExample.Shared.MyCustomContent;

namespace Beamable.Server
{
   [Microservice("MyCustomContentMicroservice")]
   public class MyCustomContentMicroservice : Microservice
   {
      [ClientCallable]
      public async Task<MyCustomData> LoadCustomData()
      {
         MyCustomData myCustomData = null;

         // Check All Content
         var clientManifest = await Services.Content.GetManifest();
         foreach (var entry in clientManifest.entries)
         {
            // Find Matching Type
            if (entry.contentId.Contains("my_custom_content"))
            {
               // Load MyCustomContent
               MyCustomContent myCustomContent =
                  await Services.Content.GetContent<MyCustomContent>(entry.ToContentRef());

               myCustomData = myCustomContent.MyCustomData;
            }
            
         }
         
         // Return data
         return myCustomData;
      }
   }
}