Class AnticipatedNetworkVariable<T>

A variable that can be synchronized over the network. This version supports basic client anticipation - the client can set a value on the belief that the server will update it to reflect the same value in a future update (i.e., as the result of an RPC call). This value can then be adjusted as new updates from the server come in, in three basic modes:

  • Snap: In this mode (with StaleDataHandling set to Ignore and no OnReanticipate(double) callback), the moment a more up-to-date value is received from the authority, it will simply replace the anticipated value, resulting in a "snap" to the new value if it is different from the anticipated value.
  • Smooth: In this mode (with StaleDataHandling set to Ignore and an OnReanticipate(double) callback that calls Smooth(in T, in T, float, SmoothDelegate) from the anticipated value to the authority value with an appropriate Lerp(float, float, float)-style smooth function), when a more up-to-date value is received from the authority, it will interpolate over time from an incorrect anticipated value to the correct authoritative value.
  • Constant Reanticipation: In this mode (with StaleDataHandling set to Reanticipate and an OnReanticipate(double) that calculates a new anticipated value based on the current authoritative value), when a more up-to-date value is received from the authority, user code calculates a new anticipated value, possibly calling Smooth(in T, in T, float, SmoothDelegate) to interpolate between the previous anticipation and the new anticipation. This is useful for values that change frequently and need to constantly be re-evaluated, as opposed to values that change only in response to user action and simply need a one-time anticipation when the user performs that action.

Note that these three modes may be combined. For example, if an OnReanticipate(double) callback does not call either Smooth(in T, in T, float, SmoothDelegate) or Anticipate(T), the result will be a snap to the authoritative value, enabling for a callback that may conditionally call Smooth(in T, in T, float, SmoothDelegate) when the difference between the anticipated and authoritative values is within some threshold, but fall back to snap behavior if the difference is too large.

Inheritance
object
NetworkVariableBase
AnticipatedNetworkVariable<T>
Implements
Inherited Members
Namespace: Unity.Netcode
Assembly: Unity.Netcode.Runtime.dll
Syntax
[Serializable]
[GenerateSerializationForGenericParameter(0)]
public class AnticipatedNetworkVariable<T> : NetworkVariableBase, IDisposable
Type Parameters
Name Description
T

the unmanaged type for NetworkVariable<T>

Constructors

AnticipatedNetworkVariable(T, StaleDataHandling)

Declaration
public AnticipatedNetworkVariable(T value = default, StaleDataHandling staleDataHandling = StaleDataHandling.Ignore)
Parameters
Type Name Description
T value
StaleDataHandling staleDataHandling

Fields

OnAuthoritativeValueChanged

Invoked any time the authoritative value changes, even when the data is stale or has been changed locally.

Declaration
public AnticipatedNetworkVariable<T>.OnAuthoritativeValueChangedDelegate OnAuthoritativeValueChanged
Field Value
Type Description
AnticipatedNetworkVariable<T>.OnAuthoritativeValueChangedDelegate

StaleDataHandling

Defines what the behavior should be if we receive a value from the server with an earlier associated time value than the anticipation time value.

If this is Ignore, the stale data will be ignored and the authoritative value will not replace the anticipated value until the anticipation time is reached. OnAuthoritativeValueChanged and OnReanticipate(double) will also not be invoked for this stale data.

If this is Reanticipate, the stale data will replace the anticipated data and OnAuthoritativeValueChanged and OnReanticipate(double) will be invoked. In this case, the authoritativeTime value passed to OnReanticipate(double) will be lower than the anticipationTime value, and that callback can be used to calculate a new anticipated value.

Declaration
public StaleDataHandling StaleDataHandling
Field Value
Type Description
StaleDataHandling

Properties

AuthoritativeValue

Retrieves or sets the underlying authoritative value. Note that only a client or server with write permissions to this variable may set this value. When this variable has been anticipated, this value will alawys return the most recent authoritative state, which is updated even if StaleDataHandling is Ignore.

Declaration
public T AuthoritativeValue { get; set; }
Property Value
Type Description
T

PreviousAnticipatedValue

Holds the most recent anticipated value, whatever was most recently set using Anticipate(T). Unlike Value, this does not get overwritten when a server update arrives.

