Class SessionOptionsExtensions

Provides extension methods to configure session options.

Inheritance

object

SessionOptionsExtensions

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Unity.Services.Multiplayer

Assembly: Unity.Services.Multiplayer.dll

Syntax

public static class SessionOptionsExtensions

Remarks

To configure the network topology.

Topology	Methods
Direct Connection	WithDirectNetwork<T>(T) WithDirectNetwork<T>(T, DirectNetworkOptions) WithDirectNetwork<T>(T, string, string, int)
Relay Connection	WithRelayNetwork<T>(T, string) WithRelayNetwork<T>(T, RelayNetworkOptions)
Distributed Authority	WithDistributedAuthorityNetwork<T>(T, string) WithDistributedAuthorityNetwork<T>(T, RelayNetworkOptions)

To configure the network handler.
WithNetworkHandler<T>(T, INetworkHandler)

To configure host migration.
WithHostMigration<T>(T, IMigrationDataHandler)
WithHostMigration<T>(T, IMigrationDataHandler, TimeSpan, TimeSpan)

To configure player name.
WithPlayerName<T>(T, VisibilityPropertyOptions)

Methods

GetPlayerName(IReadOnlyPlayer)

Retrieve the player name from the session player property

Declaration

public static string GetPlayerName(this IReadOnlyPlayer player)

Parameters

Type	Name	Description
IReadOnlyPlayer	player	The player to retrieve the name from

Returns

Type	Description
string	The player name

WithDirectNetwork<T>(T)

Same as WithDirectNetwork<T>(T, DirectNetworkOptions) but the listen address defaults to LoopbackIpv4, the publish address defaults to LoopbackIpv4 and the port defaults to0.

Declaration

public static T WithDirectNetwork<T>(this T options) where T : SessionOptions

Parameters

Type	Name	Description
T	options	The SessionOptions this extension method applies to.

Returns

Type	Description
T	The session options.

Type Parameters

Name	Description
T	The options' type.

Remarks

The default values allow local connections only.

The port number defaults to 0 which selects a randomly available port on the machine and uses the chosen value as the publish port.

See Also

WithDirectNetwork<T>(T, DirectNetworkOptions)

WithDirectNetwork<T>(T, string, string, int)

Configures a session to use direct networking and accept connections at the specified address.

Declaration

public static T WithDirectNetwork<T>(this T options, string listenIp = "127.0.0.1", string publishIp = "127.0.0.1", int port = 0) where T : SessionOptions

Parameters

Type	Name	Description
T	options	The SessionOptions this extension method applies to.
string	listenIp	Listen for incoming connection at this address (0.0.0.0 for all interfaces).
string	publishIp	Address that clients should use when connecting
int	port	Port to listen for incoming connections and also the one to use by clients

Returns

Type	Description
T	The session options

Type Parameters

Name	Description
T	The options' type.

Remarks

Using direct networking in client-hosted games reveals the IP address of players to the host. For client-hosted games, using Relay or Distributed Authority is recommended to handle NAT, firewalls and protect player privacy.

The default values allow local connections only and use 127.0.0.1 as the listenIp and publishIp. To listen on all interfaces, use 0.0.0.0 as the listenIp and specify the external/public IP address that clients should use as the publishIp.

The port number defaults to 0 which selects a randomly available port on the machine and uses the chosen value as the publish port. If a non-zero value is used, the port number applies to both listen and publish addresses.

When using Netcode for Entities, the default Multiplayer Services Network handler requires that your Client and Server Worlds are created before you create or join a session. Using the default ClientServerBootstrap, automatically creates the client and server worlds at startup when the Netcode for Entities package is first added to your project. For more advanced use cases, use WithNetworkHandler<T>(T, INetworkHandler) to disable the default integration with Netcode for Entities.

WithDirectNetwork<T>(T, DirectNetworkOptions)

Configures a session to use direct networking and accept connections at the specified IP address.

Declaration

public static T WithDirectNetwork<T>(this T options, DirectNetworkOptions networkOptions) where T : SessionOptions

Parameters

