Sync Property Components (Unreal Engine)
- Kyle
Everything inside the Cavrnus Plugin is built on top of the functions exposed in our API Reference. These functions are available for your development team to create custom controls, synchronization, and interactive interfaces for your Cavrnus application. The functions are also BlueprintCallable, so they can be referenced directly from blueprints, or derived into Blueprint classes (where applicable).
To get you started with basic collaboration, the Cavrnus Spatial Connector includes several Sync “X” components that can be attached to actors in your level. These are specialized blueprint components provided in the plugin that synchronize Properties of specific data types.
Component Name | Property | Data Type |
|---|---|---|
SyncVisibility | “Actor Hidden In Game” property | Boolean |
SyncNameTagText | User name in scene | String |
SyncMeshColor | Static Mesh primary material color | Vector |
SyncTransform | Actor class Position, Rotation, Scale | Matrix data |
Example Components
A Property is a piece of data on our server that should match with a piece of data in your project.
For more in-depth information on what Properties are and how they are configured, see the Cavrnus Application Development section.
Sync X Components
To configure a blueprint actor to synchronize properties between different users:
First open the blueprint in the blueprint editor and click the Add Component button.
Type “Sync” in the search field to filter all of the Sync X Property components provided with the Cavrnus plugin.
For this example let’s select Sync Local Transform.
Adding this component also adds a Cavrnus Properties Container automatically, 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 Play-in-Editor to test the performance. The Component will detect any changes your copy of the project makes to the actor’s transform, whether from the 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.
Be mindful when modifying Sync’d objects via non-user-controlled scripts.
Sync Components and Physics
For the time being, be advised that combining Sync Transform components with some forms of physics simulation may present unexpected results.
It will sometimes work but at other times, if actors constantly calculate their position based on physics, they may continue updating transient data and never finalize their move. This will make it so any other posts to the object’s position (such as from a position reset script) will appear not to work as the constant Physics changes will continue sending at the current position.
Synced Spawned Objects
When you use Cavrnus Object Spawning to create multiple instances of an object at runtime, the Cavrnus system automatically modifies each instance Unique Container Name to match the specific instance being spawned.
Basically, we handle everything for you behind the scenes, so... you’re welcome!
OK, Maybe a Little Code
If you like using the Cavrnus Components but can’t find one that synchronizes a component field quite the way you want, 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: