Creating Custom Behaviours

To implement the logic of your project, you'll need to implement your own NetworkBehaviours. Below you can find the basic structure of a NetworkBehaviour and its components:

public class CustomNetworkBehaviour : NetworkBehaviour
{
    //My Fields
    public float walkSpeed = 3f;

    //My Network Values
    public IntNetworkValue team = new IntNetworkValue(0);

    //Unity callbacks
    public void OnEnable(){}

    //Network callbacks
    public override void OnSpawned(bool isRetroactive){}
}

Tip

A NetworkBehaviour works exactly like a normal MonoBehaviour while also providing state synchronization over the network.

Warning

It's not possible to remove and/or add a NetworkBehaviour in real-time.

Custom Serialization

If your NetworkBehaviour has a state that's too complex to synchronize using only NetworkValue, you can use custom serialization. Simply implement the INetworkBehaviourSerializer interface in your NetworkBehaviour:

public class CustomNetworkBehaviour : NetworkBehaviour, INetworkBehaviourSerializer
{
    public float[] valueTooComplex = new float[0];

    public void OnSerialize(BinaryWriter writer, bool forceSendAll)
    {
        writer.Write(valueTooComplex.Length);
        for (var i = 0; i < valueTooComplex.Length; i++)
        {
            writer.Write(valueTooComplex[i]);
        }   
    }

    public void OnDeserialize(BinaryReader reader)
    {
        var length = reader.ReadInt32();
        valueTooComplex = new float[length];
        for (var i = 0; i < length; i++)
        {
            valueTooComplex[i] = reader.ReadSingle();
        }
    }
}

By doing this, all data will be synchronized over the network (even if someone connects later). If the data is too complex (like that of NetworkTransform), you can implement a system to update only the necessary data, and when the forceSendAll parameter is true, all data must be synchronized. This parameter will only be true when a client connects later.

Warning

These values are not re-updated automatically. You should use the NetworkBehaviour.MarkSerializerDirty method to trigger serialization and, consequently, deserialization (with forceSendAll = false).

Custom Packets

The third (and most optimized) method to synchronize custom data is by creating packets. Internally, both of the other two methods use packets to synchronize data, and even the basic functioning of the network is based on packets.

The packet-based system was chosen as the main transfer method for NetBuff because it's lightweight, fast, and highly customizable. To create a custom packet, you need to create a class that implements the IPacket or IOwnedPacket interface:

public class PlayerPunchActionPacket : IPacket
{
    public NetworkId Id { get; set; }

    public void Serialize(BinaryWriter writer)
    {
        Id.Serialize(writer);
    }

    public void Deserialize(BinaryReader reader)
    {
        Id = NetworkId.Read(reader);
    }
}

public class PacketBodyRotation : IOwnedPacket
{
    public NetworkId Id { get; set; }
    public float BodyRotation { get; set; }

    public void Serialize(BinaryWriter writer)
    {
        Id.Serialize(writer);
        writer.Write(BodyRotation);
    }

    public void Deserialize(BinaryReader reader)
    {
        Id = NetworkId.Read(reader);
        BodyRotation = reader.ReadSingle();
    }
}

A IOwnedPacket is an IPacket that is directly linked to a NetworkIdentity, therefore, they will be internally sent by a NetworkBehaviour, and the server will find the same NetworkBehaviour in other network points and call the receiving callback.

A normal IPacket is not directly linked to anything, so they will simply be sent over the network, and all handling must be done manually.

Sending Packets

To send a packet, simply use the NetworkBehaviour.SendPacket method, which will send the packet using the correct method automatically:

var packet = new PacketBodyRotation
{
    Id = Id,
    BodyRotation = body.localEulerAngles.y
};
SendPacket(packet);

Internally, the system automatically chooses between the NetworkBehaviour.ClientSendPacket and NetworkBehaviour.ServerBroadcastPacket methods depending on whether the local environment is a client or server:

