Calling Microservices from Unity

Beamable will auto generate Unity csharp code to interact with your Microservice. Below is an example of a simple Microservice, and how to access the auto-generated client.

Server Code

using Beamable.Server;

namespace Beamable.DemoService
{
	[Microservice("DemoService")]
	public partial class DemoService : Microservice
	{
		[ClientCallable]
		public int Add(int a, int b)
		{
			return a + b;
		}
	}
}

Client Code

public async void Start()
{
    // get access to Beamable 
    var ctx = await BeamContext.Default.Instance;
    
    // use extension methods to access a pre-configured client
    var demoClient = ctx.Microservices().DemoService();

    // use the auto-generated Add client method
    var sum = await demoClient.Add(1, 2);
}

In the client code, the first step is acquire a BeamContext. The BeamContext is the root instance for each player in Beamable. If you are not familiar with with BeamContext, learn more by reading the Player Centric API - Overview].

Every time the Microservice builds, Unity will generate the client code.

Serialization Constraints

The autogenerated code is making HTTP calls to communicate with your Microservice. The parameters of the methods are being serialized into JSON objects and sent along with the HTTP request. The Microservice deserializes the JSON and spreads the objects back out into the method parameters. The return value from the method is serialized as JSON and sent back to Unity to close the HTTP request. The autogenerated client deserializes the response JSON and converts it into the instance that is returned from the generated method.

The client side serialization and deserialization rely heavily on the built in Unity JsonUtility class, and as such, share many of the same constraints as the built in Unity JSON serialization. The following is a list of criteria for valid serializations.

1. Request and Response objects should use public fields instead of properties.
2. Dictionary types are not supported.

Client Generation Configuration

Client code generation should happen automatically any time the Microservice is built. Any time you start the service after changing code, it will be built. However, if the client is not being generated, you can use the dot-dot-dot menu in the Beam Services window to select Generate Client. You can also use this section to disable automatic generation if you would prefer to do it by hand.

The generated client code will be put in the following path in your Unity Project...

/Assets/Beamable/Autogenerated/Microservices

The client generation path can be changed in two ways.

1. If you create an assembly definition that has a name ending with your Microservice's name and .client, then the client code will be generated in the folder where the assembly definition exists. For example, if you had a service called HotSauce, then you could create a custom assembly definition called Custom.HowSauce.Client, and the client code would be generated.

   🚧

   You need a second script in the assembly definition!

   Unity will not register the assembly definition if no script file exists in the folder, which can create a nasty chicken-and-egg problem. If you only have the assembly definition and no existing script files, then Unity will ignore it, and therefor, the Beamable SDK will not recognize the assembly definition exists, and will not generate the client in the folder. Please include at least one (even an empty) script in the assembly definition.

2. The Microserviceclass has an attribute called [Microservice]. The attribute can accept a custom parameter, CustomAutoGeneratedClientPath, which should be a path relative to your Unity project root. Mostly commonly, it should start with either Assets/ or Packages/.