Динамические переменные

Обзор

Динамические переменные позволяют вам читать и писать данные по имени в контексте иерархии слотов. Это упрощает управление данными в больших системах; каждый бит данных четко помечен, и вы можете разбивать данные на несколько пространств, чтобы разделять ваши системы.

Ограничения именования

При использовании динамических переменных существуют некоторые ограничения на именование пространств и переменных внутри этих пространств.

Пространства и имена переменных не могут содержать:

• Любые символы
  • Как определено в C# Char.IsSymbol
• Любую пунктуацию / Пробелы
  • Как определено в C# Char.IsPunctuation и C# Char.IsWhiteSpace
• За исключением точки (.), нижнего подчеркивания (_) и пробела ( ).

Какую концепцию или свойства предоставляют ваши пространства и переменные? Не торопитесь и назовите их как следует!
Эти имена будут использоваться в разных местах или даже другими пользователями. Изменения этих имен потом может оказаться довольно сложной задачей.

Использование

При желании к имени может быть добавлен префикс в виде пробела заканчивающийся символом /, чтобы выбрать конкретное пространство для использования переменной. Это полезно для того, что различать несвязанные системы, в которых используют динамические переменные.

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. DynamicTypeVariable exists to store Types.

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.

As with variables there is a variant for Type fields: DynamicTypeField

(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:

• I: A is connected to Inner because Inner is not OnlyDirectBinding.
• II/III: Both variables are bound explicitly.
• IV: A ignores Inner because Inner is OnlyDirectBinding.
• 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.

TODO: more precise list of problematic uses cases (e.g. Duplicate Slot of a whole space works totally fine.)

Example Applications

The following examples will demonstrate a few use-cases of dynamic variables. There is a focus on how to use them to create separate objects

Modules within an object

Dynamic variables within an object allow modularization. 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 with 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.

A modular object could look like this:

• Project (Space: MyProject)
  • Dynamic Variables
    • projectVar: String (Dynamic variable projectVar of type String)
  • Module: UI (i.e. MeshRenderer or Canvas plus Colliders), may contain:
    • Dynamic Variable Drivers → Visuals
    • Button Interactions → Dynamic Variables
    • Editors ↔ Dynamic Variables
  • Module: Logic (Space: Logic)
    • Dynamic Variables
      • logicVar: int (Dynamic variable logicVar of type int)
      • MyProject/Logic: Slot (Dynamic variable Logic of type Slot for space MyProject, driven with reference to Slot of module to make it accessible to other modules)
    • ProtoFlux (may read, write or even drive dynamic variables of space MyProject)

Configurable objects

Dynamic variables make it possible to access other object's properties.

Assuming objects with a dynamic variable space, a collider and a string variable named Description you could then create a separate tool that reads and displays the Description of the object it is pointed at. The same tool could be extended to edit descriptions.

The same concept can also be applied to template slots used within a project. Their instances can be interacted with using dynamic variables.

World/User variables

There are already pre-made dynamic variable spaces:

• World on Root (OnlyDirectBinding)
• User on each User Root Slot (OnlyDirectBinding)
• Dash on Slot of UserSpaceRadiantDash

They can be used for states that are shared by many objects (i.e. day/night toggle, performance) or to broadcast information into the world. (BeatLink, library objects like the Redprint manager)

See Dynamic Variable Naming Standard for a more detailed listing.