Binding and Displaying Properties (Unreal Engine)
- Josh Criz
- Kyle
Code workflow for initializing connectivity between asset properties and the Journal.
The primary mechanism for Collaboration using Cavrnus is Properties. As people make changes to the world they will Post() Properties to the journal.
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. This also helps avoid the error returned by Cavrnus when trying to update a property without a connection.
void APropertySyncActorClass::BeginPlay()
{
Super::BeginPlay();
// Member is delegate FCavrnusSpaceConnected SpaceConnected;
SpaceConnected.BindUFunction(this, GET_FUNCTION_NAME_CHECKED(APropertySyncActorClass, OnSpaceConnected));
UCavrnusFunctionLibrary::AwaitAnySpaceConnection(OnSpaceConnected);
}
void APropertySyncActorClass::OnSpaceConnected(FCavrnusSpaceConnection SpaceConnection)
{
UE_LOG(LogTemp, Log, TEXT("Connected to Space ID %d."), SpaceConnection.SpaceConnectionId);
}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.
void APropertySyncActorClass::OnSpaceConnected(FCavrnusSpaceConnection SpaceConnection)
{
FLinearColor CurrentValue = FLinearColor::White;
MaterialInstance->GetVectorParameterValue("Color", CurrentValue);
// ContainerName is usually assigned a unique value at runtime within the Cavrnus journal by using a CavrnusPropertiesContainer component
// PropertyName should be something unique within this object. Could just be "Color", or something more specific if there are multiple synched color properties on this actor. (e.g. "ShirtBaseColor" and "ShirtAccentColor")
UCavrnusFunctionLibrary::DefineColorPropertyDefaultValue(SpaceConnection, ContainerName, PropertyName, CurrentValue);
}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.
void APropertySyncActorClass::OnSpaceConnected(FCavrnusSpaceConnection SpaceConnection)
{
...
// Member is delegate FColorPropertyUpdated OnMaterialColorPropertyUpdated;
OnMaterialColorPropertyUpdated.BindUFunction(this, GET_FUNCTION_NAME_CHECKED(APropertySyncActorClass, SetMyMaterialColor));
MaterialColorBinding = UCavrnusFunctionLibrary::BindColorPropertyValue(SpaceConnection, ContainerName, PropertyName, OnMaterialColorPropertyUpdated);
}
void APropertySyncActorClass::SetMyMaterialColor(FLinearColor Color)
{
MaterialInstance->SetVectorParameterValue("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 properties.