Learning Fundamentals

The purpose of this guide is to demonstrate everything needed for game makers to migrate an existing Beamable project to the latest version of the "Beamable SDK for Unity".

Getting Started

Game makers who already have a basic understanding of Unity and C# are invited to begin here: Installing Beamable.

Learning Fundamentals

Game makers who are new to Unity and C# can review the fundamentals here.

C# Basics

📘
Beamable SDK Examples
• The following example code is available for download at GitHub.com/Beamable_SDK_Examples

Assembly Definitions
Asynchronous Programming
Custom Build Scripts
Promise Programming
Unit Testing

Assembly Definitions

Beamable is compatible with, but does not necessarily require Unity's Assembly Definitions (Asmdef). As a best practice, many teams choose to use them. Assembly Definitions and Assembly References are assets that you can create to organize your scripts into assemblies.

Benefits

Better project organization
Better code modularity
Faster project compilation times

Beamable Asmdef File Examples

Runtime	Editor	Tests

Beamable Asmdef Project Examples

See these downloadable projects for more info.

	Feature	Detail
	Beamable SDK Examples	Collection of Beamable code snippets Note: More Example Projects may be updated in the future.
	Leaderboards (ABC) - Sample	Collection of Beamable code snippets Note: More Sample Projects may be updated in the future.

Asynchronous Programming

The C# main entry point for Beamable is the Beamable.API.Instance object. There are several ways to write asynchronous code with C# in Unity. All are compatible with Beamable. Three popular ways are shown below.

Asynchronous Programming Examples

The following example(s) are taken from Beamable SDK Examples/.../AsynchronousProgramming/.

1. Async / Await

Use the async method modifier to mark the method as asynchronous. Use the await keyword when calling an async method to treat the call as asynchronous. Using async and await together provides powerful, flexible results with just a few lines of code. It guarantees that the data needed is available at the proper timing. This is especially important here since this client API is interacting with the server and there may be inherent latency involved. See Microsoft's Guide To Asynchronous C# for more info.

Here the method is called as await MyMethodViaAsyncAwait(); and the implementation is as follows;

private async void MyMethodViaAsyncAwait()
{
    var beamableAPI = await Beamable.API.Instance;
    Debug.Log($"beamableAPI.User.id = {beamableAPI.User.id}");
}

2. Callback

Here the method is called as MyMethodViaCallback(); and the implementation is as follows;

private void MyMethodViaCallback()
{
    Beamable.API.Instance.Then(beamableAPI =>
    {
        Debug.Log($"beamableAPI.User.id = {beamableAPI.User.id}");
    });
}

3. Coroutine

Here the method is called as StartCoroutine(MyMethodViaCoroutine()); and the implementation is as follows;

private IEnumerator MyMethodViaCoroutine()
{
    var promise = Beamable.API.Instance;
    yield return promise.ToYielder();
    var beamableAPI = promise.GetResult();

    Debug.Log($"beamableAPI.User.id = {beamableAPI.User.id}");
}

Custom Build Scripts

When building Unity, you sometimes want to modify the built player in some way. Use the PostProcessBuild to define the execution order for your build methods, and call your external scripts.

Custom Build Scripts Examples

The following example(s) are taken from Beamable SDK Examples/.../CustomBuildScripts/.

using UnityEditor;
namespace Beamable.Examples.LearningFundamentals.CustomBuildScripts
{
    public static class MyCustomBuildScript 
    {
        [PostProcessBuild]
        public static void OnPostProcessBuild(BuildTarget target, string path)
        {
            //This runs after compiling Unity and before native platform (such as Xcode for iOS).*
            Debug.Log($"MyCustomBuildScript.cs, OnPostProcessBuild({target})");
        }
     }
}

Promise Programming

A promise is an object that may produce a single value some time in the future: either a resolved value, or a reason that it’s not resolved (e.g., a network error occurred). Beamable includes a custom Promise library available for use by game makers.

The Beamable Promise is flexible and powerful. It can be executed alone, in groups, serially, in batches, and in parallel.

Promise Programming Examples

The following example(s) are taken from Beamable SDK Examples/.../PromiseProgramming/.

Promise

Here the promise can be created per #1 and observed per #3, before the value is even ready. That is the power of promises. If/when the value is resolved (per #3 in this case), then the result is available.

using Beamable.Common;
using UnityEngine;
using UnityEngine.Assertions;

namespace Beamable.Examples.LearningFundamentals.PromiseProgramming
{
    public class PromiseProgrammingExample2 : MonoBehaviour
    {
        protected void Start()
        {
            StringPromiseWithCompleteSuccess();
        }
        
        // Executes in order of 1 then 2 then 3
        private void StringPromiseWithCompleteSuccess()
        {
            // 1. Arrange
            var stringPromise = new Promise<string>();
            
            stringPromise.Then(result =>
            {
                // 3. Assert
                Debug.Log($"stringPromise.Then() result = {result}");
                Assert.AreEqual(result, "Hello World!");
            });

            // 2. Act
            stringPromise.CompleteSuccess("Hello World!");
        }
    }
}

Map

The Map method takes a promise of type A, and returns a promise of type B with a conversion applied.

[1,2,3].map(x => x *2) // Returns [2,4,6]

The Map method converts the type of the promise to something else. For example, you have a network request that gives back a full request object, like a User object, but you only want to get the .email field.

var userPromise = SomeApi.GetUser(); // Returns Promise<User>
var emailPromise = userPromise.Map(user => user.email); // Returns Promise<string>

FlatMap

The FlatMap method takes a promise of type A, and returns a promise of type B with a conversion applied and the promise hierarchy is flattened. For example, here you are given a player's user as an argument, but want to get the inventory.

var userPromise = SomeApi.GetUser(); // Returns Promise<User>

var inventoryPromise = 
      userPromise.FlatMap(user => SomeOtherApi.GetUserInventory(user)); // Returns Promise<Inventory>

inventoryPromise.Then(inventory => {
    // Use the inventory
});

Map vs FlatMap

In the previous example, if you had used Map instead of FlatMap, you'd have a more complex Promise<Promise<Inventory>> and you'd have to call Then multiple times before using it.

Both Map and FlatMap are useful generally better than having to call Then multiple times.

Unit Testing

Beamable is compatible with, but does not necessarily require Unity's Unit Testing. As a best practice, many teams choose to use unit testing.

Benefits

Encourages KISS
Bugs are found easily and fixed quickly
Provides a 'living documentation' to core systems

Unit Testing Examples

Examples are available Beamable SDK Examples/.../Tests/.

Also, each downloadable project mentioned in Assembly Definitions also has several Unit Tests included for educational purposes.

Learning Resources

These learning resources provide a better way to build live games in Unity.

	Feature	Detail
	Prototyping With Unity	Quickly develop new games & features
	Game Jams With Unity	Boost development skills with friendly competition

Learning Fundamentals

Getting Started