API Reference - Unreal

Owned by bert
Last updated: Jul 19, 2024 by Kyle
5 min read

Welcome to the Cavrnus Unreal Engine API Reference! This document is designed to help you harness the power of Cavrnus to create your own custom applications within Unreal Engine. While our Cavrnus No-Code solutions take care of all of the details automatically, you can also leverage the Cavrnus API to tightly integrate collaboration in your own custom 3D application tools. The following pages will describe how the Cavrnus API provides the tools you need to build rich, interactive experiences in a seamless real-time collaboration environment.

Getting Started

This reference is organized into 2 sections:

Cavrnus Types

Detailed descriptions of the core Cavrnus data types, such as:

  • FCavrnusSpaceConnection: Represents a user's connection to a space.

  • FCavrnusAuthentication: Stores authentication tokens for user logins.

  • FCavrnusSpaceInfo: Provides information about a specific Cavrnus space.

  • FCavrnusUser: Represents an individual user within a space.

  • FCavrnusLiveXPropertyUpdate: Used for sending temporary property updates.

  • FCavrnusSpawnedObject: Represents an object spawned in a synchronized manner.

  • FCavrnusRemoteContent: Describes files uploaded to the Cavrnus server.

  • FCavrnusInputDevice, FCavrnusOutputDevice, FCavrnusVideoInputDevice: Represent audio and video devices for real-time communication.

Cavrnus Functions

Detailed descriptions of the primary public functions available in the Cavrnus API:

  • Authentication: Manage user logins and permissions.

  • Space Functions: Interact with Cavrnus spaces, including joining, exiting, and fetching information.

  • Property Functions: Synchronize and manipulate various property types (color, bool, float, string, vector, transform) in real-time.

  • Permissions: Control access and actions within spaces.

  • Spawned Objects: Create, manage, and destroy objects in the collaborative environment.

  • Remote Content: Upload, download, and access files stored on the Cavrnus server.

  • Space Users: Retrieve information about users within a space and track their presence.

  • Voice and Video: Manage audio and video streams for real-time communication.

Cavrnus Headers

In addition, you’ll find general descriptions of the various public headers in the Cavrnus source files, organized by functional groups:

  • Public Core: Defines the core structure and functionality of the Cavrnus Spatial Connector plugin for Unreal Engine.

  • Live Property Updates: Define classes designed to handle real-time updates of different property types within the Cavrnus collaborative environment.

  • Value Syncs: Form a structured system for synchronizing property values between Unreal Engine and the Cavrnus platform.

  • Types: Essential data structures used throughout the Cavrnus Spatial Connector plugin.

  • Flag Components: Components that play a role in identifying and tracking entities for collaboration (users, avatars, spawned objects).

  • UI: Define the core functionality of the user interface (UI) elements for a Cavrnus Space, including Pagination and Space Lists.

Important Notes

  • Work in Progress: This API reference is a work in progress. While we strive for accuracy, some information might be incomplete or outdated.

  • Reference the Code: For the most up-to-date and complete understanding of the API's functionality, please refer to the latest source code.

  • Community Support: If you have any questions or need assistance, don't hesitate to reach out to our community forums.

Cavrnus Types

FCavrnusSpaceConnection

This is the most important object in Cavrnus. It represents a user’s connection to a Space. As such it is used to access Properties, hook Users, etc.

FCavrnusAuthentication

This contains the Token received from the server upon a successful login. You can only ever have one active login at a time. At the moment, outside of just existing, this class doesn’t really “do” anything.

FCavrnusSpaceInfo

This is the live info about a given Space. It can be used to create a Spaces List, like the one provided in Cavrnus by default.

FCavrnusUser

This represents an individual user, and can be used to fetch their properties at runtime.

FCavrnusLiveXPropertyUpdate

This is used to post Transient Updates.

FCavrnusSpawnedObject

This represents an object that was spawned in a synchronized way at runtime using Cavrnus. It is used to manage that objects properties and, if desired, to delete it.

