Cloud Variables

From Neos Wiki
Revision as of 02:02, 20 September 2021 by ProbablePrime (talk | contribs)
Jump to navigation Jump to search
Other languages:
English • ‎čeština • ‎日本語 • ‎한국어

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: owner, name, type, permissions, and default value.
  • Values - Actual values per user.

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 (Default value would be an output of the To String node. An example would be Color, which through to string results in: [1; 1.23; 0; 1])

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

Default Values

When creating a definition, you supply data and configuration in a series of stages with each command. Just in case you forget or omit a command here are the default values for various properties of a definition:

  • Read and Write permissions will default to variable_owner
  • List permissions will default to definition_owner
  • If no default value is specified, Neos will return the default value for this data type as defined in C#.

Cloud Variable Values

Each Cloud Variable Definition can have multiple values, each value is tied to an individual Neos User or group. A value just contains its value and has no details about the definition. You can think of it like a table with two columns an Owner 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
Variable Owner ID Value
U-Frooxius Strawberry
U-Nexulan Orange
U-Shifty Pineapple
U-ProbablePrime Blueberry
U-Vegasx Blueberry
G-MyGroup Banana

The last row shows a value that is specific for a Group. This is only possible for Cloud Variables that belong to a Group.

Variable Owner IDs (User IDs or Group IDs) with spaces need to be written with a hyphen. Example: Group "My Group" becomes "G-My-Group". Always double check your User ID and Group IDs they can be completely different from a User's/Group's displayed name.

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.
  • Variable Definitions are heavily cached and will typically take several minutes to update. It's recommended to set them up fully in advance.
  • Reads & writes are buffered, batched and cached and will take a bit to propagate.
  • A current limitation of the cloud variable system is that they won’t be synchronized in real time across different sessions, unless they run on the same host/user. If you host multiple worlds/sessions on a single headless (or your own computer), the changes to the cloud variable will sync in real time within those sessions.
  • If different users host the same world, changes in one world won’t be immediately reflected in another and will take a few minutes to refresh. The current plan is to add full real time synchronization in such cases by integrating SignalR into our cloud infrastructure, which will help the cloud scale better for other things like active sessions or the messaging system as well, but is a bigger chunk of work.
  • Current limits, permissions, and other aspects are subject to change.
  • Changing data types is possible, however already stored values are not affected.

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

¹This applies only to the owner of the definition and not the user of a variable. As such you can own any amount of values.

Example: If NeosUser1 owns the definiton "User.Color". This reduces it to 255 free definitions for that user. But anyone else can freely use the variable if the permissions are set up to allow them to do so.

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>
    • By default, strings have a length of 256 characters. This can be increased to 8192 characters if you use the string:<max_length> syntax to enter longer limits.
  • float
    • float2
    • float3
    • float4
    • float2x2
    • float3x3
    • float4x4
  • floatQ - use floatq for definition
  • doubleQ - use doubleq for definition
  • 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:

  • Action Permission - The type of action that a Permission Group can carry out.
  • Group/Type Permission - A group or classification of user.

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

Action Permission

Action Permission 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 /setUserVarPerms test.color read,write,list anyone would grant read,write and list permissions to the test.color variable.

Group/Type Permission

Common Definition Permissions

These permissions, can be used with both User and Group owned definitions.

Permission Type Description Locations Limitations
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. Everywhere. - Cannot be used with 'list' permissions.
- Cannot be used with write permissions on User owned definitions.
definition_owner_only Only the User/Group who defined the variable can read/write/list their own singular value. Useful for announcement/version control systems. Userspace/safe contexts only. None.
definition_owner_only_unsafe Only the User/Group who defined the variable can read/write/list their own singular value. Useful for announcement/version control systems. Everywhere. None.
variable_owner Only the user who owns the variable value can write/read it. Userspace/safe contexts only. Cannot be used for 'list' permissions.
variable_owner_unsafe Only the user who owns the variable value can write/read it. Everywhere. Cannot be used for 'list' permissions.

User Definition Permissions

These permissions, can only be used with User owned definitions.

Permission Type Description Locations Limitations
definition_owner_only_contacts The variable value can be written to only by the definition owner for any user who is an accepted contact of the definition owner. Useful for User tagging systems. Userspace/safe contexts only. Cannot be used with 'list' permissions
definition_owner_only_contacts_unsafe The variable value can be written to only by the definition owner for any user who is an accepted contact of the definition owner. Useful for User tagging systems. Everywhere. Cannot be used with 'list' permissions
variable_owner_only_contacts This allows anyone who is a contact of given value owner to read/write given value (meaning your contacts can read/write your value). Userspace/safe contexts only. Cannot be used for 'list' permissions.
variable_owner_only_contacts_unsafe This allows anyone who is a contact of given value owner to read/write given value (meaning your contacts can read/write your value). Everywhere Cannot be used for 'list' permissions

Group Definition Permissions

These permissions, can only be used with Group owned definitions.

Permission Type Description Locations Limitations
definition_owner Only the group who defined the variable can read/write/list it. Userspace/safe contexts only.
definition_owner_unsafe Only the group who defined the variable can read/write/list it. Everywhere.

