Dynamic variables, commonly shorted to dyn vars or dynvars, is a system of data storage wherein one can store arbitrary, scoped data under slot heirarchies with arbitrary names, akin to that of an associative array. Their usage is usually found in large systems with many moving parts, but can nonetheless be useful as easy "global" values that can be changed on an object.
For a quick-start guide on using dynamic variables, the How To Use Dynamic Variables page serves as a straightforward guide.
Usage
Dynamic variables as a whole are managed with two parts: dynamic variable spaces and dynamic variables. The DynamicVariableSpace component defines a dynamic variable space on a slot and its children, while any one of the DynamicValueVariable, DynamicReferenceVariable, DynamicTypeVariable components define a dynamic variable. Dynamic variable spaces and names must not contain symbols, punctuation, or whitespace, except for period (.), underscore (_), and space ( ). To check if a character is unable to be used in a dynamic variable name, one can use the Is Symbol, Is Punctuation, and Is White Space ProtoFlux nodes, taking care of the three exceptions above.
The process of a dynamic variable being associated with a given space is called binding. The VariableName of a dynamic variable component can be one of the following two forms: VariableName or VariableSpaceName/VariableName. The former represents indirect binding, while the latter represents direct binding. A dynamic variable component will traverse up the slot heirarchy, including its current slot, looking for an applicable variable space to bind to. If a dynamic variable is indirectly binding, it will bind to the first dynamic variable space that does not have OnlyDirectBinding set to True. If a dynamic variable is directly binding, it will bind to the first dynamic variable space that matches its name. If a dynamic variable does not find a dynamic variable space that it can bind to, it will not be accessible outside of the component itself, essentially reducing to a glorified ValueField. A dynamic variable will go through this binding process every time any part of the component changes.
Dynamic Fields
It is also possible to interface with an existing IField as if it were a dynamic variable. This is done by attaching a DynamicField component (for IValue types), DynamicReference component (for SyncRef types), or DynamicTypeField component (for the Type type), then dragging the target field into the TargetField field.
Reading and Writing
Dynamic variables can be read in any fashion one sees fit, such as copying from the variable field, sourcing the variable field, or using the Read Dynamic Variable node. Dynamic variables can be written to via the Write Dynamic Variable or Write Or Create Dynamic Variable nodes. Additionally, it is possible to directly drive a field using the value of a dynamic variable by using either the DynamicValueVariableDriver or DynamicReferenceVariableDriver component.
Driving Dynvars
Driving dynamic variables must be done with caution. For one, one must drive the value field of the dynamic variable, which can incur a delay of the value when reading it back. Additionally, if a dynamic variable is being driven, it is crucial that all instances of the same dynamic variable are driven by the same value. Otherwise, clients will fight over which value is the "true" value of the dynamic variable and cause inconsistent behavior.
Best Practices
Even though dynamic variables allow for a wide array of freedom, there are a few practices generally considered to be favorable when working with dynamic variables:
- It is highly recommended to have only one instance of a dynamic variable (dynamic variable component with the same name) at any given time. There aren't any huge problems with having multiple dynamic variable instances if none or all of the instances are being driven, but it allows for cleaner organization of variables.
- Do not write to the value of the dynamic variable by sourcing the field and using a Write node. Always use the ProtoFlux nodes for writing to a dynamic variable. Otherwise, you will need to wait 2+ updates before the variable actually propagates the new value when reading the dynamic variable back. Reading can be done in any fashion and will update instantly upon the variable being written to.
- Using variable names that directly bind allows for a clearer overview of where the variables should be bound. Indirectly binding variable names are more suited for variables that are dynamically created and/or destroyed as part of an object's function.
- Using
OnlyDirectBindingon a DynamicVariableSpace strictly enforces this behavior, which can prevent misbindings and catch errors earlier.
- Using
- DynamicVariableSpaces are not nested. If a system is complex enough, or if a DynamicVariableSpace is being shared by multiple objects, using periods (
.) to pseudo-isolate objects or systems from one another is greatly encouraged.
Default Spaces
As of the time of writing, there are three dynamic spaces that exist by default:
World, which exists under the Root of the world. This space isOnlyDirectBinding.User, which exists under every User's User Root Slot. This space isOnlyDirectBinding.- Useful for systems that affect avatars, as they can rely on a standardized space being available for each user to read and write variables on.
Dash, which exists under the slot containing the UserspaceRadiantDash in userspace.