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