Code

Create and deploy server-authoritative C#

Overview

Here is everything needed to use the Microservices feature in the "Beamable SDK for Unity".

The purpose of this feature is to allow game makers to create and deploy server-authoritative C# functionality within their games.

This feature eliminates the need to build, run, and scale a game server. Game makers can create server-authoritative logic in C# inside the Unity editor.

📘

Related Guides & Video

A common use case for the feature is covered in the guides. See Adding Microservices for more info.

Example

Here 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("MyMicroservice")]
  public class MyMicroservice  : CustomMicroservice
  {
  
    [ClientCallable]
    public int GetLootboxReward()
    {
      Console.WriteLine("GetLootboxReward()");
      
      // if (IsAllowed), then reward 100 gold
      return 100;
    }
  }
}

Calling a Microservice

namespace Beamable.Examples.Features.Microservices
{
   public class MyMicroserviceExample : MonoBehaviour
   {
      private MyMicroserviceClient  _myMicroservice;

      protected void Awake ()
      {
        _myMicroservice = new MyMicroserviceClient();

        _myMicroservice.GetLootboxReward()
            .Then(OnServerCallCompleted);
      }

      private void OnServerCallCompleted(int result)
      {
         // Result:100
         Debug.Log ($"Result:{result}");
      }
   }
}

Why Beamables Microservices?

Beamable's Microservice FeatureFeature - An individual aspect of the Beamable product used to create a great user experience is custom-built to provide the best workflow and performance for game makers.

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. See Wikipedia for more info.

Benefits

  • Highly maintainable & testable
  • Loosely coupled
  • Independently deployable

Like never before, programming a server-authoritative feature feels like a natural extension of your favorite client-side tools and workflows — powered by Beamable Microservices.

Now all your code lives in one place — shared between client and server.

The Microservice code is checked in alongside your client code to version control. With Beamable, there is less code since the system shares and serializes all client/server data structures.

Comparison

Beamable
C# Microservices

Amazon AWS Lambda

GameSparks
Cloud Code

Microsoft PlayFab
Cloud Script

C# Client Code

✔️

✔️

✔️

✔️

C# Server Code

✔️

Full Debugging Support
(Debug.Log, Breakpoints, etc...)

✔️

Source Control Integration

✔️

Runs Locally During Development

✔️

Unity Workflow
(ScriptableObjects, etc...)

✔️

There are trade-offs as well. Games using server technology like Microservices must be connected to the internet, each server-side operation call is slower than a client-side operation due to network latency, and there are fees incurred to host or use servers.

Server-Authoritative Benefits

Typically in game development, game code is on the game client. This is a client-authoritative approach. Moving functionality to the back-end is a server-authoritative approach. There are pros and cons.

Invariably — today's games grow to need server-authoriative code.

Comparison: Client vs Server Benefits

Client-Authoritative

Server-Authoritative

Speed Of Development

✔️

Speed At Runtime

✔️

Speed To Release Updates

✔️

High Security (Anti-Cheat)

✔️

Beamable Microservices Features

Features

Beamable provides an SDK that enables game makers to easily add social, commerce and content management FeatureFeature - An individual aspect of the Beamable product used to create a great user experiences.

The available features vary by context.

API Entry Points

  • C# Client Code - Access via Beamable.API from a context outside of Microservices
  • C# Server Code (Microservice) - Access via Services from a context inside of a Microservice

Feature Comparison

Examples

Example: Client-Authoritative

Imagine an in-game treasure chest ("loot box") containing a random prize for the player. The player is offered the loot box as a reward for progress in the game, opens the box, and receives the prize.

In a simple game with little or no back-end technology, the prize is offered, validated, and rewarded on the client-side. This is straight-forward to code, but is relatively insecure to any malicious hackers in the gaming community.

Example: Server-Authoritative

Now imagine some portion of the loot box code is moved to the server.

Now the the prize is offered, validated, and rewarded on the server-side. This is less straight-forward to code, but is relatively secure against any malicious hackers in the gaming community.

The benefits of a server-authoritative architecture are great. There are a few major ways to set it up.

A development team could write a custom back-end server setup. This is considerable time and effort, even for experienced teams. The team could choose an off-the-shelf solution. Beamable's Microservice feature provides power and ease of use.

Example: Beamable Microservice

Let's see how Beamable can help.

Imagine some portion of loot box code is moved to the server as a Beamable Microservice.

The prize is offered, validated, and rewarded on the server-side as a Microservice. The Microservice code sits in your Unity project along-side your client side code and is written in the familiar and powerful C# language. It is straight-forward to code and it is secure against any malicious hackers in the gaming community.

Advanced

This section contains any advanced configuration options and workflows.

