Class NetworkTransform

A component to synchronize the position and rotation of networked objects.

The movement of game objects can be networked by this component. There are two models of authority for networked movement:

If the object has authority on the client, then it should be controlled locally on the owning client, then movement state information will be sent from the owning client to the server, then broadcast to all of the other clients. This is common for player objects.

If the object has authority on the server, then it should be controlled on the server and movement state information will be sent to all clients. This is common for objects not related to a specific client, such as an enemy unit.

Inheritance
object
Object
Component
Behaviour
MonoBehaviour
NetworkBehaviour
NetworkTransform
Inherited Members
Namespace: UnityEngine.Networking
Assembly: com.unity.multiplayer-hlapi.Runtime.dll
Syntax
[DisallowMultipleComponent]
[AddComponentMenu("Network/NetworkTransform")]
[Obsolete("The high level API classes are deprecated and will be removed in the future.")]
public class NetworkTransform : NetworkBehaviour

Properties

characterContoller

Cached CharacterController.

Declaration
public CharacterController characterContoller { get; }
Property Value
Type Description
CharacterController

clientMoveCallback2D

A callback that can be used to validate on the server, the movement of client authoritative objects.

This version of the callback works with objects that use 2D physics. The callback function may return false to reject the movement request completely. It may also modify the movement parameters - which are passed by reference.

The example below set the callback in OnStartServer, and will disconnect a client that moves an object into an invalid position after a number of failures.

using UnityEngine;
using UnityEngine.Networking;

public class MyMover : NetworkManager
{
public int cheatCount = 0;


public bool ValidateMove(ref Vector2 position, ref Vector2 velocity, ref float rotation)
{
Debug.Log("pos:" + position);
if (position.y > 9)
{
position.y = 9;
cheatCount += 1;
if (cheatCount == 10)
{
Invoke("DisconnectCheater", 0.1f);
}
}
return true;
}


void DisconnectCheater()
{
GetComponent<>().connectionToClient.Disconnect();
}


public override void OnStartServer()
{
GetComponent<>().clientMoveCallback2D = ValidateMove;
}
}
This kind of server-side movement validation should be used in conjunction with client side movement validation. The callback should only detect a failure if a client is by-passing client side movement checks - by cheating.
Declaration
public NetworkTransform.ClientMoveCallback2D clientMoveCallback2D { get; set; }
Property Value
Type Description
NetworkTransform.ClientMoveCallback2D

clientMoveCallback3D

A callback that can be used to validate on the server, the movement of client authoritative objects.

This version of the callback works with objects that use 3D physics. The callback function may return false to reject the movement request completely. It may also modify the movement parameters - which are passed by reference.

The example below set the callback in OnStartServer, and will disconnect a client that moves an object into an invalid position after a number of failures.

using UnityEngine;
using UnityEngine.Networking;

public class MyMover : NetworkManager
{
public int cheatCount = 0;


public bool ValidateMove(ref Vector3 position, ref Vector3 velocity, ref Quaternion rotation)
{
Debug.Log("pos:" + position);
if (position.y > 9)
{
position.y = 9;
cheatCount += 1;
if (cheatCount == 10)
{
Invoke("DisconnectCheater", 0.1f);
}
}
return true;
}


void DisconnectCheater()
{
GetComponent<>().connectionToClient.Disconnect();
}


public override void OnStartServer()
{
GetComponent<>().clientMoveCallback3D = ValidateMove;
}
}
This kind of server-side movement validation should be used in conjunction with client side movement validation. The callback should only detect a failure if a client is by-passing client side movement checks - by cheating.
Declaration
public NetworkTransform.ClientMoveCallback3D clientMoveCallback3D { get; set; }
Property Value
Type Description
NetworkTransform.ClientMoveCallback3D

grounded

Tells the NetworkTransform that it is on a surface (this is the default).

Object that are NOT grounded will not interpolate their vertical velocity. This avoid the problem of interpolation fighting with gravity on non-authoritative objects. This only works for RigidBody2D physics objects.

Declaration
public bool grounded { get; set; }
Property Value
Type Description
bool

interpolateMovement

Enables interpolation of the synchronized movement.

The larger this number is, the faster the object will interpolate to the target position.

Declaration
public float interpolateMovement { get; set; }
Property Value
Type Description
float

interpolateRotation

Enables interpolation of the synchronized rotation.

If this is not set, object will snap to the new rotation. The larger this number is, the faster the object will interpolate to the target facing direction.

Declaration
public float interpolateRotation { get; set; }
Property Value
Type Description
float

lastSyncTime

The most recent time when a movement synchronization packet arrived for this object.

Declaration
public float lastSyncTime { get; }
Property Value
Type Description
float

movementTheshold

The distance that an object can move without sending a movement synchronization update.

Declaration
public float movementTheshold { get; set; }
Property Value
Type Description
float

rigidbody2D

Cached Rigidbody2D.

Declaration
public Rigidbody2D rigidbody2D { get; }
Property Value
Type Description
Rigidbody2D

