(For new projects, you should use the new networking system introduced in 5.1. This information is for legacy projects using the old networking system.)
Remote Procedure Calls (RPCs) let you call functions on a remote machine. Invoking an RPC 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 but the network bandwidth involved will increase with the number and size of parameters. You should keep parameters to a minimum in order to get the best performance.
Unlike a normal function call, an RPC needs an additional parameter to denote the recipients of the RPC request. There are several possible RPC call modes to cover all common use cases. For example, you can easily invoke the RPC function on all connected machines, on the server alone, on all clients but the one sending the RPC call or on a specific client.
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 and use them however you like. For example, a server for a game which only starts after four clients have connected could send an RPC call to all clients as soon as the fourth one connects, thus starting the game. A client of a particular player could send RPC calls to everyone to signal that they picked up an item. A server could send an RPC to a particular client to initialize the player right after they connect, for example, to assign them their player number, spawn location, team color, etc. A client could in turn send an RPC only to the server to specify starting options, such as the color they prefer or the items they have bought.
A function must be marked as an RPC before it can be invoked remotely. This is done by prefixing the function in the script with an RPC attribute:
using UnityEngine;
using System.Collections;
public class ExampleScript : MonoBehaviour {
[RPC]
void PrintText (string text)
{
Debug.Log(text);
}
}
C# script example
// All RPC calls need the @RPC attribute!
@RPC
function PrintText (text : String)
{
Debug.Log(text);
}
JS script example
All network communication is handled by NetworkView components, so you must attach one to the object whose script declares the RPC functions before they can be called.
You can use the following variable types as parameters to RPCs:-
For example, the following code invokes an RPC function with a single string parameter:
using UnityEngine;
using UnityEngine.Network;
using System.Collections;
public class ExampleScript : MonoBehaviour {
NetworkView networkView;
void Start() {
networkView = new NetworkView ();
networkView.RPC ("PrintText", RPCMode.All, "Hello world");
}
}
C# script example
networkView.RPC ("PrintText", RPCMode.All, "Hello world");
JS script example
The first parameter of RPC() is the name of the function to be invoked while the second determines the targets on which it will be invoked. In this case we invoke the RPC call on everyone who is connected to the server (but the call will not be buffered to wait for clients who connect later - see below for further details about buffering).
All parameters after the first two are the ones 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 access an extra internal parameter, a NetworkMessageInfo struct which holds additional information, such as where the RPC call came from. This information will be passed automatically, so the PrintText function shown above will be can be declared as:
using UnityEngine;
using System.Collections;
public class ExampleScript : MonoBehaviour {
[RPC]
void PrintText (string text, NetworkMessageInfo info)
{
Debug.Log(text + " from " + info.sender);
}
}
C# script example
@RPC
function PrintText (text : String, info : NetworkMessageInfo)
{
Debug.Log(text + " from " + info.sender);
}
JS script example
…while being invoked the same way as before.
As mentioned above, a Network View must be attached to any GameObject which has a script containing RPC functions. If you are using RPCs exclusively (ie, without state synchronisation) then the Network View’s State Synchronization can be set to Off.
RPC calls can also be buffered. Buffered RPC calls are stored up and executed in the order they were issued for each new client that connects. This can be a useful way to ensure that a latecoming player gets all necessary information to start. A common scenario is that every player who joins a game should first load a specific level. You could send the details of this level to all connected players but also buffer it for any who join in the future. By doing this, you ensure that the new player receives the level information just as if they had been present from the start.
You can also remove calls from the RPC buffer when necessary. Continuing the example above, the game may have moved on from the starting level by the time a new player joins, so you could remove the original buffered RPC and send a new one to request the new level.
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Is something described here not working as you expect it to? It might be a Known Issue. Please check with the Issue Tracker at issuetracker.unity3d.com.
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thanks for helping to make the Unity documentation better!
When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer.
More information
These cookies enable the website to provide enhanced functionality and personalisation. They may be set by us or by third party providers whose services we have added to our pages. If you do not allow these cookies then some or all of these services may not function properly.
These cookies allow us to count visits and traffic sources so we can measure and improve the performance of our site. They help us to know which pages are the most and least popular and see how visitors move around the site. All information these cookies collect is aggregated and therefore anonymous. If you do not allow these cookies we will not know when you have visited our site, and will not be able to monitor its performance.
These cookies may be set through our site by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant adverts on other sites. They do not store directly personal information, but are based on uniquely identifying your browser and internet device. If you do not allow these cookies, you will experience less targeted advertising. Some 3rd party video providers do not allow video views without targeting cookies. If you are experiencing difficulty viewing a video, you will need to set your cookie preferences for targeting to yes if you wish to view videos from these providers. Unity does not control this.
These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, logging in or filling in forms. You can set your browser to block or alert you about these cookies, but some parts of the site will not then work. These cookies do not store any personally identifiable information.