FCavrnusRemoteContent

Represents a file that has been uploaded to the Cavrnus Servers.

FCavrnusInputDevice

This represents a microphone, and can be used to create a Audio/Video selector, like the one provided in Cavrnus by default.

FCavrnusOutputDevice

This represents the speakers the app’s voice and video play out of. NOTE: This only affects the Cavrnus voice chat, not your application’s other sounds.

FCavrnusVideoInputDevice

This represents a Video Source (both Cameras and Desktop Streams), and can be used to create a Audio/Video selector, like the one provided in Cavrnus by default.

Functions

Authentication

AuthenticateWithPassword

Gets user credentials, allowing you to join valid spaces and make other requests

AuthenticateAsGuest

Creates a guest user account with a given name and joins as that user

IsLoggedIn

Checks if you are logged in

AwaitAuthentication

Throws an even when user authentication is complete

Space Functions

FetchJoinableSpaces

Gets a list of all current spaces which can be joined

BindJoinableSpaces

Triggers when spaces become available to you that you can join, or when their metadata changes

IsConnectedToAnySpace

Checks if there is any active connection to a space

JoinSpace

Connects to a Space; joining voice & video and recieving/processing the journal

AwaitAnySpaceBeginLoading

Triggers when you begin attempting to join a space, returning the ID of the space being joined

AwaitAnySpaceConnection

Triggers immediately if you are already in a space, otherwise triggers as soon as you connect

ExitSpace

Disconnects you from a given space.  You will stop recieving property updates, and lose user & voice connections

Property Functions

Booleans

DefineBoolPropertyDefaultValue

Defines what the application will show if a new prop value has not been assigned

GetBoolPropertyValue

Gets the current property value, whether the default or the one currently set

BindBooleanPropertyValue

Triggers an Event when the property changes, plus an inital event when first bound

BeginTransientBoolPropertyUpdate

Begins a temporary property update. This can be updated with UpdateWithNewData() This will show for everyone in the space, but will not be saved unless you call Finish().

PostBoolPropertyUpdate

Updates the property value at the given path and synchronizes the data to the server

Floats

DefineFloatPropertyDefaultValue

Defines what the application will show if a new prop value has not been assigned

GetFloatPropertyValue

Gets the current property value, whether the default or the one currently set

BindFloatPropertyValue

Triggers an Event when the property changes, plus an inital event when first bound

BeginTransientFloatPropertyUpdate

Begins a temporary property update. This can be updated with UpdateWithNewData() This will show for everyone in the space, but will not be saved unless you call Finish().

PostFloatPropertyUpdate

Updates the property value at the given path and synchronizes the data to the server

Strings

DefineStringPropertyDefaultValue

Defines what the application will show if a new prop value has not been assigned

GetStringPropertyValue

Gets the current property value, whether the default or the one currently set

BindStringPropertyValue

Triggers an Event when the property changes, plus an inital event when first bound

BeginTransientStringPropertyUpdate

Begins a temporary property update. This can be updated with UpdateWithNewData() This will show for everyone in the space, but will not be saved unless you call Finish().

PostStringPropertyUpdate

Updates the property value at the given path and synchronizes the data to the server

Vectors

DefineVectorPropertyDefaultValue

Defines what the application will show if a new prop value has not been assigned

GetVectorPropertyValue

Gets the current property value, whether the default or the one currently set

BindVectorPropertyValue

Triggers an Event when the property changes, plus an inital event when first bound

BeginTransientVectorPropertyUpdate

Begins a temporary property update. This can be updated with UpdateWithNewData() This will show for everyone in the space, but will not be saved unless you call Finish().

PostVectorPropertyUpdate

Updates the property value at the given path and synchronizes the data to the server

Transforms

DefineTransformPropertyDefaultValue

Defines what the application will show if a new prop value has not been assigned

GetTransformPropertyValue

Gets the current property value, whether the default or the one currently set

