Learning Fundamentals

The basics of Unity and C#

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.

Learning Fundamentals

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

C# Basics

📘

Beamable SDK Examples

This and all examples are available for download at GitHub.com/Beamable_SDK_Examples

Table Of Contents

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

Back to Top

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

Back to Top

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

Back to Top

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

Back to Top

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


Did this page help you?