Dynamic Variables/fr: Difference between revisions

From Resonite Wiki
Created page with "A la création d'une variable dynamique, vous pouvez choisir depuis une liste de types communs. Si ce que vous voulez n'est pas dans la liste, vous allez devoir entrer le type complexe manuellement."
Updating to match new version of source page
Line 1: Line 1:
<languages/>
<languages/>
{{stub}}


== Aperçu ==
== Aperçu ==


Les '''variables dynamiques''' vous permettent de lire et écrire des information depuis un simple nom. Elles rendent simple la gestion de données dans des systèmes larges; chaque bout de données est étiquetée correctement que vous pouvez décomposer en plusieurs '''espaces'''.
<span class="mw-translate-fuzzy">Les '''variables dynamiques''' vous permettent de lire et écrire des information depuis un simple nom. Elles rendent simple la gestion de données dans des systèmes larges; chaque bout de données est étiquetée correctement que vous pouvez décomposer en plusieurs '''espaces'''.</span>


== Restrictions de noms ==
== Restrictions de noms ==
Line 16: Line 14:
** Comme défini en C# avec [https://docs.microsoft.com/en-us/dotnet/api/system.char.ispunctuation?view=net-5.0 Char.IsPunctuation] et [https://docs.microsoft.com/en-us/dotnet/api/system.char.iswhitespace?view=net-5.0 Char.IsWhiteSpace]
** Comme défini en C# avec [https://docs.microsoft.com/en-us/dotnet/api/system.char.ispunctuation?view=net-5.0 Char.IsPunctuation] et [https://docs.microsoft.com/en-us/dotnet/api/system.char.iswhitespace?view=net-5.0 Char.IsWhiteSpace]
* '''Excepté''' pour les points (.), underscore (_) et espaces ( ).
* '''Excepté''' pour les points (.), underscore (_) et espaces ( ).
<div lang="en" dir="ltr" class="mw-content-ltr">
{{Note|Which concept or properties do your spaces and variables represent? Take your time to name them appropriately!<br/> Those names will be used in different places or even by multiple users. Changing them after the fact can become quite challenging. |suggestion}}
</div>


== Utilisation ==
== Utilisation ==
Line 35: Line 37:
=== Variables ===
=== Variables ===


La manière la plus simple d'utiliser les variables dynamiques est d'utiliser les composants [[DynamicValueVariable%601_(Component)|DynamicValueVariable<T>]] et [[DynamicReferenceVariable%601_(Component)|DynamicReferenceVariable<T>]]. Ils fonctionnent pour des valeurs (int, float, String...) et references (Slot, Utilisateur...).
<span class="mw-translate-fuzzy">La manière la plus simple d'utiliser les variables dynamiques est d'utiliser les composants [[DynamicValueVariable%601_(Component)|DynamicValueVariable<T>]] et [[DynamicReferenceVariable%601_(Component)|DynamicReferenceVariable<T>]]. Ils fonctionnent pour des valeurs (int, float, String...) et references (Slot, Utilisateur...).</span>
   
   
Ces components stockent une valeur ou référence directement. Si deux variable ont le même nom, elles auront des valeurs identiques.
Ces components stockent une valeur ou référence directement. Si deux variable ont le même nom, elles auront des valeurs identiques.
Line 41: Line 43:
=== Champs ===
=== Champs ===


<div class="mw-translate-fuzzy">
Si vous voulez utiliser un champ ou référence comme contenu d'une variable dynamique, vous pouvez utiliser les composants [[DynamicField%601_(Component)|DynamicField<T>]] ou [[DynamicReference%601_(Component)|DynamicReference<T>]]. A la place de stocker quelque chose directement, ils pointent a un champ contenant une certaine valeur ou référence.
Si vous voulez utiliser un champ ou référence comme contenu d'une variable dynamique, vous pouvez utiliser les composants [[DynamicField%601_(Component)|DynamicField<T>]] ou [[DynamicReference%601_(Component)|DynamicReference<T>]]. A la place de stocker quelque chose directement, ils pointent a un champ contenant une certaine valeur ou référence.
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
As with variables there is a variant for <code>Type</code> fields: [[Component:DynamicTypeField|DynamicTypeField]]
</div>