BindTransformPropertyValue

Triggers an Event when the property changes, plus an inital event when first bound

BeginTransientTransformPropertyUpdate

Begins a temporary property update. This can be updated with UpdateWithNewData() This will show for everyone in the space, but will not be saved unless you call Finish().

PostTransformPropertyUpdate

Updates the property value at the given path and synchronizes the data to the server

Color

DefineColorPropertyDefaultValue

Defines what the application will show if a new prop value has not been assigned

GetColorPropertyValue

Gets the current property value, whether the default or the one currently set

BindColorPropertyValue

Triggers an Event when the property changes, plus an inital event when first bound

BeginTransientColorPropertyUpdate

Begins a temporary property update. This can be updated with UpdateWithNewData() This will show for everyone in the space, but will not be saved unless you call Finish().

PostColorPropertyUpdate

Updates the property value at the given path and synchronizes the data to the server

Permissions

BindGlobalPolicy

Binds an event to throw when a policy is/isn't allowed for the user (returns false until policies are fetched & resolved)

BindSpacePolicy

Binds an event to throw when a policy is/isn't allowed for the user in a given space (returns false until policies are fetched & resolved)

Spawned Objects

SpawnObject

Instantiates the given object with no set properties (note you will need to pull the Container ID out of the Spawned Object and assign property values to it).

DestroyObject

Destroys the given object.

Remote Content

UploadContent

Uploads a file from your disk to the Cavrnus Server

UploadContentWithTags

Uploads a file from your disk to the Cavrnus Server with additional metadata

FetchAllUploadedContent

Fetches a list of available files on your Domain that you can download.

FetchFileById

Fetches a file from the Cavrnus Server and gives you a list of bytes

FetchFileByIdToDisk

Fetches a file from the Cavrnus Server and saves it as a file on disk

Space Users

AwaitLocalUser

Throws an event when the local CavrnusUser arrives in the space

GetCurrentSpaceUsers

Gives the list of current users in a space

BindSpaceUsers

Triggers whenever users join or leave a given space

BindUserVideoFrames

Throws an event with the user's current stream image

Voice and Video

SetLocalUserMutedState

Set my muted state

SetLocalUserStreamingState

Set my streaming state

FetchAudioInputs

Gets available microphones

UpdateAudioInput

Sets which microphone to use

FetchAudioOutputs

Gets available speakers

UpdateAudioOutput

Sets which speaker to use

FetchVideoInputs

Gets available camera/stream sources

UpdateVideoInput

Sets which camera/stream source to use

Public Headers

The header files & folders in the Source/Public folder define the structure and functionality of the Cavrnus Spatial Connector plugin for Unreal Engine

Core Headers

The core functionality of the Cavrnus Spatial Connector, including the definition of the CavrnusSpatialConnector actor that can be placed in a level to immediately connect your Unreal project to the metaverse.

LivePropertyUpdates

The header files in the LivePropertyUpdates folder define a set of classes designed to handle real-time updates of different property types within the Cavrnus collaborative environment. These classes share a common base class, UCavrnusLivePropertyUpdate, and provide specialized functionality for specific data types.

ValueSyncs

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.

Types

The header files in the "Types" folder define essential data structures used throughout the Cavrnus Spatial Connector plugin.

FlagComponents

The header files in the FlagComponents folder relate to flagging or marking entities within the Cavrnus system (users, avatars, spawned objects). These components play a role in identifying and tracking these entities for collaboration.

UI

The header files in the "UI" folder define the core structure and functionality of the user interface (UI) elements for the Cavrnus Spatial Connector plugin. They enable users to log in, select spaces, view other users, and potentially perform other essential actions within the collaborative environment.

Pagination

The header files in the "Pagination" folder define the UI structure and interface for handling pagination of list elements within the Cavrnus Spatial Connector plugin.

SpaceList

The header files in the "UI/SpaceList" folder define the UI elements and logic for displaying and interacting with a list of Cavrnus spaces.