Microservices - Guide

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

The purpose of this guide is for game makers to create and deploy server-authoritative C# functionality within their games with Beamable Microservices.

This guide includes everything needed to use the Microservices feature in the "Beamable SDK for Unity". Or watch this video.

📘

Related Feature

More details are covered in related feature page(s). See Microservices for more info.

Game Maker User Experience

There are 3 major parts to MicroserviceMicroservice - A Microservice architecture, or microservice, is a solution of developing software systems that focuses on building single-function modules with well-defined interfaces and operations. setup process. During development, the game maker's user experience is as follows:

Example

In this AddMyValues() example a new c# server-side MicroserviceMicroservice - A Microservice architecture, or microservice, is a solution of developing software systems that focuses on building single-function modules with well-defined interfaces and operations. is created and exposes a method to be called by any c# client-side scope.

The source-code for both server-side and client-side sits local in your Unity project for efficiency and ease-of-use.

Creating a Microservice

namespace Beamable.Examples.Features.Microservices
{
   [Microservice("MyMathMicroservice")]
   public class MyMathMicroservice : Microservice
   {
      [ClientCallable]
      public int AddMyValues(int a, int b)
      {
         return a + b; 
      }
   }
}

Calling a Microservice

namespace Beamable.Examples.Features.Microservices
{
    public class MyMathMicroserviceExample : MonoBehaviour
    {
        private MyMathMicroserviceClient  _myMathMicroserviceClient;

        protected async void Start()
        {
            var beamContext = BeamContext.Default;
            await beamContext.OnReady;

            Debug.Log($"beamContext.PlayerId = {beamContext.PlayerId}");
            
            _myMathMicroserviceClient = new MyMathMicroserviceClient();
            
            int myValues = await _myMathMicroserviceClient.AddMyValues(10, 5);
                
            Debug.Log ($"AddMyValues() Result = {myValues}");
        }
    }
}

The following steps will demonstrate how to setup that example code in a real-world project.

Getting Started With Beamable Microservices

Follow these steps to get started:

Beamable Microservices uses the industry standard Docker technology. Beamable handles all coordination and configuration.

See Microservices (Beamable & Docker) for more info.

Beamable's Docker Setup

  • Hosts the client Microservices environment and hides complexity of .Net core
  • Hosts the server Microservices environment

Order of Execution

  1. Game maker changes C# code
  2. Unity recompiles
  3. Beamable synchronizes Client <-> Server, only if needed

Step 1. Setup Docker

Name

Detail

  1. Download & Install Docker
    (Windows or Mac)

• Visit Docker.com

Note: You may skip the Docker official tutorial

  1. Open Command Line

Window: Press Windows+R to open the “Run” box. Type cmd and then click “OK”.
Mac: Open the Applications folder, then open Utilities and double-click on Terminal, or press Command+Spacebar to launch Spotlight and type Terminal

  1. Run Docker Command Line

• Type docker ps

  1. Verify that Docker is operational (With no Microservices running yet)

Step 2. Create Microservice

By design, creating Microservice C# server-code is as straight-forward as creating any traditional C# client-code. Let's take a look at an example.

Here is a traditional C# method.

public int AddMyValues(int a, int b)
{
  return a + b;
}

And here is the equivalent C# Microservice method.

[ClientCallable]
public int AddMyValues(int a, int b)
{
  return a + b;
}

Name

Detail

  1. Open the "Microservices Manager" Window

• Unity → Window → Beamable → Open Microservices Manager

  1. Create a new Microservice

• Unity → Window → Beamable → Create New Microservice

• Populate all form fields

  1. Implement the Microservice method

[ClientCallable]
public int AddMyValues(int a, int b)
{
return a + b;
}

  1. Build the Microservice

• See Beamable Microservice Manager Window

  1. Run the Microservice

• See Beamable Microservice Manager Window

  1. Play the Scene

• Unity → Edit → Play

Note: Verify that the code properly functions. This varies depending on the specifics of the game logic

  1. Stop the Scene

• Unity → Edit → Stop

With each newly created Microservice, there is auto-generated code. This serves as a working template for the game maker, who will write the actual implementation.

👍

Hot Reload

