Overview

To make use of the shared logic and features of the Metaplay SDK, you need to be able to connect to the server and further manage your game's state. Although the Hello World sample comes with an ApplicationStateManager implemented, you'll probably want to integrate the connection logic into your own state manager.

Establishing connection

As a starting point, we recommend using the ApplicationStateManager that is included in your default Metaplay integration to connect to the server. However, if you already have your own state management system, then there are a few steps you need to go through to connect to the Metaplay server.

The first thing you need to do is to define and initialize the MetaplayClient class.

StateManager.cs

/// <summary>
/// Declare concrete MetaplayClient class for type-safe access to player context from game code.
/// </summary>
public class MetaplayClient : MetaplayClientBase<PlayerModel>
{
}

public class StateManager : MonoBehaviour, IMetaplayLifecycleDelegate
{
    ... 

    /// <summary>
    /// Game specific initializion code
    /// </summary>
    public void Init()
    {
        MetaplayClient.Initialize(new MetaplayClientOptions
        {
            // Hook all the lifecycle and connectivity callbacks back to this class.
            LifecycleDelegate = this,

            // Check out the other members from MetaplayClientOptions,
            // these are optional but have useful settings 
            // or provide useful information.
        });
    }
}

The MetaplayClient requires frame updates to keep track of the connection, so you'll also need to add a call to MetaplayClient.Update() in your update loop. Note that it is important that the MetaplayClient keeps receiving the Update call, therefore it might be useful to have a dedicated DontDestroyOnLoad class that invokes it every frame.

StateManager.cs

public class StateManager : MonoBehaviour, IMetaplayLifecycleDelegate
{
    ... 

    public void Update()
    {
        MetaplayClient.Update();
    }
}

Next, we're ready to establish the connection. When the game is ready to connect (when a loading screen is visible for the user, for example), just call MetaplayClient.Connect().

StateManager.cs

public class StateManager : MonoBehaviour, IMetaplayLifecycleDelegate
{
    ... 

    public void OnLoadingScreenBecameVisible()
    {
        MetaplayClient.Connect();
    }
}

You might have noticed that we're implementing the IMetaplayLifecycleDelegate interface, which enables you to receive callbacks when a session has been established, lost, or failed for any reason.

Finally, we recommend that you set a ClientListener in the state manager. ClientListeners are used by models and actions to communicate changes from the shared game logic code into the Unity world: for example, you can use them to update the UI or other visuals.

StateManager.cs

public class StateManager : MonoBehaviour, IMetaplayLifecycleDelegate
{
    ... 

    /// <summary>
    /// A session has been successfully negotiated with the server. 
    /// At this point, we also have the relevant state initialized
    /// on the client, so we can move on to the game state.
    /// </summary>
    void IMetaplayLifecycleDelegate.OnSessionStarted()
    {
        // Hook up to updates in PlayerModel.
        // This can be the same class, 
        // however it has to implement `IPlayerModelClientListener`
        MetaplayClient.PlayerModel.ClientListener = this;

        // Continue with your loading sequence here.

        // At this point, the player state is available. 
        
        // For example, the following are now valid:
        // Access player state members: MetaplayClient.PlayerModel.CurrentTime
        // Execute player actions: MetaplayClient.PlayerContext.ExecuteAction(..);
    }
}

Further Reading

You can learn more about listeners on the Client and Server Listeners page. It's also noteworthy that server listeners exist and can be used on the server to trigger server-only actions and other behaviors.