Adding Microservices

Overview

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

Here is 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

During development, the game maker's user experience is as follows. 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.

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 beamableAPI = await Beamable.API.Instance;

            Debug.Log($"beamableAPI.User.id = {beamableAPI.User.id}");
            
            _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 http://www.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.

Example

📘

Beamable SDK Examples

This and all examples are 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

This and all examples are 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 beamableAPI = await Beamable.API.Instance;

            Debug.Log($"beamableAPI.User.id = {beamableAPI.User.id}");
            
            _myMathMicroserviceClient = new MyMathMicroserviceClient();
            
            // #1 - Call Microservice with (10, 5)
            int myValues = await _myMathMicroserviceClient.AddMyValues(10, 5);
                
            // #2 - Result = 15
            Debug.Log ($"AddMyValues() Result = {myValues}");
        }
    }
}

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?