Linkage: Difference between revisions

From Resonite Wiki
→‎Hooks: clarify, rewrite, and add more info
overhaul
Line 1: Line 1:
A [[Field]] on the [[Data Model]] can be [[Link|Linked]], [[Drive|Driven]] or [[Hook|Hooked]]. These are different ways of specifying the type of control a system can have over fields it is influencing. In the [[Scene Inspector]], linked fields are highlighted blue, and driven or hooked fields are highlighted purple. There you can also easily find the source of a linked / driven field by clicking on the hamburger menu button on the left side of the field, and choosing "open link / drive source". You can also break the linkage by choosing "break link / drive", which will set the active link / drive / hook reference to null.
<languages />


== Links ==
{{Note|"FieldHook" and "Field hook" redirect here. For the ProtoFlux node, see [[ProtoFlux:Field Hook]]|information}}
Links are exclusive references to fields. There can only be a single thing linking a given target field at the same time. This is often used when systems need some sort of exclusive control over the target and make sure no other copy of that system will operate on it. Linked fields are highlighted blue in the [[Scene Inspector]].


== Drives ==
<translate>
Drives are an extension of links that on top of ensuring exclusive control also give the drive source control over the value of the driven field. This excludes the field from the implicit synchronization by the [[Data Model]], meanings its value gets locally computed by every client, and changes to it are not networked. Driven fields are highlighted purple in the [[Scene Inspector]].
'''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''.
</translate>


Drives are the fundamental building block that allows creating [[Local Systems]] (systems that aren't implicitly synchronized). By utilizing drives, fields can have different values for different users, which is required for things like culling systems to function. Drives can also be used to reduce  network impact of systems, by locally computing values on every client, instead of computing them on one client and implicitly synchronizing them to all other clients by writing them to a non-driven field on the [[Data Model]].
== <translate>Links</translate> ==


== Hooks ==
[[File:FieldLinkage LinkedFieldExample.webp|thumb|<translate>The <code>Target</code> field in this image is linked, as shown by it being cyan. This is due to it being a [[Type:FieldDrive`1|FieldDrive&lt;T&gt;]] type.</translate>]]
Hooks are an extension of drives that allow defining custom behavior for writing to a driven value. They do this by signaling any attempted write to the field, and returning what the value being written was. This allows systems to react to external changes, for example to create "writeback" behaviors. Just like normal drives, hooked fields are highlighted purple in the [[Scene Inspector]].


Components can have boolean values (often called write back or reverse mapping) that can switch the field hook behavior of the fields they drive. A couple of examples of the many components that can do this are [[Component:ValueCopy|ValueCopy]] and [[Component:LinearMapper1D|LinearMapper1D]]. For these kinds of components, they will allow sending data in the reverse direction when writing to the hooked value. For example, if 10 was written to the field hook's source value, and this causes the hooked value to become 20; Writing the value 20 to the hooked value will make the source automatically set to 10. This only works if the component has its write back switch enabled.
<translate>
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.
</translate>


This is useful for when you want to make 2 containers synchronize their capacity in terms of volume, or to synchronize sliders or visuals in a cross link fashion.
<translate>
Links are rarely used within the game and 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.
</translate>
 
== <translate>Drives</translate> ==
 
[[File:FieldLinkage DrivenFieldExample.webp|thumb|<translate>The <code>Rotation</code> field on the [[slot]] is driven by the [[Component:AutoLookAtUser|AutoLookAtUser]], as shown by it being purple.</translate>]]
 
<translate>
'''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.
</translate>
 
<translate>
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.
</translate>
 
<translate>
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.
</translate>
 
== <translate>Hooks</translate> ==
 
<translate>
'''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.
</translate>
 
=== <translate>WriteBack</translate> ===
 
<translate>
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.
</translate>
 
<translate>
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>

Revision as of 22:47, 25 April 2025

"FieldHook" and "Field hook" redirect here. For the ProtoFlux node, see ProtoFlux:Field Hook

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.

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

Links are rarely used within the game and 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 drive state of a field to be local. 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 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.

Fields 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, 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 Value Field Drive or Object Field Drive node to drive the value of a field.

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.

Hooks

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.

WriteBack

The most commonly-named hook that one might encounter is called WriteBack. 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.