(9 intermediate revisions by the same user not shown)
Line 1:
Line 1:
'''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 [https://en.wikipedia.org/wiki/Associative_array 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.
<languages></languages>
For a quick-start guide on using dynamic variables, the [[How To Use Dynamic Variables]] page serves as a straightforward guide.
{{Infobox Component
|Image=ValueGradientDriver`1Component.png
|Name=ValueGradientDriver
}}
== Usage ==
<translate>
Dynamic variables as a whole are managed with two parts: ''dynamic variable spaces'' and ''dynamic variables''. The [[Component:DynamicVariableSpace|DynamicVariableSpace]] component defines a dynamic variable space, while any one of the [[Component:DynamicValueVariable|DynamicValueVariable]], [[Component:DynamicReferenceVariable|DynamicReferenceVariable]], [[Component:DynamicTypeVariable|DynamicTypeVariable]] components define a dynamic variable. Dynamic variable spaces and names must not contain symbols, punctuation, or whitespace, <em>except</em> for period (<code>.</code>), underscore (<code>_</code>), and space (<code> </code>). To check if a character is unable to be used in a dynamic variable name, one can use the [[ProtoFlux:Is Symbol|Is Symbol]], [[ProtoFlux:Is Punctuation|Is Punctuation]], and [[ProtoFlux:Is White Space|Is White Space]] ProtoFlux nodes, taking care of the three exceptions above.
<!--T:1-->
The '''ValueGradientDriver''' component changes the value of the field defined in <code>Target</code> based on the items in the <code>Points</code> list and their <code>Position</code> in relation to the <code>Progress</code> value.
</translate>
The process of a dynamic variable being associated with a given space is called ''binding''. The <code>VariableName</code> of a dynamic variable component can be one of the following two forms: <code>VariableName</code> or <code>VariableSpaceName/VariableName</code>. 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 <code>OnlyDirectBinding</code> set to <code>True</code>. 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 [[Component:ValueField|ValueField]]. A dynamic variable will go through this binding process every time any part of the component changes.
== <translate><!--T:2--> Fields</translate> ==
{{Note|Currently, there exist a few instances where created variables do not instantly bind/rebind to a dynamic variable space, requiring a [[ProtoFlux:Delay Updates|Delay Updates]] of 2+ updates. These include [https://github.com/Yellow-Dog-Man/Resonite-Issues/issues/1394 creating new dynamic reference variables], [https://github.com/Yellow-Dog-Man/Resonite-Issues/issues/2717 deleting dynamic variables], changing the name of a dynamic variable or dynamic variable space, and any instance where there is a dynamic variable space change without a component update, such as [https://github.com/Yellow-Dog-Man/Resonite-Issues/issues/1690 duplicating slots containing a dynamic variable space] or reparenting a slot containing a dynamic variable under a new dynamic variable space. If you find your dynamic variables to be behaving weirdly, try adding a delay of 2 or more updates between such operations.|warning}}
{{Table ComponentFields
|Progress|Float|<translate><!--T:3--> Controls which items from the <code>Points</code> list will be used to drive the value of <code>Target</code></translate>
|Target|{{RootFieldType|FieldDrive`1|T}}|TypeAdv1=true|<translate><!--T:4--> The field that this component will drive the value of</translate>
|Interpolate|Bool|<translate><!--T:5--> Controls whether or not this component will interpolate (or blend) between the nearest two <code>Points</code> to the current <code>Progress</code> value.</translate>
|Points|{{RootFieldType|SyncList`1|[[#Point|Point]]<T>}}|TypeAdv3=true|<translate><!--T:6--> A list of items indicating their <code>Position</code> (in relation to <code>Progress</code>), and a <code>Value</code></translate>
}}
=== Dynamic Fields ===
== <translate><!--T:7--> Usage</translate> ==
It is also possible to interface with an existing [[Type:IField|IField]] as if it were a dynamic variable. This is done by attaching a [[Component:DynamicField|DynamicField]] component (for [[Type:IValue`1|IValue]] types), [[Component:DynamicReference|DynamicReference]] component (for [[Type:SyncRef`1|SyncRef]] types), or [[Component:DynamicTypeField|DynamicTypeField]] component (for the [[Type:Type|Type]] type), then dragging the target field into the <code>TargetField</code> field.
=== Reading and Writing ===
<translate>
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 [[ProtoFlux:Read Dynamic Variable|Read Dynamic Variable]] node. Dynamic variables can be written to via the [[ProtoFlux:Write Dynamic Variable|Write Dynamic Variable]] or [[ProtoFlux:Write Or Create Dynamic Variable|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 [[Component:DynamicValueVariableDriver|DynamicValueVariableDriver]] or [[Component:DynamicReferenceVariableDriver|DynamicReferenceVariableDriver]] component.
<!--T:8-->
Each point in the <code>Points</code> list has a <code>Position</code> field and <code>Value</code> field. The <code>Position</code> field is used for comparison with the component's <code>Progress</code> field, while the <code>Value</code> field is the value used for driving the field in <code>Target</code>.
==== Driving Dynvars ====
<!--T:9-->
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 <em>crucial</em> that <em>all</em> 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.
When <code>Interpolate</code> is checked, the value stored in <code>Target</code> is linearly interpolated between the <code>Value</code>s of the two points surrounding the current <code>Progress</code>. When unchecked, the output value is simply set to the <code>Value</code> of the closest point before the current <code>Progress</code>. The only exception to this is when no point exists before the current <code>Progress</code>, in which case the first point after the current <code>Progress</code> is used.
== Best Practices ==
<!--T:10-->
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:
If two points have the same <code>Position</code>, then the point of greatest index takes priority if the value is not interpolated or if the positions are exactly equal to the current <code>Progress</code>. ''During'' interpolation, however, the point of ''least'' index takes priority.
</translate>
* 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.
== <translate><!--T:11--> Examples</translate> ==
* Do <em>not</em> write to the value of the dynamic variable by sourcing the field and using a [[ProtoFlux:Write|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 <code>OnlyDirectBinding</code> on a DynamicVariableSpace strictly enforces this behavior, which can prevent misbindings and catch errors earlier.
* DynamicVariableSpaces are not nested. If a system is complex enough, or if a DynamicVariableSpace is being shared by multiple objects, using periods (<code>.</code>) to pseudo-isolate objects or systems from one another is greatly encouraged.
== Default Spaces ==
<gallery widths=560px heights=480px>
As of the time of writing, there are three dynamic spaces that exist by default:
File:component_example_ValueGradientDriver.webm|alt=<translate><!--T:12--> A ValueGradientDriver is set up with five float values. Index 0 has position 0.00 and value 0, index 1 has position 0.77 and value 2, index 2 has position 0.25 and value 4, index 3 has position 0.67 and value 6, and index 4 has position 1.00 and value 8. As progress moves from 0 to 1, the target field is linearly interpolated between the values of indices 0, 2, 3, 1, then 4. Once interpolation is unchecked, the target field is merely set to the previous index value.</translate>|<translate><!--T:13--> General usage of the component, showing interpolation and non-interpolation between five float values.</translate>
File:Component_example_ValueGradientDriver_IndexOfMax.webp|alt=<translate><!--T:14--> A ValueGradientDriver is set up with five int values. The progress is fixed at 1 and each point's value is set to its index. Interpolation is disabled. The index of the point with the greatest position is output.</translate>|<translate><!--T:15--> An unorthodox yet valid usage of the component, as way to find the index of the maximum value in a list of floats (as the <code>Position</code> values) without the need for ProtoFlux. <code>Progress</code> may be set to 0 to find the index of the minimum value as well.</translate>
</gallery>
* <code>World</code>, which exists under the [[Root]] of the world. This space is <code>OnlyDirectBinding</code>.
== <translate><!--T:16--> See Also</translate> ==
** Useful for things that should globally affect the world or broadcast information throughout the world. Example items that use this space include [[BeatLink]] and the [[Redprint]] manager.
* <code>User</code>, which exists under every [[User]]'s [[ProtoFlux:Get User Root Slot|User Root Slot]]. This space is <code>OnlyDirectBinding</code>.
** 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.
* <code>Dash</code>, which exists under the slot containing the [[Component:UserspaceRadiantDash|UserspaceRadiantDash]] in userspace.
ValueGradientDriver component as seen in the Scene Inspector
The ValueGradientDriver component changes the value of the field defined in Target based on the items in the Points list and their Position in relation to the Progress value.
A list of items indicating their Position (in relation to Progress), and a Value
Usage
Each point in the Points list has a Position field and Value field. The Position field is used for comparison with the component's Progress field, while the Value field is the value used for driving the field in Target.
When Interpolate is checked, the value stored in Target is linearly interpolated between the Values of the two points surrounding the current Progress. When unchecked, the output value is simply set to the Value of the closest point before the current Progress. The only exception to this is when no point exists before the current Progress, in which case the first point after the current Progress is used.
If two points have the same Position, then the point of greatest index takes priority if the value is not interpolated or if the positions are exactly equal to the current Progress. During interpolation, however, the point of least index takes priority.
Examples
General usage of the component, showing interpolation and non-interpolation between five float values.
An unorthodox yet valid usage of the component, as way to find the index of the maximum value in a list of floats (as the Position values) without the need for ProtoFlux. Progress may be set to 0 to find the index of the minimum value as well.
An unorthodox yet valid usage of the component, as way to find the index of the maximum value in a list of floats (as the