Class NetworkTransform

A component for syncing transforms. NetworkTransform will read the underlying transform and replicate it to clients. The replicated value will be automatically be interpolated (if active) and applied to the underlying GameObject's transform.

Inheritance
Object
Object
Component
Behaviour
MonoBehaviour
NetworkBehaviour
NetworkTransform
NetworkTransformTestComponent
TransformInterpolationObject
Inherited Members
Namespace: Unity.Netcode.Components
Syntax
[DisallowMultipleComponent]
[AddComponentMenu("Netcode/Network Transform")]
[DefaultExecutionOrder(100000)]
public class NetworkTransform : NetworkBehaviour

Fields

InLocalSpace

Sets whether the transform should be treated as local (true) or world (false) space.

Declaration
[Tooltip("Sets whether this transform should sync in local space or in world space")]
public bool InLocalSpace
Field Value
Type Description
Boolean
Remarks

This is synchronized by authority. During runtime, this should only be changed by the authoritative side. Non-authoritative instances will be overridden by the next authoritative state update.

Interpolate

When enabled (default) interpolation is applied. When disabled interpolation is disabled.

Declaration
public bool Interpolate
Field Value
Type Description
Boolean
Remarks

This is synchronized by authority and changes to interpolation during runtime forces a teleport/full update. During runtime, this should only be changed by the authoritative side. Non-authoritative instances will be overridden by the next authoritative state update.

m_CachedIsServer

Internally used by NetworkTransform to keep track of whether this NetworkBehaviour derived class instance was instantiated on the server side or not.

Declaration
protected bool m_CachedIsServer
Field Value
Type Description
Boolean

m_CachedNetworkManager

Internally used by NetworkTransform to keep track of the NetworkManager instance assigned to this this NetworkBehaviour derived class instance.

Declaration
protected NetworkManager m_CachedNetworkManager
Field Value
Type Description
NetworkManager

OnClientRequestChange

The handler that gets invoked when server receives a change from a client. This handler would be useful for server to modify pos/rot/scale before applying client's request.

Declaration
public NetworkTransform.OnClientRequestChangeDelegate OnClientRequestChange
Field Value
Type Description
NetworkTransform.OnClientRequestChangeDelegate

PositionThreshold

The position threshold value that triggers a delta state update by the authoritative instance.

Declaration
public float PositionThreshold
Field Value
Type Description
Single
Remarks

Note: setting this to zero will update position every network tick whether it changed or not.

PositionThresholdDefault

The default position change threshold value. Any changes above this threshold will be replicated.

Declaration
public const float PositionThresholdDefault = 0.001F
Field Value
Type Description
Single

RotAngleThreshold

The rotation threshold value that triggers a delta state update by the authoritative instance.

Declaration
[Range(1E-05F, 360F)]
public float RotAngleThreshold
Field Value
Type Description
Single
Remarks

Minimum Value: 0.00001 Maximum Value: 360.0

RotAngleThresholdDefault

The default rotation angle change threshold value. Any changes above this threshold will be replicated.

Declaration
public const float RotAngleThresholdDefault = 0.01F
Field Value
Type Description
Single

ScaleThreshold

The scale threshold value that triggers a delta state update by the authoritative instance.

Declaration
public float ScaleThreshold
Field Value
Type Description
Single
Remarks

Note: setting this to zero will update position every network tick whether it changed or not.

ScaleThresholdDefault

The default scale change threshold value. Any changes above this threshold will be replicated.

Declaration
public const float ScaleThresholdDefault = 0.01F
Field Value
Type Description
Single

SlerpPosition

When true and interpolation is enabled, this will Slerp to the target position.

Declaration
[Tooltip("When enabled the position interpolator will Slerp towards its current target position.")]
public bool SlerpPosition
Field Value
Type Description
Boolean
Remarks

This is synchronized by authority and only applies to position interpolation. During runtime, this should only be changed by the authoritative side. Non-authoritative instances will be overridden by the next authoritative state update.

SyncPositionX

When enabled (default), the x component of position will be synchronized by authority.

Declaration
public bool SyncPositionX
Field Value
Type Description
Boolean
Remarks

