Important: UNet is a deprecated solution, and a new Multiplayer and NetworkingThe Unity system that enables multiplayer gaming across a computer network. More info See in Glossary Solution (Netcode for GameObjects) is under development. For more information and next steps see the information on the Unity Netcode for GameObjects website. |
In addition to the high-level networking API (HLAPI), Unity also provides access to a lower-level networking API called the Transport Layer. The Transport Layer allows you to build your own networking systems with more specific or advanced requirements for your game’s networking.
The Transport Layer is a thin layerLayers in Unity can be used to selectively opt groups of GameObjects in or out of certain processes or calculations. This includes camera rendering, lighting, physics collisions, or custom calculations in your own code. More info
See in Glossary working on top of the operating system’s sockets-based networking. It can send and receive messages represented as arrays of bytes, and offers a number of different “quality of service” options to suit different scenarios. It is focused on flexibility and performance, and exposes an API within the NetworkTransport class.
The Transport Layer supports base services for network communication. These base services include:
Establishing connections
Communicating using a variety of “quality of services”
Flow control
Base statistics
Additional services, such as communication via relay server or local discovery
The Transport Layer can use two protocols: UDP for generic communications, and WebSockets for WebGLA JavaScript API that renders 2D and 3D graphics in a web browser. The Unity WebGL build option allows Unity to publish content as JavaScript programs which use HTML5 technologies and the WebGL rendering API to run Unity content in a web browser. More info
See in Glossary. To use the Transport Layer directly, the typical workflow is as follows:
Initialize the Network Transport Layer
Configure network topology
Create a host
Start communication (handling connections and sending/receiving messages)
Shutdown library after use
See the corresponding sections below to learn about the technical details of each section. Each section provides a code snippet to include in your networking script.
When initializing the Network Transport Layer, you can choose between the default initialization demonstrated in the code sample below (with no arguments), or you can provide additional parameters which control the overall behaviour of the network layer, such as the maximum packet size and the thread timeout limit.
To initialize the transport layer with default settings, call Init():
// Initializing the Transport Layer with no arguments (default settings)
NetworkTransport.Init();
To initialize the transport layer with your own configuration just add your configuration as a parameter to Init, as shown below.
// An example of initializing the Transport Layer with custom settings
GlobalConfig gConfig = new GlobalConfig();
gConfig.MaxPacketSize = 500;
NetworkTransport.Init(gConfig);
You should only use custom Init
values if you have an unusual networking environment and are familiar with the specific settings you need. As a rule of thumb, if you are developing a typical multiplayer game to be played across the internet, the default Init
settings are enough.
The next step is to configure connections between peers. Network topology defines how many connections allowed and what connection configuration will used. If your game needs to send network messages which vary in importance (eg low importance such as incidental sound effects, vs high importance such as whether a player scored a point), you might want to define several communication channels, each with a different quality of service level specified to suit the specific types of messages that you want to send, and their relative importance within your game.
ConnectionConfig config = new ConnectionConfig();
int myReliableChannelId = config.AddChannel(QosType.Reliable);
int myUnreliableChannelId = config.AddChannel(QosType.Unreliable);
The example above defines two communication channels with different quality of service values. QosType.Reliable delivers a message and ensures that the message is delivered, while QosType.Unreliable sends a message faster, but without any checks to ensure it was delivered.
You can also adjust properties on ConnectionConfig to specify configuration settings for each connection. However, when making a connection from one client to another, the settings should be the same for both connected peers, or the connection fails with a CRCMismatch error.
The final step of network configuration is topology definition.
HostTopology topology = new HostTopology(config, 10);
This example defines host topology as being able to allow up to 10 connections. These connections are the ones you configured in Step 1.
Now that you have performed the first two preliminary set-up steps, you need to create a host (open socket):
int hostId = NetworkTransport.AddHost(topology, 8888);
This code example adds a new host on port 8888 and any IP addresses. The host supports up to 10 connections (you configured this in Step 2). These connections are the ones you configured in the Step 1.
In order to start communicating, you need to set up a connection to another host. To do this, call Connect()
. This sets up a connection between you and the remote host. An event is received to indicate whether the connection is successful.
First, connect to the remote host at 192.168.1.42 with port 8888. The assigned connectionId
is returned.
connectionId = NetworkTransport.Connect(hostId, "192.168.1.42", 8888, 0, out error);
When the connection is done, a ConnectEvent is received. Now you can start sending data.
NetworkTransport.Send(hostId, connectionId, myReliableChannelId, buffer, bufferLength, out error);
When you are done with a connection, call Disconnect()
to disconnect the host.
NetworkTransport.Disconnect(hostId, connectionId, out error);
To check if your function calls were successful, you can cast the out error
to a NetworkError. NetworkEror.Ok indicates that no errors have been encountered.
To check host status, you can use two functions:
For polling events off the internal event queue you can call either
NetworkTransport.Receive(out recHostId, out connectionId, out channelId, recBuffer, bufferSize, out dataSize, out error);
Or NetworkTransport.ReceiveFromHost(recHostId, out connectionId, out channelId, recBuffer, bufferSize, out dataSize, out error);
Both of these functions return events from the queue; the first function will return events from any host, and the recHostId variable will be assigned with the host id that the message comes from, whereas the second function returns events only from the host specified by the recHostId that you provide.
One way to poll data from Receive
is to call it in your Update
function;
void Update()
{
int recHostId;
int connectionId;
int channelId;
byte[] recBuffer = new byte[1024];
int bufferSize = 1024;
int dataSize;
byte error;
NetworkEventType recData = NetworkTransport.Receive(out recHostId, out connectionId, out channelId, recBuffer, bufferSize, out dataSize, out error);
switch (recData)
{
case NetworkEventType.Nothing: break;
case NetworkEventType.ConnectEvent: break;
case NetworkEventType.DataEvent: break;
case NetworkEventType.DisconnectEvent: break;
case NetworkEventType.BroadcastEvent:
break;
}
}
There are 5 type of events that you can receive.
NetworkEventType.Nothing: The event queue has nothing to report.
NetworkEventType.ConnectEvent : You have received a connect event. This can be either a successful connect request, or a connection response.
case NetworkEventType.ConnectEvent:
if(myConnectionId == connectionId)
//my connect request was approved
else
//somebody else sent a connect request to me
break;
NetworkEventType.DataEvent: You have received a data event. You receive a data event when there is some data ready to be recieved. If the recBuffer
is big enough to contain data, data is copied into the buffer. If not, the event contains a MessageToLong network error. If this happens, you need to reallocate the buffer to a larger size and call the DataEvent
function again.
NetworkEventType.DisconnectEvent: Your established connection has disconnected, or your connect request has failed. Check the error code to find out why this has happened.
case NetworkEventType. DisconnectEvent:
if(myConnectionId == connectionId)
//cannot connect for some reason, see error
else
//one of the established connections has disconnected
break;
You can use WebSockets on WebGL, however web clients can only connect to hosts, they cannot be a host themselves. This means the host must be a standalone player (Win, Mac or Linux only). For client-side configuration, all steps described above (including topology and configuration) are the same. On the server, call the following:
NetworkTransport.AddWebsocketHost(topology, port, ip);
The IP address above should be the specific address you want to listen on, or you can pass null as the IP address if you want the host to listen all network interfaces.
A server can only support only one WebSocket host at a time, but it can handle other generic hosts at the same time:
NetworkTransport.AddWebsocketHost(topology, 8887, null);
NetworkTransport.AddHost(topology, 8888);
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.