(A FAIRE: clarifier les types valeur vs référence)
(A FAIRE: clarifier les types valeur vs référence)
Line 47: Line 55:
=== Pilotes ===
=== Pilotes ===


Vous pouvez utiliser le contenu d'une variable dynamique pour piloter un champ ou référence en utilisant les composants [[DynamicValueVariableDriver%601_(Component)|DynamicValueVariableDriver<T>]] ou [[DynamicReferenceVariableDriver%601_(Component)|DynamicReferenceVariableDriver<T>]].
<span class="mw-translate-fuzzy">Vous pouvez utiliser le contenu d'une variable dynamique pour piloter un champ ou référence en utilisant les composants [[DynamicValueVariableDriver%601_(Component)|DynamicValueVariableDriver<T>]] ou [[DynamicReferenceVariableDriver%601_(Component)|DynamicReferenceVariableDriver<T>]].</span>


=== Types non-listés ===
=== Types non-listés ===


A la création d'une variable dynamique, vous pouvez choisir depuis une liste de types communs. Si ce que vous voulez n'est pas dans la liste, vous allez devoir entrer le [[Complex Types in Components | type complexe]] manuellement.
A la création d'une variable dynamique, vous pouvez choisir depuis une liste de types communs. Si ce que vous voulez n'est pas dans la liste, vous allez devoir entrer le [[Complex Types in Components | type complexe]] manuellement.
===  <span lang="en" dir="ltr" class="mw-content-ltr">Binding</span> ===
<div lang="en" dir="ltr" class="mw-content-ltr">
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|Warning]])
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
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 <code>OnlyDirectBinding</code>
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
The following image will demonstrate the differences in binding:
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
[[File:Dynamic_Variables.svg|border|an image demonstrating that dynamic variable spaces with enabled OnlyDirectBinding are ignored except by variables which have explicitly declared the same space name]]
* I: <code>A</code> is connected to <code>Inner</code> because <code>Inner</code> is <u>not</u> <code>OnlyDirectBinding</code>.
* II/III: Both variables are bound explicitly.
* IV: <code>A</code> ignores <code>Inner</code> because <code>Inner</code> is <code>OnlyDirectBinding</code>.
* 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 <code>World</code>.
* I and II share the same value.
* III, IV and VI share the same value.
</div>
{{#mermaid:flowchart BT
    subgraph outside
       
        InvalidSpace["Invalid, not linked"]
        RootSlot
    end
    subgraph RootSlot [RootSlot]
        World["Space #34;World#34;"]
        color["World/Color1"] --> World
       
       
        UserRootSlot
       
    end
    subgraph UserRootSlot
        UserSpace["Space #34;User#34;"]
        AvatarRootSlot
        V["User/Voice"] --> UserSpace
        V2["User/Color"] --> UserSpace
    end
   
    subgraph AvatarRootSlot
        avatar["User/Avatar"]
        avatarworld["World/Avatar.U-myid"]
        hips["HipsSlot"] --> AvatarSpace
        invalid["None/float"]
       
        AvatarSpace["Space #34;Avatar#34;"]
       
        Flux2_node0(["DynamicVariableInput#60;ColorX#62;#12;#34;World/Color1#34;"])
        Flux2_node0 -. points to .-> color
    end
   
   
    avatarworld --> World
    avatar --> UserSpace
    subgraph Flux1
        Flux1_node0(["User Root Slot"]) -. automatically points to .-> UserRootSlot
        Flux1_node1(["Read #34;User/Avatar#34;"]) --> Flux1_node0
        Flux1_node1 -. points to .-> AvatarRootSlot
        Flux1_node2(["Read Variable #34;Avatar/Hips#34;"]) --> Flux1_node1
        Flux1_node2 -. points to .-> hips
    end
    invalid --> InvalidSpace
   
   
   
   
}}


=== Attention ===
=== Attention ===


