Cloud Variables

What are Cloud Variables?

Cloud Variables are variables that persist across worlds. They work in a similar nature to Dynamic Variables but instead of relying on parenting or the world hierarchy, they instead rely on paths and users/group ownership. You can think of them in a similar way to a settings or configuration file for your favorite game. Cloud Variables are more lively than this though as they are synced between sessions, worlds and even your Neos Dash.

Cloud Variables are comprised of two parts:

• Definitions - Settings and configuration.
• Values - Actual Values

Cloud Variable Definition

A cloud variable definition is made up of 4 Parts:

• A path/name E.g. AwesomeGadget.Version or PartyWorld.highQualityLights
• Data type
• Permissions
• A Default value

Definitions can also be registered against a User or a Group. Registering a definition against a Group has some benefits such as:

• Higher Limits
• Additional Permission Capabilities

Cloud Variable Values

Each Cloud Variable Definition can have multiple values, each value is tied to an individual Neos User. It just contains its value. You can think of it like a table with two columns a User ID and the Value.

For example if a Cloud Variable Definition was created with a data type of string and a name of "Favourite Fruit" then you can imagine it's values looking like this:

Favorite Fruit
User ID	Value
U-Frooxius	Strawberry
U-Nexulan	Orange
U-Shifty	Pineapple
U-ProbablePrime	Blueberry
U-Vegasx	Blueberry

Using Cloud Variables

Before using Cloud Variables they must be created and registered. This is done by sending commands of various types to Neos Bot. These commands create and register a #Cloud Variable Definition with Neos. Once registered Cloud Variable Values can be read, written and manipulated against this definition using LogiX & Components.

Usage Notes / Warnings

• Cloud Variables cannot currently be deleted.
• Reads & writes are buffered, batched and cached and will take a bit to propagate.
  • All active instances within Neos are synced in real-time
• Variable Definitions are heavily cached and will typically take several minutes to update. It's recommended to set them up fully in advance.
• Current limits, permissions, and other aspects are subject to change.

Limits

Cloud variables do not take up any storage, but they do have limits. These limits apply only to the definitions of the variables and not their actual values. Depending on the configuration different users could have different values. E.g. For a color variable: Sam has Red, Sally has Black, Tom has Blue.

Limit Type	Limit
Users	256
Groups	8192

Supported Datatypes

When creating Cloud Variable Definitions a valid type for them needs to be specified. The supported data types are listed below but generically any primitive data type is supported. Reference data types are not supported as references only work within one defined world/session.

• bool
  • bool2
  • bool3
  • bool4
• string
  • string:<max_length>
• float
  • float2
  • float3
  • float4
  • float2x2
  • float3x3
  • float4x4
• floatQ
• doubleQ
• color
• datetime
• timespan
• short
  • ushort
• int
  • int2
  • int3
  • int4
• uint
  • uint2
  • uint3
  • uint4
• long
  • long2
  • long3
  • long4
• ulong
  • ulong2
  • ulong3
  • ulong4
• byte
  • sbyte
• double
  • double2
  • double3
  • double4
  • double2x2
  • double3x3
  • double4x4
• decimal

Enums

You can now also use Enum types, the cloud variable definition must be set to string to sync properly. Once created you can use LogiX & Components with their DataTypes set to the Enum you wish to use. For example CloudValueField<ShadowType>.

More datatypes may be supported in the future.

Permissions

Cloud variable permissions are composed of two parts:

• Access Permissions - The actual permissions given to the Permission Type / Group.
• Permission Group/Type - A group or classification of user who is given the second part.

As an example in the following command: /setUserVarPerm test.color read,write,list anyone. The permissions are "read, write and list" and the permission type/group is "anyone".

Access Permissions

Permission Type	Description
read	Grants the ability to read values of a cloud variable.
write	Grants the ability to write values of a cloud variable.
list	Grants the ability to list all values or a variable.
all	Grants all above permissions at once.

You can also specify multiple permissions at once, separated by a comma so for example /setUserVarPerm test.color read,write,list anyone would grant read,write and list permissions to the test.color variable.

Permission Types/Groups

Permission Type	Description	Notes / Limitations
definition_owner	Only the group who defined the variable can read/write/list it.	This permission group cannot be used with User owned definitions. This permission group only works within Userspace/safe contexts.
definition_owner_unsafe	Only the group who defined the variable can read/write/list it.	This permission group cannot be used with User owned definitions. This permission group works everywhere.
variable_owner	Only the user who owners the variable value can write/read it.	This permission group only works within Userspace/safe contexts.
variable_owner_unsafe	Only the user who owners the variable value can write/read it.	This permission group works everywhere.
Anyone	Anyone can read/write/list this variable. This is recommend for reading public variables but not recommend for writes as anyone can change anyone's value.	This permission group works everywhere and cannot be used with User owned definitions.