In Beamable versions 1.1 and newer, microservices only need to be started once. This also applies to the microservice's generated documentation (Microservice ⋮ → Local → View Documentation). The hot-reload functionality can be disabled from the Microservice Configuration's "Enable Hot Module Reload" option.

Example

📘

Beamable SDK Examples

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

In this example, two values will be added together and returned.

using Beamable.Server;

namespace Beamable.Examples.Features.Microservices.MyMathMicroserviceExample
{
   [Microservice("MyMathMicroservice")]
   public class MyMathMicroservice : Microservice
   {
      /// <summary>
      /// Add 2 integers and return the result.
      /// </summary>
      /// <param name="a">The first value to add</param>
      /// <param name="b">The second value to add</param>
      /// <returns>Returns the sum of the values</returns>
      [ClientCallable]
      public int AddMyValues(int a, int b)
      {
         return a + b; 
      }
   }
}

📘

Best Practices

These hints make efficent use of concepts and workflows.

• Enable Autorun of Microservices - Click the "Autorun" Button. This will start the service in Unity's PlayMode and stop the service in Unity's EditMode

Step 3. Call Microservice

By design, calling a Microservice C# server-code is as straight-forward as calling any traditional C# client-code. Choose a location in existing C# client-code, or create a new class. Then call the Microservice as shown here.

Name

Detail

  1. Create a new MonoBehaviour class

• Unity → Assets → Create → C# Script

  1. Call the Microservice

The syntax will vary depending on the Microservice

Note: Avoid passing parameters with type references to any UnityEngine and UnityEditor namespaces

Example

📘

Beamable SDK Examples

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

In this example, the Microservice is created, called, and the result is logged out to the Unity Console Window.

using UnityEngine;
using Beamable.Server.Clients;

namespace Beamable.Examples.Features.Microservices.MyMathMicroserviceExample
{
    /// <summary>
    /// Demonstrates <see cref="Microservices"/>.
    /// </summary>
    public class MyMathMicroserviceExample : MonoBehaviour
    {
        //  Properties  -----------------------------------
        
        //  Fields  ---------------------------------------
        private MyMathMicroserviceClient  _myMathMicroserviceClient;
        
        //  Unity Methods  --------------------------------

        protected void Start()
        {
            Debug.Log("Start() Instructions...\n" + 
            "* Complete docker setup per https://docs.beamable.com/docs/microservices-feature\n" +
            "* Start the server per https://docs.beamable.com/docs/microservices-feature\n" +
            "* Play This Scene\n" + 
            "* Enjoy!\n\n\n");
            
            SetupBeamable();
        }
        
        //  Methods  --------------------------------------
        private async void SetupBeamable()
        {
            var beamContext = BeamContext.Default;
            await beamContext.OnReady;

            Debug.Log($"beamContext.PlayerId = {beamContext.PlayerId}");
            
            _myMathMicroserviceClient = new MyMathMicroserviceClient();
            
            // #1 - Call Microservice with (10, 5)
            int result = await _myMathMicroserviceClient.AddMyValues(10, 5);
            bool isSuccess = result == 15;
                
            // #2 - Result = 15
            Debug.Log ($"AddMyValues() Result = {result}, Success={isSuccess}");
        }
    }
}

Advanced

This section contains any advanced configuration options and workflows.

Designing Microservices

Optionally, the Microservice can take Beamable content as input and pass Beamable player state as output. This is a suggested workflow for many game designs.

See Microservices (Designing) for more info.

Debugging Microservices

Development of Beamable Microservices within the Unity client is straight-forward and transparent. It is the ideal environment for development including debugging tools.

See Microservices (Debugging) for more info.

Deploying Microservices

During development, the Microservice is run locally within a developer-specific sandbox. When ready, the game maker can promote/deploy the Microservice to production.

See Microservices (Deploying) for more info.

Microservice Serialization

See Microservices (Serialization) for more info.

Discussion

Questions? Comments? Join the discussion in the Beamable Ask A Question Forum!

🚧

Gotchas

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

  • Unlike many Beamable features, Microservices does not require a specific Beamable Feature PrefabFeature Prefab - The drag-and-drop template for a specific Beamable product feature to be used.
  • Within the Microservice method implementation, avoid any references to UnityEngine and UnityEditor namespaces
  • For parameters passed to a Microservice method, avoid any references to UnityEngine and UnityEditor namespaces

Did this page help you?