Changes to this on non-authoritative instances has no effect.

SyncPositionY

When enabled (default), the y component of position will be synchronized by authority.

Declaration
public bool SyncPositionY
Field Value
Type Description
Boolean
Remarks

Changes to this on non-authoritative instances has no effect.

SyncPositionZ

When enabled (default), the z component of position will be synchronized by authority.

Declaration
public bool SyncPositionZ
Field Value
Type Description
Boolean
Remarks

Changes to this on non-authoritative instances has no effect.

SyncRotAngleX

When enabled (default), the x component of rotation will be synchronized by authority.

Declaration
public bool SyncRotAngleX
Field Value
Type Description
Boolean
Remarks

When UseQuaternionSynchronization is enabled this does not apply. Changes to this on non-authoritative instances has no effect.

SyncRotAngleY

When enabled (default), the y component of rotation will be synchronized by authority.

Declaration
public bool SyncRotAngleY
Field Value
Type Description
Boolean
Remarks

When UseQuaternionSynchronization is enabled this does not apply. Changes to this on non-authoritative instances has no effect.

SyncRotAngleZ

When enabled (default), the z component of rotation will be synchronized by authority.

Declaration
public bool SyncRotAngleZ
Field Value
Type Description
Boolean
Remarks

When UseQuaternionSynchronization is enabled this does not apply. Changes to this on non-authoritative instances has no effect.

SyncScaleX

When enabled (default), the x component of scale will be synchronized by authority.

Declaration
public bool SyncScaleX
Field Value
Type Description
Boolean
Remarks

Changes to this on non-authoritative instances has no effect.

SyncScaleY

When enabled (default), the y component of scale will be synchronized by authority.

Declaration
public bool SyncScaleY
Field Value
Type Description
Boolean
Remarks

Changes to this on non-authoritative instances has no effect.

SyncScaleZ

When enabled (default), the z component of scale will be synchronized by authority.

Declaration
public bool SyncScaleZ
Field Value
Type Description
Boolean
Remarks

Changes to this on non-authoritative instances has no effect.

UseHalfFloatPrecision

Enable this to use half float precision for position, rotation, and scale. When enabled, delta position synchronization is used.

Declaration
[Tooltip("When enabled, this will use half float precision values for position (uses delta position updating), rotation (except when Quaternion compression is enabled), and scale.")]
public bool UseHalfFloatPrecision
Field Value
Type Description
Boolean
Remarks

This is synchronized by authority. During runtime, this should only be changed by the authoritative side. Non-authoritative instances will be overridden by the next authoritative state update.

UseQuaternionCompression

Enabled this on the authority side for quaternion compression

Declaration
[Tooltip("When enabled, this uses a smallest three implementation that reduces full Quaternion updates down to the size of an unsigned integer (ignores half float precision settings).")]
public bool UseQuaternionCompression
Field Value
Type Description
Boolean
Remarks

This has a lower precision than half float precision. Recommended only for low precision scenarios. UseHalfFloatPrecision provides better precision at roughly half the cost of a full quaternion update. This is synchronized by authority. During runtime, this should only be changed by the authoritative side. Non-authoritative instances will be overridden by the next authoritative state update.

UseQuaternionSynchronization

Enable this on the authority side for quaternion synchronization

Declaration
[Tooltip("When enabled, this will synchronize the full Quaternion (i.e. all Euler rotation axis are updated if one axis has a delta)")]
public bool UseQuaternionSynchronization
Field Value
Type Description
Boolean
Remarks

This is synchronized by authority. During runtime, this should only be changed by the authoritative side. Non-authoritative instances will be overridden by the next authoritative state update.

Properties

CanCommitToTransform

Used to determine who can write to this transform. Server only for this transform. Changing this value alone in a child implementation will not allow you to create a NetworkTransform which can be written to by clients. See the ClientNetworkTransform Sample in the package samples for how to implement a NetworkTransform with client write support. If using different values, please use RPCs to write to the server. Netcode doesn't support client side network variable writing

Declaration
public bool CanCommitToTransform { get; protected set; }
Property Value
Type Description
Boolean

Methods

Awake()

