Linkage

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.