rigidbody3D

Cached Rigidbody.

Declaration
public Rigidbody rigidbody3D { get; }
Property Value
Type Description
Rigidbody

rotationSyncCompression

How much to compress rotation sync updates.

Declaration
public NetworkTransform.CompressionSyncMode rotationSyncCompression { get; set; }
Property Value
Type Description
NetworkTransform.CompressionSyncMode

sendInterval

The sendInterval controls how often state updates are sent for this object.

Unlike most NetworkBehaviour scripts, for NetworkTransform this is implemented at a per-object level rather than at the per-script level. This allows more flexibility as this component is used in various situation.

If sendInterval is non-zero, then transform state updates are send at most once every sendInterval seconds. However, if an object is stationary, no updates are sent.

If sendInterval is zero, then no automatic updates are sent. In this case, calling SetDirtyBits() on the NetworkTransform will cause an updates to be sent. This could be used for objects like bullets that have a predictable trajectory.

Declaration
public float sendInterval { get; set; }
Property Value
Type Description
float

snapThreshold

If a movement update puts an object further from its current position that this value, it will snap to the position instead of moving smoothly.

Declaration
public float snapThreshold { get; set; }
Property Value
Type Description
float

syncRotationAxis

Which axis should rotation by synchronized for.

Declaration
public NetworkTransform.AxisSyncMode syncRotationAxis { get; set; }
Property Value
Type Description
NetworkTransform.AxisSyncMode

syncSpin

Declaration
public bool syncSpin { get; set; }
Property Value
Type Description
bool

targetSyncPosition

The target position interpolating towards.

Declaration
public Vector3 targetSyncPosition { get; }
Property Value
Type Description
Vector3

targetSyncRotation2D

The target rotation interpolating towards.

Declaration
public float targetSyncRotation2D { get; }
Property Value
Type Description
float

targetSyncRotation3D

The target position interpolating towards.

Declaration
public Quaternion targetSyncRotation3D { get; }
Property Value
Type Description
Quaternion

targetSyncVelocity

The velocity send for synchronization.

Declaration
public Vector3 targetSyncVelocity { get; }
Property Value
Type Description
Vector3

transformSyncMode

What method to use to sync the object's position.

Declaration
public NetworkTransform.TransformSyncMode transformSyncMode { get; set; }
Property Value
Type Description
NetworkTransform.TransformSyncMode

velocityThreshold

The minimum velocity difference that will be synchronized over the network.

Declaration
public float velocityThreshold { get; set; }
Property Value
Type Description
float

Methods

GetNetworkChannel()

This virtual function is used to specify the QoS channel to use for SyncVar updates for this script.

Using the NetworkSettings custom attribute causes this function to be implemented for this script, but developers can also implement it themselves.

Declaration
public override int GetNetworkChannel()
Returns
Type Description
int

The QoS channel for this script.
Overrides

GetNetworkSendInterval()

This virtual function is used to specify the send interval to use for SyncVar updates for this script.

Using the NetworkSettings custom attribute causes this function to be implemented for this script, but developers can also implement it themselves.

Declaration
public override float GetNetworkSendInterval()
Returns
Type Description
float

The time in seconds between updates.
Overrides

HandleTransform(NetworkMessage)

Declaration
public static void HandleTransform(NetworkMessage netMsg)
Parameters
Type Name Description
NetworkMessage netMsg

OnDeserialize(NetworkReader, bool)

Virtual function to override to receive custom serialization data. The corresponding function to send serialization data is OnSerialize().

Declaration
public override void OnDeserialize(NetworkReader reader, bool initialState)
Parameters
Type Name Description
NetworkReader reader

Reader to read from the stream.
bool initialState

True if being sent initial state.
Overrides

OnSerialize(NetworkWriter, bool)

Virtual function to override to send custom serialization data. The corresponding function to send serialization data is OnDeserialize().

The initialState flag is useful to differentiate between the first time an object is serialized and when incremental updates can be sent. The first time an object is sent to a client, it must include a full state snapshot, but subsequent updates can save on bandwidth by including only incremental changes. Note that SyncVar hook functions are not called when initialState is true, only for incremental updates.

If a class has SyncVars, then an implementation of this function and OnDeserialize() are added automatically to the class. So a class that has SyncVars cannot also have custom serialization functions.

The OnSerialize function should return true to indicate that an update should be sent. If it returns true, then the dirty bits for that script are set to zero, if it returns false then the dirty bits are not changed. This allows multiple changes to a script to be accumulated over time and sent when the system is ready, instead of every frame.

Declaration
public override bool OnSerialize(NetworkWriter writer, bool initialState)
Parameters
Type Name Description
NetworkWriter writer

Writer to use to write to the stream.
bool initialState

If this is being called to send initial state.
Returns
Type Description
bool

True if data was written.
Overrides

OnStartAuthority()

Declaration
public override void OnStartAuthority()
Overrides

OnStartServer()