List of Commands for Cloud Variables

Most of the commands below use a similar format:

• First part is one of /get, /set, /list or /create for actions.
• Then specify whether the variable definition belongs to User or Group.
• Then Var.
• And then add the final part which is unique to each command's purpose. (<blank>, Type, Value, Perms or DefaultValue).

Creating Definitions

User Definitions

• /createUserVar <path> - Creates a variable definition with the given path.
• /setUserVarType <path> <type> - Sets the variable definiton'sData type.
• /setUserVarDefaultValue <path> <value> - Sets the default value for a definition.
• /setUserVarPerms <path> <perm_types> <permissions> - Sets the Permissions for a definition.
• /setUserVarValue (<user>) <path> <value> - Sets an individual user's value for a definition.

There is also a command which can create a definition in one go: /createUserVar <path> <type> <default value> <read perms> <write perms> <list perms>

Group Definitions

• /createGroupVar <group> <path> - Creates a variable definition with the given path.
• /setGroupVarType <group> <path> <type> - Sets the variable definiton'sData type.
• /setGroupVarDefaultValue <group> <path> <value> - Sets the default value for a definition.
• /setGroupVarPerms <group> <path> <perm_types> <permissions> - Sets the Permissions for a definition.
• /setGroupVarValue <group> <path> <value> (<target user>) <value> - Sets an individual user's value for a definition.

There is also a command which can create a definition in one go: /createGroupVar <group> <path> <type> <default value> <read perms> <write perms> <list perms>

Reading Values

User Values

• /getUserVar <path> - Gets the definition for a variable (type, perms, default value)
• /getUserVarValue (<user>) <path> (<target user>) - Gets a user's (default: yours) value for a definition.
• /listUserVars (<user>) - Lists Values for a defintion

Group Values

• /getGroupVar <group> <path> - Gets the definition for a variable (type, perms, default value)
• /getGroupVarValue <group> <path> (<target user>) - Gets a user's (default: yours) value for a definition.
• /listGroupVars <group> - Lists Values for a defintion

Definition Examples

User Boolean

Create a User variable of type boolean that anyone could read and the owner (each user for their own copy) could write from User and World space:

/createUserVar testing.enabled
/setUserVarType testing.enabled bool
/setUserVarPerms testing.enabled read anyone
/setUserVarPerms testing.enabled write variable_owner_unsafe

User Color

Create a User variable of color type that only the owner could write from Userspace and read from everywhere:

/createUserVar testing.myColor
/setUserVarType testing.myColor color
/setUserVarPerms testing.myColor read variable_owner_unsafe
/setUserVarPerms testing.myColor write variable_owner

Group Boolean

Create a Group variable of boolean type that only the owner could read, write and list from everywhere:

/createGroupVar MyGroup testing.enabled
/setGroupVarType MyGroup testing.enabled bool
/setGroupVarPerms MyGroup testing.enabled read,write,list variable_owner_unsafe

Working with cloud variables

Components

ActiveUserCloudField`1 (Component) - Like CloudValueField, but overrides OwnerId with Local User.

ActiveUserCloudValueVariable`1 (Component) - Like CloudValueVariable, but overrides OwnerId with Local User.

CloudValueField`1 (Component) - Uses target field to store the value, otherwise similar to CloudValueVariable.

CloudValueVariable`1 (Component) - Represents the Cloud Variable, can set OwnerId manually.

CloudValueVariableDriver`1 (Component) - Drives target field with the value of the specified Cloud Variable. Overrides OwnerId with Local User.

LogiX nodes

Write Cloud Variable`1 (LogiX node) - On impulse, writes the specified Cloud Variable for specified owner.

Read Cloud Variable`1 (LogiX node) - On impulse, reads the specified Cloud Variable for specified owner.

Additional Reading

For additional reading, please check the following sources:

• Neos Weekly update - This update introduces the feature and provides usage examples and a lot of additional information.
• Initial Release of Cloud Variables.
• First batch of improvements to Cloud Variables.
• Second batch of improvements to Cloud Variables.
• Information about definition_owner and User Definitions

This article or section is a Stub. You can help the Neos Wiki by expanding it.