Worlds API

Worlds functionality can also be accessed through the PlayResolver just like rooms. Worlds work a differently however and are a bit simpler.

Worlds

First we need to fetch the available Worlds. Unlike Rooms, Worlds cannot be created by a Client and need to be setup in the Developer Portal.

async Task<(IReadOnlyList<WorldData>, bool)> FetchWorlds()

FetchWorlds in PlayResolver.cs allows us to fetch the available Worlds for our project. This task returns a list of Worlds in the form of WorldsData objects and a boolean that indicates if the operation was successful.

async Task<WorldData> FetchLocalWorld()

FetchLocalWorld in PlayResolver.cs returns the local World for a local running World Server.

The WorldsConnectDialog populates a dropdown with the Worlds returned by both of these methods so we can select a World.

After we've selected a World we can connect to it using:

void JoinWorld(IClient client, WorldData data, bool isSimulator = false)

JoinWorld in PlayResolver.cs connects the Client that we pass to the method to the World we pass to the method.

The isSimulator optional parameter is used for Simulators and can be ignored for regular Client connections (see Simulators).

The WorldsConnectDialog is an example implementation for Worlds usage.

Rooms API

Rooms functionality can be accessed through the PlayResolver which includes all the methods needed to use rooms.

Regions

To manage Rooms we must first decide which region we are working with.

async Task<(IReadOnlyList<string>, bool)> FetchRegions()

FetchRegions in PlayResolver.cs allows us to fetch the regions available for our project. This task returns a list of regions (as strings) and a boolean that indicates if the operation was successful.

async Task<string> FetchLocalRegions()

