Linkage: Difference between revisions

From Resonite Wiki
m ,
fugggg wrong template
 
(7 intermediate revisions by the same user not shown)
Line 1: Line 1:
<languages />
<languages />
{{Note|"FieldHook" and "Field hook" redirect here. For the ProtoFlux node, see [[ProtoFlux:Field Hook]]|information}}


<translate>
<translate>
<!--T:1-->
<!--T:1-->
'''Field linkage''' is a way to give exclusive control of the value of a [[field]] to one singular source in various different ways. These ways are known as ''links'', ''drives'', and ''hooks''. Linked fields grab their value from some source usually known as the ''driver''.
'''Linkage''' is a way to give exclusive control of the value of a [[sync element]]{{em dash}}usually a [[Type:SyncField`1|field]]{{em dash}}to one singular source in various different ways. These ways are known as ''links'', ''drives'', and ''hooks''. Linked elements are exclusively controlled from some source usually known as the ''driver''.
</translate>
</translate>


Line 14: Line 12:
<translate>
<translate>
<!--T:4-->
<!--T:4-->
The most basic form of linkage is known as a '''link'''. Linked fields appear as cyan in the inspector. Links will continuously set the linked field with whatever value the driver provides. This type of field relation is synced, and will not differ locally between users other than the case of network delays.
The most basic form of linkage is known as a '''link'''. Linked elements appear as cyan in the inspector. Links establish exclusive control of the linked element to the driver. This allows the driver, and only the driver, to update the value of the element. This type of relation is synced and will not differ locally between users other than the case of network delays.
</translate>
</translate>


<translate>
<translate>
<!--T:5-->
<!--T:5-->
Links are rarely used within the game and are only necessary for specific purposes. For example, attempting to drive a [[Type:FieldDrive`1|FieldDrive&lt;T&gt;]] type will result in the field becoming linked. This is due to [[FrooxEngine]] not wanting the drive state of a field to be local. Links are also used in some parts of user and avatar setup in worlds.
This form of linkage is rarely used within the game and is only necessary for specific purposes. For example, attempting to drive a [[Type:FieldDrive`1|FieldDrive&lt;T&gt;]] type will result in the field becoming linked. This is due to [[FrooxEngine]] not wanting the state of an element being driven to differ between each user, as localizing such a property could lead to major synchronization issues. Links are also used in some parts of user and avatar setup in worlds.
</translate>
</translate>


Line 28: Line 26:
<translate>
<translate>
<!--T:8-->
<!--T:8-->
'''Drives''' are an extension of links and the most common form of linkage that one will encounter in Resonite. Driven fields appear as purple in the inspector. As with links, drives will continuously set the driven field with whatever value the driver provides. However, unlike links, the value of a driven field is inherently local to each individual user. Because of this locality, drives are usually used to reduce network traffic by having each individual user calculate a value on their own machine.
'''Drives''' are an extension of links and the most common form of linkage that one will encounter in Resonite. Driven elements appear as purple in the inspector. As with links, drives establish exclusive control over the driven element to the driver. However, unlike links, changes to a driven element are not synchronized over the network. This results in the value of a driven sync element to be local to each individual user. Because of this locality, drives are usually used to reduce network traffic by having each individual user calculate the value of an element on their own machine.
</translate>
</translate>


<translate>
<translate>
<!--T:9-->
<!--T:9-->
Fields can become driven with either [[components]] or [[ProtoFlux]]. With components, most drivers are found under the [[:Category:Components:Transform:Drivers|Transform/Drivers]] or [[:Category:Components:Relations|Relations]] categories. With ProtoFlux, while holding the [[ProtoFlux Tool]], you can drag out a field from an inspector, open the [[context menu]] while still holding the field, and choose the "Drive" option. This will create a [[ProtoFlux:Value Field Drive|Value Field Drive]] or [[ProtoFlux:Object Field Drive|Object Field Drive]] node to drive the value of a field.
Elements can become driven with either [[components]] or [[ProtoFlux]]. With components, most drivers are found under the [[:Category:Components:Transform:Drivers|Transform/Drivers]] or [[:Category:Components:Relations|Relations]] categories. With ProtoFlux, while holding the [[ProtoFlux Tool]], one can drag out a [[Type:SyncField`1|field]] from an inspector, open the [[context menu]] while still holding the field, and choose the "Drive" option. This will create a [[ProtoFlux:Value Field Drive|Value Field Drive]] or [[ProtoFlux:Object Field Drive|Object Field Drive]] node to drive the value of the field. Other sync elements that are not derivations of the [[Type:SyncField|SyncField]] type can not be driven in ProtoFlux at this time.
</translate>
</translate>