Declaration
public T PreviousAnticipatedValue { get; }
Property Value
Type Description
T

ShouldReanticipate

Indicates whether this variable currently needs reanticipation. If this is true, the anticipated value has been overwritten by the authoritative value from the server; the previous anticipated value is stored in PreviousAnticipatedState

Declaration
public bool ShouldReanticipate { get; }
Property Value
Type Description
bool

Value

Retrieves the current value for the variable. This is the "display value" for this variable, and is affected by Anticipate(T) and Smooth(in T, in T, float, SmoothDelegate), as well as by updates from the authority, depending on StaleDataHandling and the behavior of any OnReanticipate(double) callbacks.

When a server update arrives, this value will be overwritten by the new server value (unless stale data handling is set to "Ignore" and the update is determined to be stale). This value will be duplicated in PreviousAnticipatedValue, which will NOT be overwritten in server updates.

Declaration
public T Value { get; }
Property Value
Type Description
T

Methods

Anticipate(T)

Sets the current value of the variable on the expectation that the authority will set the variable to the same value within one network round trip (i.e., in response to an RPC).

Declaration
public void Anticipate(T value)
Parameters
Type Name Description
T value

Dispose()

Virtual IDisposable implementation

Declaration
public override void Dispose()
Overrides

ExceedsDirtinessThreshold()

Check whether or not this variable has changed significantly enough to send an update. If not, no update will be sent even if the variable is dirty, unless the time since last update exceeds the UpdateTraits' MaxSecondsBetweenUpdates.

Declaration
public override bool ExceedsDirtinessThreshold()
Returns
Type Description
bool
Overrides

~AnticipatedNetworkVariable()

Declaration
protected ~AnticipatedNetworkVariable()

IsDirty()

Gets Whether or not the container is dirty

Declaration
public override bool IsDirty()
Returns
Type Description
bool

Whether or not the container is dirty
Overrides

OnInitialize()

Called on initialization

Declaration
public override void OnInitialize()
Overrides

ReadDelta(FastBufferReader, bool)

Reads delta from the reader and applies them to the internal value

Declaration
public override void ReadDelta(FastBufferReader reader, bool keepDirtyDelta)
Parameters
Type Name Description
FastBufferReader reader

The stream to read the delta from
bool keepDirtyDelta

Whether or not the delta should be kept as dirty or consumed
Overrides

ReadField(FastBufferReader)

Reads the complete state from the reader and applies it

Declaration
public override void ReadField(FastBufferReader reader)
Parameters
Type Name Description
FastBufferReader reader

The stream to read the state from
Overrides

ResetDirty()

Resets the dirty state and marks the variable as synced / clean

Declaration
public override void ResetDirty()
Overrides

Smooth(in T, in T, float, SmoothDelegate)

Interpolate this variable from from to to over durationSeconds of real time. The duration uses deltaTime, so it is affected by timeScale.

Declaration
public void Smooth(in T from, in T to, float durationSeconds, AnticipatedNetworkVariable<T>.SmoothDelegate how)
Parameters
Type Name Description
T from
T to
float durationSeconds
AnticipatedNetworkVariable<T>.SmoothDelegate how

Update()

Declaration
public void Update()

WriteDelta(FastBufferWriter)

Writes the dirty changes, that is, the changes since the variable was last dirty, to the writer

Declaration
public override void WriteDelta(FastBufferWriter writer)
Parameters
Type Name Description
FastBufferWriter writer

The stream to write the dirty changes to
Overrides

WriteField(FastBufferWriter)

Writes the complete state of the variable to the writer

Declaration
public override void WriteField(FastBufferWriter writer)
Parameters
Type Name Description
FastBufferWriter writer

The stream to write the state to
Overrides

Events

CheckExceedsDirtinessThreshold

Determines if the difference between the last serialized value and the current value is large enough to serialize it again.

Declaration
public event NetworkVariable<T>.CheckExceedsDirtinessThresholdDelegate CheckExceedsDirtinessThreshold
Event Type
Type Description
NetworkVariable<T>.CheckExceedsDirtinessThresholdDelegate

Implements