RPC Details

Remote Procedure Calls (RPCs) let you call functions on a remote machine. It is similar to calling a normal function and almost as easy, but there are some important differences to understand.

An RPC call can have as many parameters as you like. All parameters will of course be sent over the network. This makes the bandwidth increase with the more parameters you send. Therefore, you should try to minimize your parameters as much as possible.
You need to determine who will receive the RPC that is being sent out. There are several RPC call modes, that cover all common use cases. You can easily invoke the RPC function on everyone, on only the server, everyone but yourself or a specific client/player.

RPC calls are usually used to execute some event on all clients in the game or pass event information specifically between two parties, but you can be creative with it and use it however you want to. For example, a server for a game which only starts after 4 clients have connected could send an RPC call to all clients as soon as the forth one connects, thus starting the game. A client could send RPC calls to everyone to signal that he picked up an item. A server could send an RPC to only a particular client to initialize him right after he connects, for example, to give him his player number, spawn location, team color, etc. A client could in turn send an RPC only to the server to specify his starting options, like which color he prefers or what items he has bought.

Using RPCs

There are two steps involved in setting up RPC calls: declaring the function you want to call and invoking it. When declaring a function you have to prefix it with an RPC attribute.

The following code declares an RPC function.

// All RPC calls need the @RPC attribute!
@RPC
function PrintText (text : String)
{
    Debug.Log(text);
}

Once you have declared an RPC call you can invoke it. All network communication goes through the Network View attached to the same GameObject as the script. In other words, you need to attach the scripts containing the RPCs functions to a GameObject that contains a Network View Component.

You can use the following variable types as parameters in RPCs:

int
float
string
NetworkPlayer
NetworkViewID
Vector3
Quaternion

The following code invokes an RPC function.

networkView.RPC ("PrintText", RPCMode.All, "Hello world");

This code will use the attached Network View to invoke all "PrintText()" functions in any scripts attached to the same GameObject.

The first parameter of RPC() is the name of the function to be invoked, the second determines who will have this function invoked. In this case we invoke the RPC call on everyone who is connected to the server but did not tell him to buffer the call for clients which connect later.

All the following parameters are the parameters that will be passed to the RPC function and be sent across the network. In this case, "Hello World" will be sent as a parameter and be passed as the text parameter in the PrintText function.

You can also get hold of an extra internal parameter, a NetworkMessageInfo struct which holds details like who sent the RPC. You do not need to specifically pass in this information, so the PrintText function shown above will be invoked exactly the same but can be declared as:

@RPC
function PrintText (text : String, info : NetworkMessageInfo)
{
    Debug.Log(text + " from " + info.sender);
}

As already mentioned, in order for RPC function to work in a script, a Network View must exist on the GameObject which contains the script. The Network View's State Synchronization can be set to Off, unless you are using State Synchronization with the same Network View.

RPC Buffer

RPC calls can also be buffered. Buffered RPC calls are stored up and executed in order for each new connecting client. They can be useful for making the process of a player joining an existing game session easier. A common scenario is that every player who joins a game should first load a specific level. Thus you would send an RPC function to everyone and then also set it to be buffered. By buffering it, whenever a new player joins the game, it will automatically be sent to the player. This way you don't need to track players joining and manually send load level RPCs specifically to the player.

Unity also has some functionality to remove calls from the RPC buffer. In the load level example, if the game has progressed through multiple levels, all you really care about is having a new player join the current level. In this case, you would remove any previously added Load Level RPC calls from the RPC buffer.

Page last updated: 2010-07-19