TheAutopilot (talk | contribs) added detail about value sharing |
TheAutopilot (talk | contribs) WiP: use-case explainations |
||
Line 5: | Line 5: | ||
== <translate><!--T:1--> Overview</translate> == | == <translate><!--T:1--> Overview</translate> == | ||
<translate><!--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.</translate> | <translate><!--T:2--> '''Dynamic variables''' allow you to read and write data by name in the context of a slot hierarchy. 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.</translate> | ||
== <translate><!--T:3--> Naming Restrictions</translate> == | == <translate><!--T:3--> Naming Restrictions</translate> == | ||
Line 82: | Line 82: | ||
<translate><!--T:31--> In a few use-cases binding may take 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)|Create Dynamic Variable]] or [[Write Or Create Dynamic Variable`1 (ProtoFlux)|Write Or Create Dynamic Variable]] ProtoFlux Node, or cause it to be duplicated using the [[Duplicate Slot (ProtoFlux)|Duplicate Slot]] ProtoFlux Node, or cause it to be moved using the [[Set Parent (ProtoFlux)|Set Parent]] ProtoFlux Node, you may find it necessary to add an [[Updates Delay (ProtoFlux)|Updates Delay]] or [[Updates Delay With Value (ProtoFlux)|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.</translate> | <translate><!--T:31--> In a few use-cases binding may take 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)|Create Dynamic Variable]] or [[Write Or Create Dynamic Variable`1 (ProtoFlux)|Write Or Create Dynamic Variable]] ProtoFlux Node, or cause it to be duplicated using the [[Duplicate Slot (ProtoFlux)|Duplicate Slot]] ProtoFlux Node, or cause it to be moved using the [[Set Parent (ProtoFlux)|Set Parent]] ProtoFlux Node, you may find it necessary to add an [[Updates Delay (ProtoFlux)|Updates Delay]] or [[Updates Delay With Value (ProtoFlux)|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.</translate> | ||
== <translate> Example Applications</translate> == | |||
=== <translate> Modules within an object </translate> === | |||
<translate> | |||
Using dynamic variables within an object allows to modularize your project. | |||
Different modules would be connected via dynamic variables within the space located at the root of the object. | |||
If all hard-coded references going in or out of a module are eliminated you can replace it with a different variant/version without additional setup. | |||
Module-local variables can be created within a dynamic variable space located at the root of the module. Use appropriately named spaces to differentiate between the two. | |||
To make available variables more obvious to other people - including you in 6 months - it is recommended to place all dynamic variables within a dedicated slot hierarchy. | |||
Commonly used names for such hierarchies are: | |||
* DV | |||
* DynVar | |||
* Vars | |||
* etc. | |||
</translate> | |||
TODO: example + image | |||
=== <translate> Configurable objects / making properties accessible from the outside </translate> === | |||
* TODO: explain use-case | |||
* TODO: example + image | |||
=== <translate> Public Interface (World/User) </translate> === | |||
* TODO: explain use-case | |||
* TODO: collect examples/link to list of known variables |
Revision as of 18:43, 20 March 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 in the context of a slot hierarchy. 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:
- Any symbols
- As defined in C# Char.IsSymbol
- Any Punctuation / Whitespace
- As defined in C# Char.IsPunctuation and C# Char.IsWhiteSpace
- Except for period (.), underscore (_) and space ( ).
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.
Binding
Creating, duplicating, or moving a dynamic variable requires binding that variable to a space. This is a process that happens automatically but isn't perfect yet. (see Warning)
In essence it starts searching for a matching dynamic variable space at the slot of the dynamic variable.
If there is no match, it tries the parent slot, its parent etc. until a matching space is found.
Variables with explicitly given space names only match spaces with the same name.
Variables without explicit space name match all spaces that are not OnlyDirectBinding
The following image will demonstrate the differences in binding:
Note:
- I:
A
is connected toInner
becauseInner
is notOnlyDirectBinding
. - II/III: Both variables are bound explicitly.
- IV:
A
ignoresInner
becauseInner
isOnlyDirectBinding
. - V/VI: Both variables are bound explicitly.
- VII/IX: There is no matching dynamic variable space. Both variables are not bound.
- VIII: The variable is explicitly bound to
World
. - I and II share the same value.
- III, IV and VI share the same value.
Warning
In a few use-cases binding may take 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.
Example Applications
Modules within an object
Using dynamic variables within an object allows to modularize your project. Different modules would be connected via dynamic variables within the space located at the root of the object. If all hard-coded references going in or out of a module are eliminated you can replace it with a different variant/version without additional setup. Module-local variables can be created within a dynamic variable space located at the root of the module. Use appropriately named spaces to differentiate between the two. To make available variables more obvious to other people - including you in 6 months - it is recommended to place all dynamic variables within a dedicated slot hierarchy. Commonly used names for such hierarchies are:
- DV
- DynVar
- Vars
- etc.
TODO: example + image
Configurable objects / making properties accessible from the outside
- TODO: explain use-case
- TODO: example + image
Public Interface (World/User)
- TODO: explain use-case
- TODO: collect examples/link to list of known variables