Dynamic Variables: Difference between revisions

From Resonite Wiki
Zandario (talk | contribs)
m LogiX -> ProtoFlux
 
cleanup + redo headings
Line 1: Line 1:
{{stub}}
{{stub}}
= Overview = <!--T:1-->
== Overview ==


<!--T:2-->
'''Dynamic variables''' allow you to read and write data by name. This makes it easy to manage data in large systems; every bit of data is clearly labeled, and you can break data into multiple '''spaces''' to keep your systems separate.=
'''Dynamic variables''' allow you to read and write data by name. This makes it easy to manage data in large systems; every bit of data is clearly labeled, and you can break data into multiple '''spaces''' to keep your systems separate.=


= Naming Restrictions = <!--T:17-->
== Naming Restrictions ==
When using Dynamic Variables there are some restrictions and limitations on naming both spaces and variables within those spaces.
When using Dynamic Variables there are some restrictions and limitations on naming both spaces and variables within those spaces.


<!--T:18-->
Space and Variable Names '''cannot contain''':
Space and Variable Names '''cannot contain''':
* Any symbols  
* Any symbols  
Line 16: Line 14:
* '''Except''' for period (.), underscore (_) and space ( ).
* '''Except''' for period (.), underscore (_) and space ( ).


= Usage = <!--T:3-->
== Usage ==


<!--T:4-->
Optionally, the name can be prefixed by the name of a '''space''', terminated by a /, to choose a specific variable space to use. This is useful to distinguish between unrelated systems that all use dynamic variables.
Optionally, the name can be prefixed by the name of a '''space''', terminated by a /, to choose a specific variable space to use. This is useful to distinguish between unrelated systems that all use dynamic variables.


<!--T:5-->
Some valid names include:
Some valid names include:


<!--T:6-->
* Health -- no space defined, named Health
* Health -- no space defined, named Health
* World/Color -- named Color, in the World space
* World/Color -- named Color, in the World space
* MyCoolSystem/Score -- named Score, in the MyCoolSystem space
* MyCoolSystem/Score -- named Score, in the MyCoolSystem space


== Spaces == <!--T:7-->
=== Spaces ===


<!--T:8-->
Dynamic variables can live anywhere in or under the slot containing a [[DynamicVariableSpace (Component)|DynamicVariableSpace]] component.
Dynamic variables can live anywhere in or under the slot containing a [[DynamicVariableSpace (Component)|DynamicVariableSpace]] component.


<!--T:9-->
So, a variable space on the world root can be used from anywhere, whilst a variable space on your avatar can be used from anything stored in your avatar.
So, a variable space on the world root can be used from anywhere, whilst a variable space on your avatar can be used from anything stored in your avatar.


== Variables == <!--T:10-->
=== Variables ===


<!--T:11-->
The simplest way to use dynamic variables is to use the [[DynamicValueVariable%601_(Component)|DynamicValueVariable<T>]] and [[DynamicReferenceVariable%601_(Component)|DynamicReferenceVariable<T>]] components. These are for value (int, float, String, etc.) and reference (Slot, User, etc.) types, respectively.
The simplest way to use dynamic variables is to use the [[DynamicValueVariable%601_(Component)|DynamicValueVariable<T>]] and [[DynamicReferenceVariable%601_(Component)|DynamicReferenceVariable<T>]] components. These are for value (int, float, String, etc.) and reference (Slot, User, etc.) types, respectively.
   
   
These components store a value or reference directly. If two variable components have the same name, then they will have identical contents.
These components store a value or reference directly. If two variable components have the same name, then they will have identical contents.


== Fields == <!--T:12-->
=== Fields ===


<!--T:13-->
If you want to use an existing field or reference as the contents of a dynamic variable, you can use the [[DynamicField%601_(Component)|DynamicField<T>]] or [[DynamicReference%601_(Component)|DynamicReference<T>]] components. Instead of storing something directly, they point at a field that contains a value or reference type, respectively.
If you want to use an existing field or reference as the contents of a dynamic variable, you can use the [[DynamicField%601_(Component)|DynamicField<T>]] or [[DynamicReference%601_(Component)|DynamicReference<T>]] components. Instead of storing something directly, they point at a field that contains a value or reference type, respectively.