Créer, dupliquer ou bouger des variables dynamiques demande de '''lier''' cette variable a son espace. Ceci est généralement rapide, pendant ce temps, la variable n'est ni lisible, ni inscriptible. Quand vous créez une variable dynamique en utilisant [[Create Dynamic Variable`1 (ProtoFlux)|Create Dynamic Variable]] ou [[Write Or Create Dynamic Variable`1 (ProtoFlux)|Write Or Create Dynamic Variable]], ou dupliquez le slot avec [[Duplicate Slot (ProtoFlux)|Duplicate Slot]], ou bougez le slot avec [[Set Parent (ProtoFlux)|Set Parent]], vous devez dans certains cas ajouter un délais avec [[Updates Delay (ProtoFlux)|Updates Delay]] ou [[Updates Delay With Value (ProtoFlux)|Updates Delay With Value]] pour attendre correctement que les variables sont liées correctement quand vous voulez les lires. Généralement un delais de 1 a 3 ticks est assez.
<span class="mw-translate-fuzzy">Créer, dupliquer ou bouger des variables dynamiques demande de '''lier''' cette variable a son espace. Ceci est généralement rapide, pendant ce temps, la variable n'est ni lisible, ni inscriptible. Quand vous créez une variable dynamique en utilisant [[Create Dynamic Variable`1 (ProtoFlux)|Create Dynamic Variable]] ou [[Write Or Create Dynamic Variable`1 (ProtoFlux)|Write Or Create Dynamic Variable]], ou dupliquez le slot avec [[Duplicate Slot (ProtoFlux)|Duplicate Slot]], ou bougez le slot avec [[Set Parent (ProtoFlux)|Set Parent]], vous devez dans certains cas ajouter un délais avec [[Updates Delay (ProtoFlux)|Updates Delay]] ou [[Updates Delay With Value (ProtoFlux)|Updates Delay With Value]] pour attendre correctement que les variables sont liées correctement quand vous voulez les lires. Généralement un delais de 1 a 3 ticks est assez.</span>
 
TODO: more precise list of problematic uses cases (e.g. <code>Duplicate Slot</code> of a whole space works totally fine.)
 
==  <span lang="en" dir="ltr" class="mw-content-ltr">Example Applications</span> ==
 
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
 
===  <span lang="en" dir="ltr" class="mw-content-ltr">Modules within an object</span>  ===
 
<div lang="en" dir="ltr" class="mw-content-ltr">
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.
</div>
 
<div lang="en" dir="ltr" class="mw-content-ltr">
Commonly used names for such hierarchies are:
* DV
* DynVar
* Vars
* etc.
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
A modular object could look like this:
* Project (Space: <code>MyProject</code>)
** Dynamic Variables
*** projectVar: String (Dynamic variable <code>projectVar</code> of type [[Type:String|String]])
** Module: UI (i.e. [[Component:MeshRenderer|MeshRenderer]] or [[Component:Canvas|Canvas]] plus [[Collider|Colliders]]), may contain:
*** Dynamic Variable Drivers → Visuals
*** [[:Category:Components:Common_UI:Button_Interactions|Button Interactions]] → Dynamic Variables
*** [[:Category:Components:Common_UI:Editors|Editors]] ↔ Dynamic Variables
** Module: Logic (Space: <code>Logic</code>)
*** Dynamic Variables
**** logicVar: int (Dynamic variable <code>logicVar</code> of type [[Type:Int|int]])
**** MyProject/Logic: Slot (Dynamic variable <code>Logic</code> of type [[Slot]] for space <code>MyProject</code>, 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 <code>MyProject</code>)
</div>
 
===  <span lang="en" dir="ltr" class="mw-content-ltr">Configurable objects</span>  ===
<div lang="en" dir="ltr" class="mw-content-ltr">
Dynamic variables make it possible to access other object's properties.
</div>
 
<div lang="en" dir="ltr" class="mw-content-ltr">
Assuming objects with a dynamic variable space, a collider and a string variable named <code>Description</code> you could then create a separate tool that reads and displays the <code>Description</code> of the object it is pointed at. The same tool could be extended to edit descriptions.
</div>
 