FetchLocalRegions in PlayResolver.cs returns the local region string for a local running Rooms Server, or null if the operation is un-successful (if the Server isn't running for example).

Every other Rooms API will require a region string that indicates the relevant region for the operation so these strings should not be changed before using them for other operations.

The RoomsConnectDialog populates a dropdown with the region strings returned by both of these methods directly for easy selection.

Room management

After we have the available regions we can start managing Rooms, for instance:

async Task<RoomData> CreateRoom(string region, RoomCreationOptions options = null)

CreateRoom in PlayResolver.cs allows us to create a Room in the region we send it.

the RoomCreationOptions is used to optionally specify:

• a Room name

• the maximum number of Clients allowed for the Room

• a list of tags for Room filtering and other uses

• a key-value collection for the Room

This task returns the RoomData for the created Room assuming the operation was successful.

async Task<IReadOnlyList<RoomData>> FetchRooms(string region, string[] tags = null)

FetchRooms in PlayResolver.cs allows us to search for available Rooms in a region. We can also optionally specify tags for filtering the Rooms.

This task returns a list of RoomData objects for the Rooms available for our specifications.

void JoinRoom(IClient client, RoomData room, bool isSimulator = false)

JoinRoom in PlayResolver.cs connects the client that we pass to the method to the Room we pass to the method. This RoomData object can be either the one we get back from CreateRoom or one of the ones we got from FetchRooms.

When joining a Room, the method is optionally supplied if the connecting Client is a Simulator, as well.

The RoomsConnectDialog demonstrates both of these cases in CreateRoom when called with true for autoJoin and in JoinRoom respectively.

RemoveRoom in PlayResolver.cs allows us to close a Room. The uniqueID can be either the one we get back from CreateRoom or one of the ones we got from FetchRooms, but roomToken (Room's Secret) is only returned by CreateRoom.

async Task RemoveRoom(string region, ulong uniqueID, string roomToken)

The PlayResolver encapsulates all the internals to fetch and join both Rooms and Worlds.

using Coherence.Runtime;

// ensure connection to the play services backend
async Task<bool> PlayResolver.EnsurePlayConnection();

Rooms API

Detailed usage can be found under chapter Rooms.

// Returns true if there is a valid local server running.
// Returns "local" as the region if local server is running.
async Task<(bool, string)> FetchLocalRegions()

// Returns all the regions where rooms are enabled in the portal.
async Task<IReadOnlyList<string>> FetchRegions()

// Fetch a list of rooms currently active in the given region.
// Optionally, filter by tags provided when creating the room.
async Task<IReadOnlyList<RoomData>> FetchRooms(string region, string[] tags = null)

// Create a new room in the region. 
async Task<RoomData> CreateRoom(string region, RoomCreationOptions options = null)

// Convert RoomData to EndpointData, to call IClient.Connect(endpoint) directly.
// The second return value is false if the room data is invalid. 
(EndpointData, bool) GetRoomEndpointData(RoomData room)

Example usage for Rooms API:

using UnityEngine;
using Coherence.Runtime;
using Coherence.Toolkit;

public class CreatorAndJoiner : MonoBehaviour
{
    private CoherenceMonoBridge bridge;

    private async void Start()
    {
        if (!MonoBridgeStore.TryGetBridge(gameObject.scene, out bridge))
        {
            return; 
        }
        
        // XXX: try-catch everything
        var regions = await PlayResolver.FetchRegions();
        var rooms = await PlayResolver.FetchRooms(regions[0]);

        
        if (rooms.Count == 0)
        {
            var room = await PlayResolver.CreateRoom(regions[0]);
            bridge.JoinRoom(room);
        }
        else
        {
            bridge.JoinRoom(rooms[0]);  
        }
    }
}

Worlds API

Detailed usage can be found under chapter Worlds.

// Returns true if a local worlds replication server is running.
async Task<bool> EnsureLocalServer()

// Fetches the connection data for local replication server.
async Task<WorldData> FetchLocalWorld()

// Fetches a list of worlds from the portal.
async Task<IReadOnlyList<WorldData>> FetchWorlds()

// Convert WorldData into EndpointData, to call IClient.Connect(endpoint) directly.
// The second return value is false if the world data is invalid. 
(EndpointData, bool) GetWorldEndpoint(WorldData world)

Example usage for Worlds API:

using UnityEngine;
using Coherence.Runtime;
using Coherence.Toolkit;

public class WorldJoiner : MonoBehaviour
{
    private async void Start()
    {
        if (!MonoBridgeStore.TryGetBridge(gameObject.scene, out var bridge))
        {
            return; 
        }
        
        // XXX: try-catch everything
        var worlds = await PlayResolver.FetchWorlds();
        if (worlds.Count > 0)
        {
            bridge.JoinWorld(worlds[0]);
        }
    }
}

The Configure window lists all variables and methods that can be synced for the selected Prefab. Each selected element in the list is stored in the Prefab as a Binding with an associated Descriptor, which holds information about how to access that data.

By default, coherence uses reflection to gather public fields, properties and methods from each of the Prefab's components. You can specify exactly what to list in the Configure window for a given component by implementing a custom DescriptorProvider. This allows you to sync custom component data over the network.

Take this player inventory for example:

using UnityEngine;

public class Inventory : MonoBehaviour
{
    [System.Serializable]
    public class Item
    {
        public int id;
        public string name;
        public int durability;
    }

    public Item[] items = new Item[]
    {
        new Item {id = 0, name = "Shield", durability = 80},
        new Item {id = 1, name = "Stick", durability = 50},
        new Item {id = 2, name = "Stone", durability = 100},
    };

    public Item GetItem(int id)
    {
        foreach (var item in items)
        {
            if (item.id == id)
            {
                return item;
            }
        }

        return default;
    }
}

Since the inventory items are not immediately accessible as fields or properties, they are not listed in the Configure window. In order to expose the inventory items so they can be synced across the network, we need to implement a custom DescriptorProvider.

Creating a custom DescriptorProvider

The main job of the DescriptorProvider is to provide the list of Descriptors that you want to show up in the Configure window. You can instantiate new Descriptors using this constructor:

public Descriptor(string name, Type ownerType, Type bindingType, bool required=false)

• name: identifying name for this Descriptor.

• ownerType: type of the MonoBehaviour that this Descriptor is for.

• bindingType: type of the ValueBinding class that will be instantiated and serialized in CoherenceSync, when selecting this Descriptor in the Configure window.

• required: if true, every network Prefab that uses a MonoBehaviour of ownerType will always have this Binding active.

Here is an example InventoryDescriptorProvider that returns a Descriptor for each of the inventory items:

using System.Collections.Generic;
using Coherence.Toolkit;
using Coherence.Toolkit.Bindings;

[DescriptorProvider(typeof(Inventory))]
public class InventoryDescriptorProvider : DescriptorProvider
{
    public override List<Descriptor> Fetch()
    {
        // Call base.Fetch to include public fields, properties and methods
        var descriptors = base.Fetch();

        var inventory = Component as Inventory;

        foreach (var item in inventory.items)
        {
            var inventoryDescriptor = new Descriptor(name: item.name, ownerType: typeof(Inventory), bindingType: typeof(InventoryBinding));
            inventoryDescriptor.CustomData = item.id;
            descriptors.Add(inventoryDescriptor);
        }

        return descriptors;
    }
}

To specify how to read and write data to the Inventory component, we also need a custom binding implementation.

Creating a custom Binding

A Descriptor must specify through the bindingType which type of ValueBinding it is going to instantiate when synced in a CoherenceSync. In our example, we need an InventoryBinding to specify how to set and get the values from the Inventory. To sync the durability property of the inventory item, we should extend the IntBinding class which provides functionality for syncing int values.

using Coherence.Toolkit.Bindings;
using Coherence.Toolkit.Bindings.ValueBindings;
using UnityEngine;

public class InventoryBinding : IntBinding
{
    public override string BakedSyncScriptGetter => "GetItem(ItemId).durability";
    public override string BakedSyncScriptSetter => "GetItem(ItemId).durability = @";

    // Required constructor signatures
    public InventoryBinding(Descriptor descriptor, Component unityComponent) : base(descriptor, unityComponent) { }
    public InventoryBinding() { }

    public int ItemId => (int)descriptor.CustomData;

    public override int Value
    {
        get => ((Inventory) unityComponent).GetItem(ItemId).durability;
        set => ((Inventory) unityComponent).GetItem(ItemId).durability = value;
    }
}

We are now ready to sync the inventory items on the Prefabs.