Cavrnus Unreal API - ValueSyncs

Owned by Kyle
Last updated: Jul 18, 2024
2 min read

The header files within the ValueSyncs folder, along with IPropertySyncInterface.h, form a structured system for synchronizing property values between Unreal Engine and the Cavrnus platform. These are the primary methods for synchronizing properties with the Journal to create a collaborative virtual experience.

Key Points:

  • This structure allows for flexible and type-safe synchronization of various property types between Unreal Engine and Cavrnus.

  • The UCavrnusValueSyncBase class handles the common synchronization logic, while the derived classes provide specialized handling for their respective data types.

  • The system is designed to be extensible, allowing for the addition of new property types as needed.

General Workflow (How Syncs Work):

The separation of temporary and final updates allows for smooth user interactions while ensuring data consistency.

  1. Attachment: A UCavrnusValueSyncBase-derived component is attached to an Unreal Engine actor that owns the property to be synchronized.

  2. Property Identification: The PropertyName property is set to the name of the property within the actor.

  3. Polling and Updates: The UCavrnusValueSyncBase component periodically polls the property value. If it detects a change and SendChanges is true, it sends an update to the Cavrnus platform.

  4. Receiving Updates: The Cavrnus platform can send property updates back to Unreal Engine. The UCavrnusValueSyncBase component receives these updates and applies them to the corresponding property on the actor.

Base Class (UCavrnusValueSyncBase):

  • Purpose: This abstract class serves as the foundation for all live property update classes. It provides essential functions for managing the update process, such as:

    • Cancel(): Cancels any ongoing property updates.

    • GetLastUpdatedTimeSeconds(): Retrieves the time elapsed since the last update.

  • Key Members:

    • livePropertyUpdate: A pointer to the underlying implementation of the property update (likely in the Cavrnus backend).

  1. UCavrnusValueSyncBase:

    • This abstract class inherits from USceneComponent (allowing it to be attached to Unreal Engine actors) and implements the IPropertySyncInterface.

    • It provides a foundation for synchronizing properties, including:

      • Polling for property changes.

      • Sending updates to the Cavrnus platform.

      • Handling space connections.

    • Key properties include PropertyName (the name of the property to sync) and SendChanges (whether to send updates).

Derived Classes (Specific Property Types):

  • The folder contains several classes derived from UCavrnusValueSyncBase, each specializing in a specific property type:

    • UCavrnusValueSyncBoolean: Synchronizes boolean values.

    • UCavrnusValueSyncFloat: Synchronizes float values.

    • UCavrnusValueSyncString: Synchronizes string values (FString).

    • UCavrnusValueSyncVector: Synchronizes vector values (FVector).

    • UCavrnusValueSyncTransform: Synchronizes transform values (FTransform).

    • UCavrnusValueSyncColor: Synchronizes color values (FLinearColor).

Common Functionality:

Each derived class typically provides the following functions:

  • IPropertySyncInterface:

    • This interface defines the contract for property synchronization, requiring implementing classes to provide methods for getting and setting property values (GetPropertyValue and SetPropertyValue).

Blueprint Integration:

  • Each property-specific class provides Blueprint-callable functions (e.g., GetBoolean, SetBoolean) to get and set the property value, making it easy to integrate with Unreal Engine's visual scripting system.