Create interpolators when first instantiated to avoid memory allocations if the associated NetworkObject persists (i.e. despawned but not destroyed or pools)

Declaration
protected virtual void Awake()

GetScale(Boolean)

Helper method that returns the scale of the transform.

Declaration
public Vector3 GetScale(bool getCurrentState = false)
Parameters
Type Name Description
Boolean getCurrentState

Authority always returns the space relative transform scale (whether true or false). Non-authority: When false (default): returns the space relative transform scale When true: returns the authority scale from the most recent state update.
Returns
Type Description
Vector3 Vector3
Remarks

When invoked on the non-authority side: If is true then it will return the most current authority scale from the most recent state update. This can be useful if interpolation is enabled and you need to determine the final target scale. When invoked on the authority side: It will always return the space relative scale.

GetSpaceRelativePosition(Boolean)

Helper method that returns the space relative position of the transform.

Declaration
public Vector3 GetSpaceRelativePosition(bool getCurrentState = false)
Parameters
Type Name Description
Boolean getCurrentState

Authority always returns the space relative transform position (whether true or false). Non-authority: When false (default): returns the space relative transform position When true: returns the authority position from the most recent state update.
Returns
Type Description
Vector3 Vector3
Remarks

If InLocalSpace is then it returns the transform.localPosition If InLocalSpace is then it returns the transform.position When invoked on the non-authority side: If is true then it will return the most current authority position from the most recent state update. This can be useful if interpolation is enabled and you need to determine the final target position. When invoked on the authority side: It will always return the space relative position.

GetSpaceRelativeRotation(Boolean)

Helper method that returns the space relative rotation of the transform.

Declaration
public Quaternion GetSpaceRelativeRotation(bool getCurrentState = false)
Parameters
Type Name Description
Boolean getCurrentState

Authority always returns the space relative transform rotation (whether true or false). Non-authority: When false (default): returns the space relative transform rotation When true: returns the authority rotation from the most recent state update.
Returns
Type Description
Quaternion Quaternion
Remarks

If InLocalSpace is then it returns the transform.localRotation If InLocalSpace is then it returns the transform.rotation When invoked on the non-authority side: If is true then it will return the most current authority rotation from the most recent state update. This can be useful if interpolation is enabled and you need to determine the final target rotation. When invoked on the authority side: It will always return the space relative rotation.

Initialize()

Initializes NetworkTransform when spawned and ownership changes.

Declaration
protected void Initialize()

IsServerAuthoritative()

Method to determine if this NetworkTransform instance is owner or server authoritative.

Declaration
public bool IsServerAuthoritative()
Returns
Type Description
Boolean or
Remarks

Used by to determines if this is server or owner authoritative.

OnAuthorityPushTransformState(ref NetworkTransform.NetworkTransformState)

Invoked just prior to being pushed to non-authority instances.

Declaration
protected virtual void OnAuthorityPushTransformState(ref NetworkTransform.NetworkTransformState networkTransformState)
Parameters
Type Name Description
NetworkTransform.NetworkTransformState networkTransformState

the state being pushed
Remarks

This is useful to know the exact position, rotation, or scale values sent to non-authoritative instances. This is only invoked on the authoritative instance.

OnDestroy()

Invoked when the GameObject the NetworkBehaviour is attached to. NOTE: If you override this, you will want to always invoke this base class version of this OnDestroy() method!!

Declaration
public override void OnDestroy()
Overrides

OnGainedOwnership()

Gets called when the local client gains ownership of this object

Declaration
public override void OnGainedOwnership()
Overrides

OnInitialize(ref NetworkVariable<NetworkTransform.NetworkTransformState>)

Invoked when first spawned and when ownership changes.

Declaration
protected virtual void OnInitialize(ref NetworkVariable<NetworkTransform.NetworkTransformState> replicatedState)
Parameters
Type Name Description
NetworkVariable<NetworkTransform.NetworkTransformState> replicatedState

the NetworkVariable<T> replicated NetworkTransform.NetworkTransformState

OnIsServerAuthoritative()

Override this method and return false to switch to owner authoritative mode

Declaration
protected virtual bool OnIsServerAuthoritative()
Returns
Type Description
Boolean

