Beamable Player-Centric API
Provide power and flexibility to the game maker
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
Benefits | Legacy API | Player-Centric API |
---|---|---|
Flexible creation syntax (Async / Await, Callbacks, & Coroutines) | ✔️ | ✔️ |
Flexible service method calls syntax (Async / Await, Callbacks, Coroutines & Synchronous) | ✔️ | |
Supports 2+ Local Players | ✔️ | |
Designed for Testability | ✔️ | |
Optimized for Lazy Initialization | ✔️ |
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.
Syntax | |
---|---|
var beamContext = BeamContext.Default; | Default. This is suggested for most use-cases |
var beamContext = BeamContext.ForContext("MyPlayer01"); | Ideal for games with 2+ local players |
var beamContext = BeamContext.ForContext(this); | Traverses the hierarchy for relevant configuration data. Advanced Users Only |
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
Name | Detail |
---|---|
OnLoadingStarted | Invoked when the service starts loading Example: beamable.Currencies.OnLoadingFinished |
OnLoadingFinished | Invoked when the service finishes loading |
OnUpdated | Invoked when the service updates |
OnDataUpdated | Invoked when the service data updates |
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;
withvar 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!
Updated about 1 month ago