<div lang="en" dir="ltr" class="mw-content-ltr">
The same concept can also be applied to template slots used within a project.
Their instances can be interacted with using dynamic variables.
</div>
===  <span lang="en" dir="ltr" class="mw-content-ltr">World/User variables</span>  ===
<div lang="en" dir="ltr" class="mw-content-ltr">
There are already pre-made dynamic variable spaces:
* <code>World</code> on [[Root]] (<code>OnlyDirectBinding</code>)
* <code>User</code> on each [[Component:UserRoot|User Root]] Slot (<code>OnlyDirectBinding</code>)
* <code>Dash</code> on Slot of [[Component:UserspaceRadiantDash|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)
</div>
 
<div lang="en" dir="ltr" class="mw-content-ltr">
See [[Dynamic Variable Naming Standard]] for a more detailed listing.
</div>

Revision as of 18:30, 24 April 2024

Aperçu

Les variables dynamiques vous permettent de lire et écrire des information depuis un simple nom. Elles rendent simple la gestion de données dans des systèmes larges; chaque bout de données est étiquetée correctement que vous pouvez décomposer en plusieurs espaces.

Restrictions de noms

En utilisant les variables dynamiques, il y a quelques restrictions sur le nommage sur les variables et espaces.

Les noms de variables et espaces ne peuvent pas contenir:

Which concept or properties do your spaces and variables represent? Take your time to name them appropriately!
Those names will be used in different places or even by multiple users. Changing them after the fact can become quite challenging.

Utilisation

Optionnellement, un nom de variable peut être préfixé avec le nom d'un espace, se finissant avec /, pour choisir un espace de variables. Cela est utile pour distinguer des systèmes indépendants.

Quelques noms valides incluent:

  • Vie -- pas d'espaces, juste nommé Vie
  • World/Couleur -- nommé Couleur, dans l'espace World
  • MonSysteme/Score -- Nommé Score, dans l'espace MonSysteme

Espaces

Les variables dynamiques peuvent être n'importe ou ou sous un slot contenant le composant DynamicVariableSpace.

Donc, une variable sur l'origine du monde peut être utilisée de partout alors qu'une variable dans un espace sur votre avatar ne peut être utilisée que sur votre avatar.

Variables

La manière la plus simple d'utiliser les variables dynamiques est d'utiliser les composants DynamicValueVariable<T> et DynamicReferenceVariable<T>. Ils fonctionnent pour des valeurs (int, float, String...) et references (Slot, Utilisateur...).

Ces components stockent une valeur ou référence directement. Si deux variable ont le même nom, elles auront des valeurs identiques.

Champs

Si vous voulez utiliser un champ ou référence comme contenu d'une variable dynamique, vous pouvez utiliser les composants DynamicField<T> ou DynamicReference<T>. A la place de stocker quelque chose directement, ils pointent a un champ contenant une certaine valeur ou référence.

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

(A FAIRE: clarifier les types valeur vs référence)

Pilotes

Vous pouvez utiliser le contenu d'une variable dynamique pour piloter un champ ou référence en utilisant les composants DynamicValueVariableDriver<T> ou DynamicReferenceVariableDriver<T>.

Types non-listés

A la création d'une variable dynamique, vous pouvez choisir depuis une liste de types communs. Si ce que vous voulez n'est pas dans la liste, vous allez devoir entrer le type complexe manuellement.

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:

an image demonstrating that dynamic variable spaces with enabled OnlyDirectBinding are ignored except by variables which have explicitly declared the same space name

  • 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.


Attention

Créer, dupliquer ou bouger des variables dynamiques demande de lier cette variable a son espace. Ceci est généralement rapide, pendant ce temps, la variable n'est ni lisible, ni inscriptible. Quand vous créez une variable dynamique en utilisant Create Dynamic Variable ou Write Or Create Dynamic Variable, ou dupliquez le slot avec Duplicate Slot, ou bougez le slot avec Set Parent, vous devez dans certains cas ajouter un délais avec Updates Delay ou Updates Delay With Value pour attendre correctement que les variables sont liées correctement quand vous voulez les lires. Généralement un delais de 1 a 3 ticks est assez.

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

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.