<!--T:14-->
(TODO: clarify value vs. reference types; I think this isn't fully correct)
(TODO: clarify value vs. reference types; I think this isn't fully correct)


== Drivers == <!--T:15-->
=== Drivers ===


<!--T:16-->
You can use the contents of a dynamic variable to drive a field or reference, using the [[DynamicValueVariableDriver%601_(Component)|DynamicValueVariableDriver<T>]] and [[DynamicReferenceVariableDriver%601_(Component)|DynamicReferenceVariableDriver<T>]] components.
You can use the contents of a dynamic variable to drive a field or reference, using the [[DynamicValueVariableDriver%601_(Component)|DynamicValueVariableDriver<T>]] and [[DynamicReferenceVariableDriver%601_(Component)|DynamicReferenceVariableDriver<T>]] components.


== Unlisted types == <!--T:21-->
=== Unlisted types ===


<!--T:22-->
When creating a dynamic variable component, you will be given a list of "common types". If the type you seek is not in that list, you will have to enter it by hand. See [[Complex Types in Components]].
When creating a dynamic variable component, you will be given a list of "common types". If the type you seek is not in that list, you will have to enter it by hand. See [[Complex Types in Components]].


== Warning == <!--T:19-->
=== Warning ===


<!--T:20-->
Creating, duplicating, or moving a dynamic variable requires '''binding''' that variable to its space. This usually takes a small amount of time, before which the dynamic variable can appear to be present, but not be readable or writable. Therefore, if you create a dynamic variable using the [[Create Dynamic Variable`1 (ProtoFlux node)|Create Dynamic Variable]] or [[Write Or Create Dynamic Variable`1 (ProtoFlux node)|Write Or Create Dynamic Variable]] Protoflux node, or cause it to be duplicated using the [[Duplicate Slot (ProtoFlux node)|Duplicate Slot]] Protoflux node, or cause it to be moved using the [[Set Parent (ProtoFlux node)|Set Parent]] Protoflux node, you may find it necessary to add an [[Updates Delay (ProtoFlux node)|Updates Delay]] or [[Updates Delay With Value (ProtoFlux node)|Updates Delay With Value]] Protoflux node afterwards in order to ensure the dynamic variables have been bound by the time you use them. A delay of 1 to 3 updates usually suffices.
Creating, duplicating, or moving a dynamic variable requires '''binding''' that variable to its space. This usually takes a small amount of time, before which the dynamic variable can appear to be present, but not be readable or writable. Therefore, if you create a dynamic variable using the [[Create Dynamic Variable`1 (ProtoFlux node)|Create Dynamic Variable]] or [[Write Or Create Dynamic Variable`1 (ProtoFlux node)|Write Or Create Dynamic Variable]] Protoflux node, or cause it to be duplicated using the [[Duplicate Slot (ProtoFlux node)|Duplicate Slot]] Protoflux node, or cause it to be moved using the [[Set Parent (ProtoFlux node)|Set Parent]] Protoflux node, you may find it necessary to add an [[Updates Delay (ProtoFlux node)|Updates Delay]] or [[Updates Delay With Value (ProtoFlux node)|Updates Delay With Value]] Protoflux node afterwards in order to ensure the dynamic variables have been bound by the time you use them. A delay of 1 to 3 updates usually suffices.

Revision as of 17:52, 13 January 2024

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


Overview

Dynamic variables allow you to read and write data by name. This makes it easy to manage data in large systems; every bit of data is clearly labeled, and you can break data into multiple spaces to keep your systems separate.=

Naming Restrictions

When using Dynamic Variables there are some restrictions and limitations on naming both spaces and variables within those spaces.

Space and Variable Names cannot contain:

Usage

Optionally, the name can be prefixed by the name of a space, terminated by a /, to choose a specific variable space to use. This is useful to distinguish between unrelated systems that all use dynamic variables.

Some valid names include:

  • Health -- no space defined, named Health
  • World/Color -- named Color, in the World space
  • MyCoolSystem/Score -- named Score, in the MyCoolSystem space

Spaces

Dynamic variables can live anywhere in or under the slot containing a DynamicVariableSpace component.

So, a variable space on the world root can be used from anywhere, whilst a variable space on your avatar can be used from anything stored in your avatar.

Variables

The simplest way to use dynamic variables is to use the DynamicValueVariable<T> and DynamicReferenceVariable<T> components. These are for value (int, float, String, etc.) and reference (Slot, User, etc.) types, respectively.

These components store a value or reference directly. If two variable components have the same name, then they will have identical contents.

Fields

If you want to use an existing field or reference as the contents of a dynamic variable, you can use the DynamicField<T> or DynamicReference<T> components. Instead of storing something directly, they point at a field that contains a value or reference type, respectively.

(TODO: clarify value vs. reference types; I think this isn't fully correct)

Drivers

You can use the contents of a dynamic variable to drive a field or reference, using the DynamicValueVariableDriver<T> and DynamicReferenceVariableDriver<T> components.

Unlisted types

When creating a dynamic variable component, you will be given a list of "common types". If the type you seek is not in that list, you will have to enter it by hand. See Complex Types in Components.

Warning

Creating, duplicating, or moving a dynamic variable requires binding that variable to its space. This usually takes a small amount of time, before which the dynamic variable can appear to be present, but not be readable or writable. Therefore, if you create a dynamic variable using the Create Dynamic Variable or Write Or Create Dynamic Variable Protoflux node, or cause it to be duplicated using the Duplicate Slot Protoflux node, or cause it to be moved using the Set Parent Protoflux node, you may find it necessary to add an Updates Delay or Updates Delay With Value Protoflux node afterwards in order to ensure the dynamic variables have been bound by the time you use them. A delay of 1 to 3 updates usually suffices.