<translate>
<translate>
<!--T:10-->
<!--T:10-->
Another way to drive fields in ProtoFlux is via the [[ProtoFlux:Field Hook|Field Hook]] node. This is a lower-level interface to driving, as it allows one to start and stop drives arbitrarily on a field using impulses.
Another way to drive fields in ProtoFlux is via the [[ProtoFlux:Field Hook|Field Hook]] node. This is a lower-level interface to driving, as it allows one to start and stop drives arbitrarily on a field using impulses. It also allows one to use a [[#Hooks|hook]] to allow other sources to write to the field.
</translate>
</translate>


Line 45: Line 43:
<translate>
<translate>
<!--T:12-->
<!--T:12-->
'''Hooks''' are an extension of drives. They are essentially the same thing as drives except for the fact that when the driven field attempts to be written to, a function will be run. This function is defined by the driver.
A '''Hook''' is an optional part of linkage that certain drivers may utilize. It is a function that will be run when the linked element attempts to be changed. This function is defined by the driver. This allows the driver to arbitrarily change the behavior of writing to a sync element.
</translate>
</translate>


Line 52: Line 50:
<translate>
<translate>
<!--T:14-->
<!--T:14-->
The most commonly-named hook that one might encounter is called <code>WriteBack</code>. This makes it so that when one attempts to write to the driven field, the write will go through, writing both to the source value and driven value at once.
The most commonly-named hook that one might encounter is called <code>WriteBack</code>, seen on the [[Component:ValueCopy|ValueCopy]] component for example. This makes it so that when one attempts to write to the driven field, the write will go through, writing both to the source value and driven value at once.
</translate>
</translate>


Line 59: Line 57:
This hook can cause an interesting effect when combined with the locality of drives. If one were to [[Component:ValueCopy|ValueCopy]] a field onto itself and enable writeback, the field becomes a local field with the backbone of the [[data model]] to support it, as opposed to something like a [[ProtoFlux:Store|Store]] in ProtoFlux.
This hook can cause an interesting effect when combined with the locality of drives. If one were to [[Component:ValueCopy|ValueCopy]] a field onto itself and enable writeback, the field becomes a local field with the backbone of the [[data model]] to support it, as opposed to something like a [[ProtoFlux:Store|Store]] in ProtoFlux.
</translate>
</translate>
== <translate><!--T:16--> How linked fields are updated</translate> ==
<translate>
<!--T:17-->
It is important to remember that an element being linked is a separate concept from the value of the element being updated. All that linkage establishes is a way to make sure that a sync element is controlled by one and only one source only--however that element gets updated and the value it gets updated with is still the responsibility of the driver. This could be on every engine update, whenever the component detects a change from some source, or any other way the component sees fit.
</translate>
=== ProtoFlux ===
<translate>
<!--T:18-->
In the [[ProtoFlux]] [[FrooxEngineContext]], a [[ProtoFlux:Value Field Drive|Field Drive]] node is a [[listener node]]. Whenever the node is notified of a change from its input context, it will evaluate its input and write the result to the field. This makes ProtoFlux drives <em>lazy</em> by default--usually only evaluating their input when needed. However, as with all listener nodes, if the input node graph has a node marked with the [[ContinuouslyChanging]] property, it will cause the drive to evaluate its input every [[engine update]].
</translate>
[[Category:Data model]]

Latest revision as of 17:14, 3 July 2025

Linkage is a way to give exclusive control of the value of a sync element—usually a field—to one singular source in various different ways. These ways are known as links, drives, and hooks. Linked elements are exclusively controlled from some source usually known as the driver.

Links

The Target field in this image is linked, as shown by it being cyan. This is due to it being a FieldDrive<T> type.

The most basic form of linkage is known as a link. Linked elements appear as cyan in the inspector. Links establish exclusive control of the linked element to the driver. This allows the driver, and only the driver, to update the value of the element. This type of relation is synced and will not differ locally between users other than the case of network delays.

This form of linkage is rarely used within the game and is only necessary for specific purposes. For example, attempting to drive a FieldDrive<T> type will result in the field becoming linked. This is due to FrooxEngine not wanting the state of an element being driven to differ between each user, as localizing such a property could lead to major synchronization issues. Links are also used in some parts of user and avatar setup in worlds.

Drives

The Rotation field on the slot is driven by the AutoLookAtUser, as shown by it being purple.

Drives are an extension of links and the most common form of linkage that one will encounter in Resonite. Driven elements appear as purple in the inspector. As with links, drives establish exclusive control over the driven element to the driver. However, unlike links, changes to a driven element are not synchronized over the network. This results in the value of a driven sync element to be local to each individual user. Because of this locality, drives are usually used to reduce network traffic by having each individual user calculate the value of an element on their own machine.

Elements can become driven with either components or ProtoFlux. With components, most drivers are found under the Transform/Drivers or Relations categories. With ProtoFlux, while holding the ProtoFlux Tool, one can drag out a field from an inspector, open the context menu while still holding the field, and choose the "Drive" option. This will create a Value Field Drive or Object Field Drive node to drive the value of the field. Other sync elements that are not derivations of the SyncField type can not be driven in ProtoFlux at this time.

Another way to drive fields in ProtoFlux is via the Field Hook node. This is a lower-level interface to driving, as it allows one to start and stop drives arbitrarily on a field using impulses. It also allows one to use a hook to allow other sources to write to the field.

Hooks

A Hook is an optional part of linkage that certain drivers may utilize. It is a function that will be run when the linked element attempts to be changed. This function is defined by the driver. This allows the driver to arbitrarily change the behavior of writing to a sync element.

WriteBack

The most commonly-named hook that one might encounter is called WriteBack, seen on the ValueCopy component for example. This makes it so that when one attempts to write to the driven field, the write will go through, writing both to the source value and driven value at once.

This hook can cause an interesting effect when combined with the locality of drives. If one were to ValueCopy a field onto itself and enable writeback, the field becomes a local field with the backbone of the data model to support it, as opposed to something like a Store in ProtoFlux.

How linked fields are updated

It is important to remember that an element being linked is a separate concept from the value of the element being updated. All that linkage establishes is a way to make sure that a sync element is controlled by one and only one source only--however that element gets updated and the value it gets updated with is still the responsibility of the driver. This could be on every engine update, whenever the component detects a change from some source, or any other way the component sees fit.

ProtoFlux

In the ProtoFlux FrooxEngineContext, a Field Drive node is a listener node. Whenever the node is notified of a change from its input context, it will evaluate its input and write the result to the field. This makes ProtoFlux drives lazy by default--usually only evaluating their input when needed. However, as with all listener nodes, if the input node graph has a node marked with the ContinuouslyChanging property, it will cause the drive to evaluate its input every engine update.