Binding and Displaying Properties

TODO: Add an Image of a cool Cavrnus thing showing Properties in use

The primary mechanism for Collaboration using Cavrnus is Properties. As people make changes to the world they will Post() Properties to the journal (as explained here[TODO: LINK] and here[TODO: LINK]).

However, while the ways in which properties are posted are varied, all Applications using Cavrnus must Bind() those Properties in order to display them to users. To do so, you can use these simple steps.

Await the CavrnusSpaceConnection

If an object is sitting in your Scene ahead of time, you won’t be able to do any Property/Synchronization work with it until you are connected to a Space. A call to AwaitAnySpaceConnection gives you the Space Connection needed to begin the actual work.

using CavrnusSdk.API;
using UnityEngine;

private CavrnusSpaceConnection spaceConn;

private void Start()
{
    CavrnusFunctionLibrary.AwaitAnySpaceConnection(spaceConn => OnConnectedToSpace(spaceConn));
}

private void OnConnectedToSpace(CavrnusSpaceConnection spaceConn)
{
    this.spaceConn = spaceConn;
}

Initialize Default Value

As soon as we are connected to a space, and before we Bind() any Properties, we need to tell the system what the Default Value of our property is. This is the value that the Journal will use when no property value is set on the server.

Without this step, the Bind() call will provide a “null” value (such as an empty-string or a [0,0,0,0] vector), until a proper value is posted to the server.

private void OnConnectedToSpace(CavrnusSpaceConnection spaceConn)
{
    ...
    
    spaceConn.DefineColorPropertyDefaultValue(ContainerName, PropertyName, GetComponent<MeshRenderer>().material.color);
}

Bind Current Journal Value & Update Application on Changes

Once we have set up our default value, we can now Bind() its changes. Whenever someone Posts a change to the server and we receive it, the Bind() call will trigger, allowing us to update the local Application to reflect the server’s value.

private void OnConnectedToSpace(CavrnusSpaceConnection spaceConn)
{
    ...
    
    spaceConn.BindColorPropertyValue(ContainerName, PropertyName, c => SetMyMaterialColor(c));
}

public void SetMyMaterialColor(Color color)
{
    GetComponent<MeshRenderer>().material.color = color;
}

If you were building an application that was “readonly” (say, a Digital Twin viewer where the data was being provided to the Journal elsewhere) then this is all you would need.

However, if you want your Application Users to be able to make their own changes to a Space, you will need to permit them to Post(TODO:LINK) properties.