Create a session
Note: The Multiplayer Services SDK uses sessions to manage groups of players. Sessions relies internally on different combinations of Unity Gaming Services such Relay, Lobby, Matchmaker and Multiplay Hosting, and thus contributes to the billing of those services.
To start a multiplayer game, the host must create a session that other players join to participate in the game. This page outlines what you must include in your script to create a session. Consider the following factors when you create a session:
- The session options properties
- The type of network connection
Note: To access the API for the Multiplayer Services SDK, import the SDK's namespace in your script:
using Unity.Services.Multiplayer;
The CreateOrJoinSessionAsync method
The CreateOrJoinSessionAsync
method either joins the session with the given ID, or if it does not exist, creates the session.
This is convenient in cases where race condition can happen between clients and you are not sure which client will create the session.
var session = await MultiplayerService.Instance.CreateOrJoinSessionAsync(sessionId, options)
Session options properties
The session options determine various properties of your session, such as the maximum number of players or whether the session is password protected.
Refer to Class SessionOptions
for a full list of options.
Type of network connection
Another consideration for your session is the network connection type with which the players join the session. Players can join with a direct network connection, or via Relay. Using a relay for network connection provides the most compatibility, and is the recommended best practice for peer-to-peer games played over the Internet.
Refer to Class SessionOptions > Methods
for more information.
Example
Consider the following example code you might add to your script to create a session.
async void StartSessionAsHost()
{
var options = new SessionOptions
{
MaxPlayers = 2
}.WithRelayNetwork();
var session = await MultiplayerService.Instance.CreateSessionAsync(options);
Debug.Log($"Session {session.Id} created! Join code: {session.Code}");
}
In this code:
- The variable
MaxPlayers
sets the maximum number of players allowed in the session, including the host. In this example, the maximum number of players is two. - The variable options of class
SessionOptions
can determine other session options, such as the session’s name, and whether it is password protected. - The use of
WithRelayNetwork()
configures the session to use Relay networking rather than direct connections (in other words, with a fixed IP address and port). This is the recommended best practice for peer-to-peer connectivity over the Internet. Refer to Relay. - The line
var session = await MultiplayerService.Instance.CreateSessionAsync(options);
creates the session, and makes the player the host. - The final line,
Debug.Log($"Session {session.Id} created! Join code: {session.Code}");
, displays the session ID and join code in the console of the Unity Editor. The host would then share this join code with the other players. Alternatively, you could create a variable to get the join code, as invar joinCode = session.Code;
and use that variable instead.
Advanced usage: Specifying a custom network handler
It is possible to specify a custom network handler implementing INetworkHandler, overriding the default integration with Netcode for Game Objects and Netcode for Entities.
var options = new SessionOptions { MaxPlayers = 2 }
.WithRelayNetwork()
.WithNetworkHandler(new CustomEntitiesNetworkHandler());