( or ) where when false it runs as owner-client authoritative

OnLostOwnership()

Gets called when we loose ownership of this object

Declaration
public override void OnLostOwnership()
Overrides

OnNetworkDespawn()

Gets called when the NetworkObject gets despawned. Is called both on the server and clients.

Declaration
public override void OnNetworkDespawn()
Overrides

OnNetworkSpawn()

Gets called when the NetworkObject gets spawned, message handlers are ready to be registered and the network is setup.

Declaration
public override void OnNetworkSpawn()
Overrides

OnNetworkTransformStateUpdated(ref NetworkTransform.NetworkTransformState, ref NetworkTransform.NetworkTransformState)

Invoked on the non-authoritative side when the NetworkTransformState has been updated

Declaration
protected virtual void OnNetworkTransformStateUpdated(ref NetworkTransform.NetworkTransformState oldState, ref NetworkTransform.NetworkTransformState newState)
Parameters
Type Name Description
NetworkTransform.NetworkTransformState oldState

the previous NetworkTransform.NetworkTransformState
NetworkTransform.NetworkTransformState newState

the new NetworkTransform.NetworkTransformState

OnSynchronize<T>(ref BufferSerializer<T>)

This is invoked when a new client joins (server and client sides) Server Side: Serializes as if we were teleporting (everything is sent via NetworkTransformState) Client Side: Adds the interpolated state which applies the NetworkTransformState as well

Declaration
protected override void OnSynchronize<T>(ref BufferSerializer<T> serializer)
    where T : IReaderWriter
Parameters
Type Name Description
BufferSerializer<T> serializer
Type Parameters
Name Description
T
Overrides
Unity.Netcode.NetworkBehaviour.OnSynchronize<T>(Unity.Netcode.BufferSerializer<T>)
Remarks

If a derived class overrides this, then make sure to invoke this base method!

SetMaxInterpolationBound(Single)

Will set the maximum interpolation boundary for the interpolators of this NetworkTransform instance. This value roughly translates to the maximum value of 't' in Lerp and Lerp for all transform elements being monitored by NetworkTransform (i.e. Position, Scale, and Rotation)

Declaration
public void SetMaxInterpolationBound(float maxInterpolationBound)
Parameters
Type Name Description
Single maxInterpolationBound

Maximum time boundary that can be used in a frame when interpolating between two values

SetState(Nullable<Vector3>, Nullable<Quaternion>, Nullable<Vector3>, Boolean)

Directly sets a state on the authoritative transform. Owner clients can directly set the state on a server authoritative transform This will override any changes made previously to the transform This isn't resistant to network jitter. Server side changes due to this method won't be interpolated. The parameters are broken up into pos / rot / scale on purpose so that the caller can perturb just the desired one(s)

Declaration
public void SetState(Vector3? posIn = null, Quaternion? rotIn = null, Vector3? scaleIn = null, bool teleportDisabled = true)
Parameters
Type Name Description
Nullable<Vector3> posIn
Nullable<Quaternion> rotIn
Nullable<Vector3> scaleIn

new scale to scale to. Can be null
Boolean teleportDisabled

When true (the default) the NetworkObject will not be teleported and, if enabled, will interpolate. When false the NetworkObject will teleport/apply the parameters provided immediately.
Exceptions
Type Condition
Exception

Teleport(Vector3, Quaternion, Vector3)

Teleport the transform to the given values without interpolating

Declaration
public void Teleport(Vector3 newPosition, Quaternion newRotation, Vector3 newScale)
Parameters
Type Name Description
Vector3 newPosition
Quaternion newRotation
Vector3 newScale

new scale to scale to.
Exceptions
Type Condition
Exception

TryCommitTransformToServer(Transform, Double)

This will try to send/commit the current transform delta states (if any)

Declaration
protected void TryCommitTransformToServer(Transform transformToCommit, double dirtyTime)
Parameters
Type Name Description
Transform transformToCommit

the transform to be committed
Double dirtyTime

time it was marked dirty
Remarks

Only client owners or the server should invoke this method

Update()

Declaration
protected virtual void Update()
Remarks

If you override this method, be sure that:

  • Non-authority always invokes this base class method.