Yield Instructions

A set of Yield Instructions are available in the Platform Services package that make it easier to develop features that require certain network states before executing. For example, a message will be lost if it is sent before the client is connected.

Yield Instructions can be used with Coroutines. An example of each of the included yield instructions can be found below.

Single User Sessions

WaitForSessionStatus

When launching a single user session, we only need wait for the user to be authenticated. Once a user is authenticated, they are able to send messages to the platform such a reporting statements.

The example below shows how to use this yield instruction to wait until the user is authenticated.

using System.Collections;
using System.Collections.Generic;
using ImmerseSDK.PlatformServices;
using UnityEngine;

public class WaitForSessionStatusExample : MonoBehaviour
{
    private IEnumerator Start()
    {
        // Wait until the user is authenticated
        yield return new WaitForSessionStatus(SessionStatus.Authenticated);
        
        // Print the current session status
        Debug.Log("Session Status: " + Session.Status);
    }
}

Multi User Sessions

WaitForConnectionStatus

This is the most commonly used yield instruction for multi-user applications. It is used to wait for a Network status.

The example below will wait until the network client is ‘Connected’ before printing the current network status. Other connection statuses can also be used to keep the user informed of their current connection status.

using System.Collections;
using ImmerseSDK.PlatformServices;
using ImmerseSDK.PlatformServices.Multiuser;
using UnityEngine;

public class WaitForConnectionStatusExample : MonoBehaviour
{
    public IEnumerator Start()
    {
        // Wait until the session is connected
        yield return new WaitForConnectionStatus(ConnectionStatus.Connected);
        
        // Print the current network status
        Debug.Log("Connection Status: " + Networking.Status);
    }
}

WaitForImmerseClock

The WaitForConnectionStatus yield instruction will return the connection status as soon as it changes. In the case of ConectionStatus.Connected, this will occur before any messages have been received, including the clock message, which means that querying the server time at this point will return 0. This causes a problem when trying to synchronize animations/events based on the server time.

The WaitForImmerseClock yield instruction waits for the first clock message to be received. An example is shown below that will keep a Timeline synchronized for all users by using the server clock.

using System.Collections;
using ImmerseSDK.PlatformServices;
using ImmerseSDK.PlatformServices.Multiuser;
using UnityEngine;
using UnityEngine.Playables;

/// <summary>
/// Synchronize timeline playback
/// </summary>
public class TimelineExample : MonoBehaviour
{
    [SerializeField]
    [Tooltip("Timeline to control")]
    private PlayableDirector _playableDirector;

    public IEnumerator Start()
    {
        // Wait until the first clock message is received
        yield return new WaitForImmerseClock();

        // Set the playback time of the PlayableDirector to the server time
        _playableDirector.time = Networking.Client.Time.RelativeClockSmoothed;
    }
}

WaitForMessageQueue

If once connected, you do not automatically start the message queue or if you have paused the message queue during your application, you may want to wait until that message queue has started before executing some code.

The WaitForMessageQueue yield instruction waits until the provided message queue is running before continuing. Note that the message queue will not exist until you are connected, so you will often need to couple this with WaitForImmerseClock.

Because the use case for this yield instruction is very rare, a common example is hard to define. So a generic example of it’s implementation is provided below.

using System.Collections;
using ImmerseSDK.PlatformServices;
using ImmerseSDK.PlatformServices.Multiuser;
using UnityEngine;
using UnityEngine.Playables;

public class WaitForMessageQueueExample : MonoBehaviour
{
    public IEnumerator Start()
    {
        // Wait until we are connected to the multi-user service
        yield return new WaitForConnectionStatus(ConnectionStatus.Connected);
        
        // Wait until the message queue has started
        yield return new WaitForMessageQueue(Networking.Client.MessageQueue);

        // Execute code ... 
    }
}