if (IsOwnedByClient)
    ClientSendPacket(packet, reliable); //Client sends a message to the server
else
    ServerBroadcastPacket(packet, reliable); //Server broadcast a message to all the clients

The server can also use the NetworkBehaviour.ServerSendPacket method to send a packet to a single client or the NetworkBehaviour.ServerBroadcastPacketExceptFor method to send to all clients except one.

Receiving Owned Packets

To receive IOwnedPackets, you can use the NetworkBehaviour.OnServerReceivePacket and NetworkBehaviour.OnClientReceivePacket callbacks:

public class PlayerController : NetworkBehaviour
{
    //Server received the packet, check the ownership (optional) then broadcasts it to everyone else than the origin client
    public override void OnServerReceivePacket(IOwnedPacket packet, int clientId)
    {
        switch (packet)
        {
            case PacketBodyRotation data:
                if(clientId == OwnerId)
                    ServerBroadcastPacketExceptFor(data, clientId);
                break;
        }
    }


    //Client received the packet, then applied it to the transform itself
    public override void OnClientReceivePacket(IOwnedPacket packet)
    {
        switch (packet)
        {
            case PacketBodyRotation bodyRot:
                transform.eulerAngles = new Vector3(0, bodyRot.BodyRotation, 0);
                break;
        }
    }
}

Note

Only the object with the IOwnedPacket.Id will receive the callbacks, so you don't need to worry about checking the id manually!

Receiving Not Owned

If a packet is not owned, you can register a custom listener for it anywhere in the project. In the example below, the Lever class is listening for PlayerPunchActionPacket, which is a packet sent by the PlayerController class:

public class Lever : NetworkBehaviour
{
    public BoolNetworkValue isOn = new(false);
    public float radius = 2f;

    private void OnEnable()
    {
        WithValues(isOn);
        PacketListener.GetPacketListener<PlayerPunchActionPacket>().AddServerListener(OnPlayerPunch);
        //PacketListener.GetPacketListener<PlayerPunchActionPacket>().AddClientListener(OnPlayerPunch);
    }

    private void OnDisable()
    {
        PacketListener.GetPacketListener<PlayerPunchActionPacket>().RemoveServerListener(OnPlayerPunch);
    }

    private bool OnPlayerPunch(PlayerPunchActionPacket obj, int client)
    {
        var o = GetNetworkObject(obj.Id);
        var dist = Vector3.Distance(o.transform.position, transform.position);

        if (dist > radius)
            return true; //Consume packet

        isOn.Value = !isOn.Value;
        return false;
    }
}

public class PlayerController : NetworkBehaviour
{
    private void Update()
    {
        if (!HasAuthority)
            return;

        if (Input.GetKeyDown(KeyCode.Q))
        {
            SendPacket(new PlayerPunchActionPacket { Id = Id }, true);
        }
    }
}

Packet Reliability

When you use any of the packet sending methods, you can set the reliability argument. When set to true, the delivery method is reliable, supporting larger packets at the cost of being slightly slower. When set to false, there's no reliability, packets are limited to small sizes, but delivery is extremely fast!

Synchronization of NetworkValue and any other important/instantaneous actions are done using reliable delivery because they need to be guaranteed. NetworkTransform, on the other hand, doesn't use reliable delivery because its state is updated almost constantly, so losing some packets probably won't cause issues.

Packet loss can be seen using the NetworkManagerGUI. If the network connection quality is good, you might not lose any packets, but if you have network issues, you might experience some packet loss. Choose wisely when reliability is needed or not. Most of the time, it's better to use reliable=true.

	Unreliable	Reliable
Speed	Fast+	Fast
Max Size	Small	Large
Order	Can be unordered	Order will be maintained
Loss	Can be lost	If lost, they will be resent
Example Usage	NetworkTransform, high-frequency update packets	Actions, NetworkValues, etc...

Network Callbacks

Tip

See the API reference of the NetworkBehaviour class for the list of all properties and methods.