Sync Property Components (Unity)

Everything inside the Cavrnus Plugin is built on top of the functions exposed in our API Reference. However, those are boring and complicated, and there’s a good chance you won’t need them.

For basic collaboration, we provide Unity Components that you can attach to objects in your Scene to synchronize their Properties.

We go into more depth on what Properties are here, but in short a Property is a piece of data on our server that should match with a piece of data in your project.

Sync X Components

To synchronize Objects between users, first select the Object in question and click Add Component.

If you type “Sync” you should see autocomplete options for the Property Synchronizers we provide. For this example let’s select Sync Local Transform.

Adding this component does two things. It adds a Sync Transform component, and it adds a Cavrnus Properties Container if one is not already present.

It will auto-fill a Property Name based on the type of the component, but this can be changed to whatever string you want. The Cavrnus Properties Container will also automatically fill in a Unique Container Name based on the object’s hierarchy.

Aside: Cavrnus Properties Container

All Property values exist inside of a “Container”. This is really just a fancy word for a unique string lookup. When a Cavrnus Properties Container is added to an object it will attempt to fill in its Unique Container Name. All Sync Components on that object node will use this as their Container.

Example: An object named “NPC” is given a Sync Transform script and a Sync Visibility script. These automatically add a Cavrnus Properties Container with the Unique Container Name of “NPC”. Therefore, these objects properties exist at “NPC/Transform” and “NPC/Visibility”.

If “NPC” had a child object named “Sword”, its Unique Container Name would automatically fill out as “NPC/Sword”. This name is absolute, and once written does not reference its parent, etc. So if you then dragged “Sword” to the root of the scene it would still have the filled-in name “NPC/Sword”, and likewise if you dragged a new object under “NPC” it would not automatically prefix its Container name. Basically, what you see on the component is what you get.

Sync X Components At Runtime

Now that you have a Sync Transform component added to your object, you can hit “Play”! The Component will detect any changes your project makes to the Transform, whether via Unity UI or code, and push the new value out to other users. It will do this smartly, sending Transient values until the object stops moving, at which point it will finalize to the journal.

PERFORMANCE NOTE: These components will always be monitoring for & sending local changes to object properties. In the course of normal user interactions this shouldn’t be a problem. However, if you have a lot of objects that are programmatically being modified while your scene is playing, this could potentially cause issues with the websocket. Programmatically changing objects can also result in multiple users “fighting” to send the same change as both of their machines run the script in question. While the logic of this would resolve fine on our servers, it would exponentially increase the number of messages being sent over the wire as more users join.

Basically, be mindful when modifying Sync’d objects via non-user-controlled scripts.

Sync Components and Physics

For the time being, it is advised to avoid combining Sync Components with Rigidbodies.

It will sometimes work, but at other times the objects will continue moving due to physics and never finalize their move. This will make it so any other posts to the object’s position (say from a position reset script) will appear not to work as the constant Physics changes will continue sending at the current position.

There are plans to address this issue in future updates. If this is a highly-desired feature for you, please let us know!

Synced Spawned Objects

When you use Cavrnus Object Spawning to create multiple instances of an object at runtime, we automatically modify its Unique Container Names to match the specific instance being spawned.

Basically, we handle everything for you behind the scenes, so from your perspective it should all just work.

OK, Maybe a Little Code

If you like using the Cavrnus Components but can’t find one that affects a component field you need to synchronize, it is very easy to make your own Components.

Ultimately, all Cavrnus needs to synchronize data is a means of checking what you have locally on your machine, and a way to update it with new data from the server.

To create this, make a new class extending CavrnusValueSyncX (X being the type of property you wish this to be; we support bool, float, string, Color, Vector4, and Transform). Then implement GetValue() and SetValue(X value).

Here is an example Synchronizer for the HitPoints field of a class called Npc:

using CavrnusSdk.PropertySynchronizers;

public class SyncHitPoints : CavrnusValueSyncFloat
{
    public override float GetValue()
    {
        return GetComponent<Npc>().HitPoints;
    }

    public override void SetValue(float value)
    {
        GetComponent<Npc>().HitPoints = value;
    }
}