User:Yosh/sandbox: Difference between revisions

Latest revision as of 06:05, 3 July 2025

The data model refers to the declaration, structure, and handling of types, data, and changes on data within FrooxEngine. The data model allows for change detection, value synchronization, unified structure, and serialization of any and all types that FrooxEngine encounters.

Elements

Everything that gets managed by the data model in some fashion implements the IWorldElement interface. This interface assigns elements with a host of properties, including a reference ID, possible parent element, and whether the element is persistent or not.

This interface doesn't have much behavior by itself--it only specifies a thing as being able to be saved and loaded into worlds in some fashion. More complex behaviors offered by the data model are provided by types that implement this interface. The three types of elements that directly implement this interface are sync elements, workers, and worlds.

Sync elements

Sync elements represent a value or object that can be written to, linked, and send/receive change events from other elements. Sync elements mainly comprise of fields and various types of collections--usually any type name that starts with Sync derives from a sync element.

The main thing that separates sync elements from other elements is, well, synchronization. Whenever a sync element is changed, spare few exceptions like RawOutput<T>, it and its entire parent hierarchy propagate a change event. This includes the elements getting put in the world's update manager to synchronize their values at the end of the update loop.

Linking

Main article: Linkage

Linkage is a way to give exclusive control of a sync element to one source, often referred to a driver. Two types of linkage exist: links and drives, while drivers may choose an optional hook.

When a field is linked, it is shown as cyan in inspectors. Linked fields still send data model events as any normal field, but can only be changed by the driver.

When a field is driven, it is shown as purple in inspectors. Driven fields act the same as linked fields, but the value of a driven field will not be synchronized across the network. This allows for per-user values or local calculations of things that would otherwise be expensive to network.

Workers

Workers are, in essence, containers for sync elements and other workers to provide a specific, individual task for the engine. Examples of workers include slots, components, sub-classes of components, and streams. Workers are able to receive events from their children and propagate events to their parent.

Workers themselves are a local construct. However, they usually exist in sync element collections, and thus their existence is usually synchronized across users along with their elements.

Events

A big part of the data model's function is capturing changes to an element or worker and propagating these changes across the element's parent and references to the element. Everything that exists within the data model can capture and send these events, while things outside the data model will usually not.

For example, the Changeable Source ProtoFlux node is able to receive change events from the element that it references. A changeable source of a slot plugged in to a Get Slot Active node will be able to update a connected listener node whenever the active state of the slot changes. However, an Input node will not update any connected listener nodes in the same fashion. This is due to the former node receiving events from the data model, while the latter does not. Whenever the active field of a slot (a sync element) changes, it propagates that change to the slot itself (the worker containing the active field), which will then get received by the changeable source and thus the entire context of the listener node.

World

The data model exists under a world. The world update loop controls the communication and events between all individual concepts of the data model as one unified pipeline. This includes, but is not limited to:

The UpdateManager for managing all sync elements that are "dirty" and the changes that they incur on other elements/workers.
The LinkManager for managing all of linkage within a world.

Strict exclusivity

The data model can only function without issue when everyone in a session agrees on what the data model should be. If one client tells another client about an element type or worker type that doesn't exist for the recipient, the recipient won't know what to do with the information or how to sync the potential element values. This is the reason why plugins marked as a core assembly type cause incompatible sessions with those who do not have the plugin.