Beamable & Docker

Beamable Microservices uses the industry standard Docker technology. Docker simplifies and accelerates your workflow, while giving developers the freedom to innovate with their choice of tools, application stacks, and deployment environments for each project. See Docker's documentation for more info.

Beamable handles all coordination and configuration of Docker including the beamableinc/beamservice base image hosted on Docker's DockerHub.

Designing Microservices

Here are some optional, suggested Beamable data types to use along with Microservices. The Microservice can take Beamable content as input and pass Beamable player state as output. Of course, game makers may choose whatever pattern helps the specific needs of their games.

Here is a partial list of examples.

Input

Output

Example

Currency

Inventory

An RPG game client sends a request for the hero to purchase new armor. The server validates the transaction, deducts player currency and updates the player inventory

ContentObject

Stat

A Boss-Battle game client sends the Boss ContentObject and the Hero's Sword ContentObject. The server updates the BossHealth Stat according to the damage inflicted

List of Player Moves

Winning Player

A checkers game can validate and declare winner. The client sends a complete list of all the players' moves and the server processes the result

Stat

Leaderboard Score

A platformer game client notifies that the player has completed level 3. The server validates that the user has previously completed level 1 and 2 (as required) and updates the player's high-score

Designing Microservice Methods

When designing each microservice method, a key question is 'Who is allowed access?'. Game makers control this access with Microservice method attributes.

Microservice Method Attributes

Name

Detail

Accessible Via?

[AdminOnlyCallable]

Method callable by any admin user account

Microservices OpenAPI

[ClientCallable]

Method callable by any user account

Microservices OpenAPI and Unity C# Client

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, safely isolated from the production environment.

Using the Beamable Microservices Manager Window in the Unity Editor, the game maker can promote/deploy the Microservice to production. Choose the destination RealmRealm - Unique body of data in the Beamable back-end. Each realm represents a game environment and press the 'Publish' Button.

As needed, the Microservice can be rolled-back there as well.

Deployment Size Profile

Each Microservice is given a size profile upon deployment.

Name

Detail

Benefit

Default

Small

Deployment is not scalable

Note: This is ideal for development

More economic

Large

Deployment is scalable (e.g. Geographic scalability &
Load scalability)

More flexibility

✔️

Managing Deployed Microservices Via Portal

With the Portal, game makers can view and manage the deployed Microservices.

Name

Details

  1. Status

Shows the current and deploying Microservices

  1. Metrics

Shows the metrics

  1. Logs

Shows the logs

  1. Docs

Shows the OpenAPI docs. See Debugging (Via OpenAPI) for more info

  1. Deployments

Shows the historic deployments of Microservices

  1. New Deployment

Allows game makers to make a new deployment

  1. View

Allows game makers to view new deployment

Making Beamable Calls From A Microservice

Each custom Microservice created extends the Beamable Microservice class.

This gives the custom Microservice access to key member variables;

  • Context - Refers to the current request context. It contains info including what DBIDDBID - The database identification. Beamable generates an anonymous account for the player when the project first runs is calling and which path is run
  • Requester - It can be used to make direct (and admin privileged) requests to the rest of the Beamable Platform
  • Services - The powerful Microservice entry-point to Beamable's StatsService, InventoryService, and more

Example

Below are two versions of the same method call with varied implementations. Notice that #2 handles more functionality on the Microservice-side and is thus more secure.

#1. Method Without Beamable Services

Here the eligibility of reward is evaluated and the amount is calculated. This assumes the client side will handle the rewarding of the currency.

[ClientCallable]
public int GetLootboxReward()
{
  // if (IsAllowed), then reward 100 gold
  return 100;
}

#2. Method With Beamable Services

Here the eligibility of reward is evaluated, the amount is calculated, and the currency is rewarded.

[ClientCallable]
public async Task<bool> GetLootboxReward()
{
  // if (IsAllowed), then reward 100 gold
  await Services.Inventory.AddCurrencies(
    new Dictionary<string, long> {{"currencies.gold", 100}});

  // Optional: Return success, if needed
  return true;
}

Microservice Serialization

Unity's built-in features use Unity's serialization.

However, within a Beamable's Microservice, game makers must rely instead on Beamable's custom SerializationSerialization - The automatic process of transforming data structures for read/write storage. This serialization is strict and has limitations.

Types

Supported Types

Unsupported Types

Microservice Serialization Supported Types

• All other types

UseLegacySerialization

A breaking change is introduced in Beamable SDK v0.11.0. If you began your project with an earlier version of the SDK, see Beamable Releases Unity SDK Version 0.11.0 for more info. Otherwise, simply disregard this issue.


Did this page help you?