Beamable Player-Centric API

🚧

Preview Release

This Beamable functionality is currently in-development and subject to change. Game makers are invited and encouraged to try it out, send feedback, and help shape the future of the product.

Questions? Comments? Contact us.

Overview

The "Beamable SDK for Unity" provides a main entry point to Beamable. This entry point and API will change to be more powerful and user-friendly.

Legacy Beamable API

As outlined in Learning Fundamentals the legacy API offers flexible API reference syntax of Async / Await, Callbacks, & Coroutines.

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

After that setup, game makers use the beamableAPI object as the main entry-point to Beamable functionality. Limitations of this API include that it relates to exactly one local player and most Beamable functionality within must be called asynchronously.

Beamable Player-Centric API

The Beamable Player-Centric API continues to offer a flexible API reference syntax of Async / Await, Callbacks, Coroutines, as well as Synchronous.

One Local Player
Here the game maker references the context synchronously.
Note that the PlayerId may be null during the initialization of the Beamable system.

private void MyMethodViaSynchronous()
{
    var beamContext = BeamContext.Default;
    Debug.Log($"beamContext.PlayerId = {beamContext.PlayerId}");
}

One Local Player
Here the game maker references the context asynchronously to guarantee the value PlayerId will be set.

private async void MyMethodViaAsynchronous()
{
    var beamContext = BeamContext.Default;
    await beamContext.OnReady;
    Debug.Log($"beamContext.PlayerId = {beamContext.PlayerId}");
}

Two or More Local Players
Here the game maker references 2 (or more) contexts. This is ideal for advanced use-cases such as couch-coop games.

private void MyMethodViaSynchronous()
{
    var beamContext01 = BeamContext.ForContext("MyPlayer01");
    Debug.Log($"beamContext01.PlayerId = {beamContext01.PlayerId}");

    var beamContext02 = BeamContext.ForContext("MyPlayer02");
    Debug.Log($"beamContext02.PlayerId = {beamContext02.PlayerId}")
}

After that setup, game makers use the BeamContext object as the main entry-point to Beamable functionality. Benefits of this API include that it relates to one or more local players and most Beamable functionality within may be called asynchronously or synchronously. Game makers may choose from the syntax options above (and mix-and-match them) to find what that works best for their needs.

Benefits

🚧

Legacy Concerns

• The Legacy Beamable API will continue to function. This is the publicly released version
• However, the new Beamable Player-Centric API will be recommended to all game makers upon launch. This is a feature preview

Advanced

This section contains any advanced configuration options and workflows.

Getting The Context

For advanced use-cases, the Beamable Player-Centric API has additional ways to reference the API.

Attaching Service Callbacks

Here the game maker references the context and subscribes to service changes via callback. The common Beamable services support various callbacks.

Currency OnUpdated Callback

private async void MyMethodForCurrencyCallback()
{
    var beamContext = BeamContext.Default;
    beamable.Currencies.OnUpdated += () => 
   {
        Debug.Log("The currency has been modified.");
   };
}

Common Service Callbacks

Migration

Game makers with existing Beamable projects which are using the legacy Beamable API are encouraged to migrate to the Beamable Player-Centric API

For the simplest migration instructions;

• Replace var beamableAPI = await Beamable.API.Instance; with var beamContext = BeamContext.Default;.

Preview Release

We are working on getting this feature ready, and hope to deliver a full release by Q1 2022.

If you have any questions or feedback, please reach out to us on our Discord Server!