RPC System Reference Sheet

Remote Procedure Call (RPC)

Valheim uses an RPC system that allows clients and the server to tell each other to run functions with specified arguments for its parameters. The RPC system relies on identifying a function by a string name. This is setup by calling :

ZRoutedRpc.instance.Register("Unique_RPC_name", new Action<long>(RPC_MethodToCall);

RPC_MethodToCall can be defined as a regular or static method. Its declaration (or method signature) must return void and have at least one parameter (first parameter must be of type long), with no more than 5 parameters :

void RPC_MethodToCall(long sender)
void RPC_MethodToCall(long sender, int a)
void RPC_MethodToCall(long sender, int a, string b)
void RPC_MethodToCall(long sender, int a, string b, float c)
void RPC_MethodToCall(long sender, int a, string b, float c, Vector3 d)

This is because Valheim hardcodes 5 RoutedMethod classes with generic types to handle the parameters passed through the ZPackage that ZRoutedRpc puts all the parameters into for replication across the network. If you find that you want to send more than 4 parameters, you can send a ZPackage of your own as a parameter.

The naming convention of prefixing RPC methods with "RPC_" is one found in the Valheim codebase and commonly used by mod authors.

You want to register your RPC as soon as you can, making the following code a useful reference :

[HarmonyPatch(typeof(Game), "Start")]
public static class GameStartPatch
{
    private static void Prefix()
    {
        ZRoutedRpc.instance.Register("Unique_RPC_name", new Action<long>(RPC_MethodToCall);
    }
}

That code ensures that your RPC is registered on the server and clients. This means that your mod will have to run on the server and clients as well. When you are ready to make the RPC call :

ZRoutedRpc.instance.InvokeRoutedRPC(ZNetView.Everybody, "Unique_RPC_Name", 5);

ZNetView.Everybody is a constant value that tells the RPC system to send the RPC to the server and all clients. You can send the RPC to a particular server or client by passing their PeerID. See below for different ways to get PeerIDs.

What are ZPackages?

ZPackages are a custom class in Valheim whose sole job is to be serializable and sent over the RPC system to be deserialized. You can write almost all standard types of data to them including bool, byte, byte[], char, double, int, long, Quaternion, sbyte, float, string, uint, ulong, Vector2i, Vector3, and ZDOID. While Quaternion, Vector2i, and Vector3 are Unity types, you can still de/serialize them with ZPackages. The RPC system uses a ZPackage as its data payload, and you can even fill your own ZPackage and have it sent in an RPC.

Using a ZPackage yourself requires you to serialize data into it manually deserialize data out of it in the same order you serialized data. See the Valheim source file ZPackage.cs to learn more about them.

Useful Functions

Get the server host's RPC uid:

ZRoutedRpc.instance.GetServerPeerID();

Get a UID from a ZRpc instance:

ZNetPeer peer = ZNet.instance.GetPeer(rpc);
peer.m_uid // The UID

Get a UID from a player's name:

ZNetPeer peer = ZNet.instance.GetPeerByPlayerName(name);
peer.m_uid // The UID