HomeGuides
HomeGuidesLearn about the Immerse SDK installerLog In

Yield Instructions

📘

This feature requires the Immerse SDK Enterprise Edition

This is different to the free Immerse SDK. Contact [email protected] if you require access.

Understand the difference between the Free and Enterprise SDK

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.

WaitForConnectionStatus

This is the most commonly used yield instruction. 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 ... 
    }
}