Type	Name	Description
T	options	The SessionOptions this extension method applies to.
DirectNetworkOptions	networkOptions	The options used to configure the direct network connection, including port settings and other network parameters.

Returns

Type	Description
T	The session options.

Type Parameters

Name	Description
T	The options' type.

WithDistributedAuthorityNetwork<T>(T, string)

Configures a session to use the Distributed Authority networking.

Declaration

public static T WithDistributedAuthorityNetwork<T>(this T options, string region = null) where T : SessionOptions

Parameters

Type	Name	Description
T	options	The SessionOptions this extension method applies to.
string	region	The Relay region where the Relay allocation used by Distributed Authority will happen. Defaults to us-central1.

Returns

Type	Description
T	The SessionOptions configured to use DTLS on most platforms, or WSS on WebGL for network communication.

Type Parameters

Name	Description
T	The options' type.

Remarks

To obtain the list of available region, use the Relay Allocations Service via ListRegionsAsync().
To determine the lowest latency region, use GetSortedRelayQosResultsAsync(IList<string>).

WithDistributedAuthorityNetwork<T>(T, RelayNetworkOptions)

Configures a session to use the Distributed Authority networking with the specified RelayNetworkOptions.

Declaration

public static T WithDistributedAuthorityNetwork<T>(this T options, RelayNetworkOptions relayOptions) where T : SessionOptions

Parameters

Type	Name	Description
T	options	The SessionOptions this extension method applies to.
RelayNetworkOptions	relayOptions	The RelayNetworkOptions specifying the relay RelayProtocol and region to use for Distributed Authority networking.

Returns

Type	Description
T	The SessionOptions configured to use the provided relayOptions.

Type Parameters

Name	Description
T	The options' type.

Remarks

To obtain the list of available regions, use the Relay Allocations Service via ListRegionsAsync().
To determine the lowest latency region, use GetSortedRelayQosResultsAsync(IList<string>).

WithHostMigration<T>(T)

Enables host migration for the session using the default migration data handler (EntitiesMigrationDataHandler) and default timing options.

Declaration

public static T WithHostMigration<T>(this T options) where T : BaseSessionOptions

Parameters

Type	Name	Description
T	options	The session options to configure.

Returns

Type	Description
T	The session options with host migration enabled.

Type Parameters

Name	Description
T	The session option type derived from BaseSessionOptions.

WithHostMigration<T>(T, IMigrationDataHandler)

Enables host migration for the session with the specified migration data handler, using default timing options DefaultDataUploadInterval and DefaultDataHandlingTimeout.

Declaration

public static T WithHostMigration<T>(this T options, IMigrationDataHandler migrationDataHandler) where T : BaseSessionOptions

Parameters

Type	Name	Description
T	options	The session options to configure.
IMigrationDataHandler	migrationDataHandler	The handler responsible for migration data processing.

Returns

Type	Description
T	The session options with host migration enabled.

Type Parameters

Name	Description
T	The session option type derived from BaseSessionOptions.

Exceptions

Type	Condition
ArgumentNullException	Thrown if migrationDataHandler is null.

WithHostMigration<T>(T, IMigrationDataHandler, TimeSpan, TimeSpan)

Enables host migration for the session with the specified migration data handler and timing options.

Declaration

public static T WithHostMigration<T>(this T options, IMigrationDataHandler migrationDataHandler, TimeSpan dataUploadInterval, TimeSpan dataHandlingTimeout) where T : BaseSessionOptions

Parameters

Type	Name	Description
T	options	The session options to configure.
IMigrationDataHandler	migrationDataHandler	The handler responsible for migration data processing.
TimeSpan	dataUploadInterval	The interval at which migration data is uploaded. The lowest interval is 1 second.
TimeSpan	dataHandlingTimeout	The timeout for handling migration data.

Returns

Type	Description
T	The session options with host migration enabled.

Type Parameters

Name	Description
T	The session option type derived from BaseSessionOptions.

Exceptions