This is invoked for NetworkBehaviour objects when they become active on the server.

This could be triggered by NetworkServer.Listen() for objects in the scene, or by NetworkServer.Spawn() for objects that are dynamically created.

This will be called for objects on a "host" as well as for object on a dedicated server.

Declaration
public override void OnStartServer()
Overrides

SerializeRotation2D(NetworkWriter, float, CompressionSyncMode)

Declaration
public static void SerializeRotation2D(NetworkWriter writer, float rot, NetworkTransform.CompressionSyncMode compression)
Parameters
Type Name Description
NetworkWriter writer
float rot
NetworkTransform.CompressionSyncMode compression

SerializeRotation3D(NetworkWriter, Quaternion, AxisSyncMode, CompressionSyncMode)

Declaration
public static void SerializeRotation3D(NetworkWriter writer, Quaternion rot, NetworkTransform.AxisSyncMode mode, NetworkTransform.CompressionSyncMode compression)
Parameters
Type Name Description
NetworkWriter writer
Quaternion rot
NetworkTransform.AxisSyncMode mode
NetworkTransform.CompressionSyncMode compression

SerializeSpin2D(NetworkWriter, float, CompressionSyncMode)

Declaration
public static void SerializeSpin2D(NetworkWriter writer, float angularVelocity, NetworkTransform.CompressionSyncMode compression)
Parameters
Type Name Description
NetworkWriter writer
float angularVelocity
NetworkTransform.CompressionSyncMode compression

SerializeSpin3D(NetworkWriter, Vector3, AxisSyncMode, CompressionSyncMode)

Declaration
public static void SerializeSpin3D(NetworkWriter writer, Vector3 angularVelocity, NetworkTransform.AxisSyncMode mode, NetworkTransform.CompressionSyncMode compression)
Parameters
Type Name Description
NetworkWriter writer
Vector3 angularVelocity
NetworkTransform.AxisSyncMode mode
NetworkTransform.CompressionSyncMode compression

SerializeVelocity2D(NetworkWriter, Vector2, CompressionSyncMode)

Declaration
public static void SerializeVelocity2D(NetworkWriter writer, Vector2 velocity, NetworkTransform.CompressionSyncMode compression)
Parameters
Type Name Description
NetworkWriter writer
Vector2 velocity
NetworkTransform.CompressionSyncMode compression

SerializeVelocity3D(NetworkWriter, Vector3, CompressionSyncMode)

Declaration
public static void SerializeVelocity3D(NetworkWriter writer, Vector3 velocity, NetworkTransform.CompressionSyncMode compression)
Parameters
Type Name Description
NetworkWriter writer
Vector3 velocity
NetworkTransform.CompressionSyncMode compression

UnserializeRotation2D(NetworkReader, CompressionSyncMode)

Declaration
public static float UnserializeRotation2D(NetworkReader reader, NetworkTransform.CompressionSyncMode compression)
Parameters
Type Name Description
NetworkReader reader
NetworkTransform.CompressionSyncMode compression
Returns
Type Description
float

UnserializeRotation3D(NetworkReader, AxisSyncMode, CompressionSyncMode)

Declaration
public static Quaternion UnserializeRotation3D(NetworkReader reader, NetworkTransform.AxisSyncMode mode, NetworkTransform.CompressionSyncMode compression)
Parameters
Type Name Description
NetworkReader reader
NetworkTransform.AxisSyncMode mode
NetworkTransform.CompressionSyncMode compression
Returns
Type Description
Quaternion

UnserializeSpin2D(NetworkReader, CompressionSyncMode)

Declaration
public static float UnserializeSpin2D(NetworkReader reader, NetworkTransform.CompressionSyncMode compression)
Parameters
Type Name Description
NetworkReader reader
NetworkTransform.CompressionSyncMode compression
Returns
Type Description
float

UnserializeSpin3D(NetworkReader, AxisSyncMode, CompressionSyncMode)

Declaration
public static Vector3 UnserializeSpin3D(NetworkReader reader, NetworkTransform.AxisSyncMode mode, NetworkTransform.CompressionSyncMode compression)
Parameters
Type Name Description
NetworkReader reader
NetworkTransform.AxisSyncMode mode
NetworkTransform.CompressionSyncMode compression
Returns
Type Description
Vector3

UnserializeVelocity2D(NetworkReader, CompressionSyncMode)

Declaration
public static Vector3 UnserializeVelocity2D(NetworkReader reader, NetworkTransform.CompressionSyncMode compression)
Parameters
Type Name Description
NetworkReader reader
NetworkTransform.CompressionSyncMode compression
Returns
Type Description
Vector3

UnserializeVelocity3D(NetworkReader, CompressionSyncMode)

Declaration
public static Vector3 UnserializeVelocity3D(NetworkReader reader, NetworkTransform.CompressionSyncMode compression)
Parameters
Type Name Description
NetworkReader reader
NetworkTransform.CompressionSyncMode compression
Returns
Type Description
Vector3