@@ 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.
+The '''data model''' refers to the declaration, structure, and handling of [[types]], data, and changes on data within [[FrooxEngine]]. The data model allows for change detection, value synchronization, unified structure, and serialization of any and all types that FrooxEngine encounters.
-For a quick-start guide on using dynamic variables, the [[How To Use Dynamic Variables]] serves as a straightforward guide.
+== Elements ==
-== Usage ==
+Everything that gets managed by the data model in some fashion implements the [[Type:IWorldElement|IWorldElement]] interface. This interface assigns elements with a host of properties, including a [[Type:RefID|reference ID]], possible parent element, and whether the element is persistent or not.
-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.
-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.
+This interface doesn't have much behavior by itself--it only specifies a thing as being able to be saved and loaded into [[worlds]] in some fashion. More complex behaviors offered by the data model are provided by types that implement this interface. The three types of elements that directly implement this interface are ''sync elements'', ''workers'', and ''worlds''.
-{{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}}
+== Sync elements ==
-=== Dynamic Fields ===
+[[Type:SyncElement|Sync elements]] represent a value or object that can be written to, [[field linkage|linked]], and send/receive change events from other elements. Sync elements mainly comprise of [[Type:SyncField|fields]] and various types of collections--usually any type name that starts with <code>Sync</code> derives from a sync element.
-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 ===
+The main thing that separates sync elements from other elements is, well, synchronization. Whenever a sync element is changed, spare few exceptions like [[Type:RawOutput`1|RawOutput&lt;T&gt;]], it and its entire parent hierarchy propagate a change event. This includes the elements getting put in the world's update manager to synchronize their values at the end of the [[update loop]].
-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.
-==== Driving Dynvars ====
+=== Linking ===
-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.
-== Best Practices ==
+{{Main|Linkage}}
-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:
-* 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.
+Linkage is a way to give exclusive control of a sync element to one source, often referred to a driver. Two types of linkage exist: ''links'' and ''drives'', while drivers may choose an optional ''hook''.
-* 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 ==
+When a field is linked, it is shown as cyan in inspectors. Linked fields still send data model events as any normal field, but can only be changed by the driver.
-As of the time of writing, there are three dynamic spaces that exist by default:
-* <code>World</code>, which exists under the [[Root]] of the world. This space is <code>OnlyDirectBinding</code>.
+When a field is driven, it is shown as purple in inspectors. Driven fields act the same as linked fields, but the value of a driven field will not be synchronized across the network. This allows for per-user values or local calculations of things that would otherwise be expensive to network.
-** 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.
-== Example Applications ==
+== Workers ==
+[[Type:Worker|Workers]] are, in essence, containers for sync elements and other workers to provide a specific, individual task for the engine. Examples of workers include [[slots]], [[components]], sub-classes of components, and [[streams]]. Workers are able to receive events from their children and propagate events to their parent.
+Workers themselves are a local construct. However, they usually exist in sync element collections, and thus their existence is usually synchronized across users along with their elements.
+== Events ==
+A big part of the data model's function is capturing changes to an element or worker and propagating these changes across the element's parent and references to the element. Everything that exists within the data model can capture and send these events, while things outside the data model will usually not.
+For example, the [[ProtoFlux:Changeable Source|Changeable Source]] ProtoFlux node is able to receive change events from the element that it references. A changeable source of a [[Type:slot|slot]] plugged in to a [[ProtoFlux:Get Slot Active|Get Slot Active]] node will be able to update a connected [[listener node]] whenever the active state of the slot changes. However, an [[ProtoFlux:Input|Input]] node will not update any connected listener nodes in the same fashion. This is due to the former node receiving events from the data model, while the latter does not. Whenever the active field of a slot (a sync element) changes, it propagates that change to the slot itself (the worker containing the active field), which will then get received by the changeable source and thus the entire [[context]] of the listener node.
+== World ==
+The data model exists under a [[world]]. The world [[update loop]] controls the communication and events between all individual concepts of the data model as one unified pipeline. This includes, but is not limited to:
+* The [[Type:UpdateManager|UpdateManager]] for managing all sync elements that are "dirty" and the changes that they incur on other elements/workers.
+* The [[Type:LinkManager|LinkManager]] for managing all of linkage within a world.
+== Strict exclusivity ==
+The data model can only function without issue when everyone in a session agrees on what the data model should be. If one client tells another client about an element type or worker type that doesn't exist for the recipient, the recipient won't know what to do with the information or how to sync the potential element values. This is the reason why [[plugins]] marked as a [[How To Create Plugins/DataModelAssemblyType|core]] assembly type cause incompatible sessions with those who do not have the plugin.
+== Further reading ==
+* [[:Category:Data model]] for more in-depth aspects about various parts of the data model.