Type	Condition
ArgumentNullException	Thrown if migrationDataHandler is null.
ArgumentOutOfRangeException	Thrown if dataUploadInterval is lower than 1 second.

WithNetworkHandler<T>(T, INetworkHandler)

Configures a session to use a custom network handler.

Declaration

public static T WithNetworkHandler<T>(this T options, INetworkHandler networkHandler) where T : BaseSessionOptions

Parameters

Type	Name	Description
T	options	The SessionOptions this extension method applies to.
INetworkHandler	networkHandler	The INetworkHandler to use.

Returns

Type	Description
T	The session options.

Type Parameters

Name	Description
T	The options' type.

Remarks

When a network handler is provided, it disables the default integration with Netcode for Game Objects and Netcode for Entities.

Combine this option with other networking options:
WithDirectNetwork<T>(T)
WithDirectNetwork<T>(T, string, string, int)
WithDirectNetwork<T>(T, DirectNetworkOptions)
WithRelayNetwork<T>(T, string)
WithRelayNetwork<T>(T, RelayNetworkOptions)
WithDistributedAuthorityNetwork<T>(T, string)
WithDistributedAuthorityNetwork<T>(T, RelayNetworkOptions)

to obtain the appropriate data to implement a custom management of the netcode library and/or transport library.

This option applies to all session flows and is normally set for all roles (host, server, client).

WithPlayerName<T>(T, VisibilityPropertyOptions)

Synchronizes the unity player name as a session player property. Requires the unity player name to be retrieved with the Authentication service.

Declaration

public static T WithPlayerName<T>(this T options, VisibilityPropertyOptions visibility = VisibilityPropertyOptions.Member) where T : BaseSessionOptions

Parameters

Type	Name	Description
T	options	The SessionOptions this extension method applies to.
VisibilityPropertyOptions	visibility	The visibility to apply to the player name property. It must be Member or Public to be readable by other players.

Returns

Type	Description
T	The session options

Type Parameters

Name	Description
T	The options' type.

WithRelayNetwork<T>(T, string)

Configures a session to use Relay networking.

Declaration

public static T WithRelayNetwork<T>(this T options, string region = null) where T : SessionOptions

Parameters

Type	Name	Description
T	options	The SessionOptions this extension method applies to.
string	region	Force a specific Relay region to be used and skip auto-selection from QoS.

Returns

Type	Description
T	The SessionOptions configured to use DTLS on most platforms, WSS on WebGL for communication.

Type Parameters

Name	Description
T	The options' type.

Remarks

The region is optional; the default behavior is to perform quality of service (QoS) measurements and pick the lowest latency region. The list of regions can be obtained from the Relay Allocations Service via ListRegionsAsync().

When using Netcode for Entities, the default Multiplayer Services Network handler requires that your Client and Server Worlds are created before you create or join a session. Using the default ClientServerBootstrap, automatically creates the client and server worlds at startup when the Netcode for Entities package is first added to your project. For more advanced use cases, use WithNetworkHandler<T>(T, INetworkHandler) to disable the default integration with Netcode for Entities.

WithRelayNetwork<T>(T, RelayNetworkOptions)

Configures a session to use Relay networking.

Declaration

public static T WithRelayNetwork<T>(this T options, RelayNetworkOptions relayOptions) where T : SessionOptions

Parameters

Type	Name	Description
T	options	The SessionOptions this extension method applies to.
RelayNetworkOptions	relayOptions	The RelayNetworkOptions

Returns

Type	Description
T	The SessionOptions.

Type Parameters

Name	Description
T	The options' type.

Remarks

The region is optional; the default behavior is to perform quality of service (QoS) measurements and pick the lowest latency region. The list of regions can be obtained from the Relay Allocations Service via ListRegionsAsync().

When using Netcode for Entities, the default Multiplayer Services Network handler requires that your Client and Server Worlds are created before you create or join a session. Using the default ClientServerBootstrap, automatically creates the client and server worlds at startup when the Netcode for Entities package is first added to your project. For more advanced use cases, use WithNetworkHandler<T>(T, INetworkHandler) to disable the default integration with Netcode for Entities.