Safe Contexts

In most cases within Neos, anyone can observe or even manipulate what you're doing. These are unsafe contexts. When in places such as Userspace,where the Neos Dash is located, no one can see or modify what you're doing. This is a safe context.

List of Commands for Cloud Variables

Most of the commands below use a similar format:

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

When reviewing these commands if you see () round an argument then it is optional. Otherwise it is required.

Creating Definitions

User Definitions

  • /createUserVar <path> - Creates a variable definition with the given path.
  • /setUserVarType <path> <type> - Sets the variable definiton's Data type.
  • /setUserVarDefaultValue <path> <value> - Sets the default value for a definition.
  • /setUserVarPerms <path> <action permission> <permission type> - Sets the Permissions 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's Data type.
  • /setGroupVarDefaultValue <group> <path> <value> - Sets the default value for a definition.
  • /setGroupVarPerms <group> <path> <action permission> <permission type> - Sets the Permissions 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

For reading values using LogiX / Components see this later section.

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 variable definitions of a user (default: yours). Requires list permission.

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 variable definitions of a group. Requires list permission.

Writing Values

When setting/writing a value, ensure that your permissions are set correctly.

For writing values using LogiX / Components see this later section.

Writing Values with User owned Definitions

  • /setUserVarValue (<user>) <path> (<target user>) <value> - Sets an individual user's value for a definition.

Writing Values with Group owned Definitions

  • /setGroupVarValue <group> <path> (<target user>) <value> - Sets an individual user's value for a definition.

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.

Headless Sessions and Auto-Startup World Options

Cloud variables can be used with headless sessions and Auto-Start-up Worlds in a number of ways:

  • Configuring roles in a session.
  • Allowing/Denying users from joining/accessing sessions.
  • Provide custom denial messages for why a user is denied access to your sessions.

These options are NOT available in the UI within Neos and require advanced setup from outside of the game.

Roles

To configure roles using cloud variables, add a roleCloudVariable parameter to your world start-up/headless session configuration. It's value should be the full path of the cloud variable you want to use. The session will then use the Cloud Variable to determine which role the user has.

When doing this you need to keep in mind a few things:

  1. The variable data type must be a string.
  2. It is strongly recommended that you use the definition_owner permission group for this variable. Other permission groups may allow users to override their roles.
  3. If no value is set for the variable and a user, the other methods for determining the role will be used.

An example setup would be:

U-ProbablePrime.awesomeHeadless.userRoles
Variable Owner ID Value
U-Frooxius Admin
U-Nexulan Builder
U-Shifty Guest
U-ProbablePrime Spectator
U-Vegasx Spectator

Access

There are a few variables and settings which can control access to headless sessions.

Allowing User's Access

To configure access to a headless session, using cloud variables add a allowUserCloudVariable parameter to your world start-up/headless session configuration. It's value should be the full path of the cloud variable you want to use. The session will then use the Cloud Variable to provide access to the session.

This option take precedence over all other checks, including regular session settings such as Max Users and Visibility.

When doing this you need to keep in mind a few things:

  1. The variable data type must be a bool.
    1. If it is set to true, the user will be allowed to join the session.
    2. If it is set to false, or a value is not present, the other methods for determining access will be used.
  2. If its value is true, the server will allow access to the user.
  3. This is the equivalent of sending an invite to the user.
  4. Users can join regardless of the MaxUsers setting.
  5. Users can join even if the session is private. They will need a link to the session though.

An example setup would be:

U-ProbablePrime.awesomeHeadless.userAccess
Variable Owner ID Value
U-Frooxius true
U-Nexulan true
U-BadGuy false

Denying User's Access

In a similar manner to allowUserCloudVariable, you can use denyUserCloudVariable to deny a user access to your world start-up/headless session configuration. Follow the guide above for allowing access but use denyUserCloudVariable instead. When a value for a user is true, they will be denied access.

This option take precedence over all other checks, including regular session settings such as Max Users and Visibility.

An example setup would be:

U-ProbablePrime.awesomeHeadless.userAccess
Variable Owner ID Value Description
U-Frooxius false Allowed Access
U-Nexulan false Allowed Access
U-BadGuy true Denied Access

Joining Control

In addition to the above options, you also have the option to use requiredUserJoinCloudVariable. When this option is added to your world start-up/headless session configuration, its value for a user will be checked. If it is true then the user will be allowed to join. If it is false then they will not be allowed to join.

Do note that this option does NOT take precedence over other session checks. Even if this value is set to true, if the session is full(At its maximum user count) the user will not be allowed in.

An example setup would be:

U-ProbablePrime.awesomeHeadless.userAccess
Variable Owner ID Value
U-Frooxius true
U-Nexulan true
U-BadGuy false

You can also use a second variable requiredUserJoinCloudVariableDenyMessage to specify a custom deny message for each user:

U-ProbablePrime.awesomeHeadless.denyMessages
Variable Owner ID Value
U-Frooxius Get Some Rest
U-BadGuy You are banned because you're bad

This option may be confusing at first but it is useful for controlling session access, without bypassing regular checks such as visibility and Max User Counts.

Additional Reading

For additional reading, please check the following sources:


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