Class ClientServerBootstrap

ClientServerBootstrap is responsible for configuring and creating the server and client worlds at runtime when the game starts (or when entering Play Mode in the Editor). ClientServerBootstrap is intended as a base class for your own custom bootstrap code and provides utility methods for creating the client and server worlds. It also supports connecting the client to the server automatically, using the AutoConnectPort port and DefaultConnectAddress. For the server, ClientServerBootstrap allows binding the server transport to a specific listening port and address (especially useful when running the server on cloud providers) via DefaultListenAddress.

Inheritance

object

ClientServerBootstrap

Implements

ICustomBootstrap

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

Namespace: Unity.NetCode

Assembly: Unity.NetCode.dll

Syntax

[Preserve]
public class ClientServerBootstrap : ICustomBootstrap

Remarks

We strongly recommend setting Application.runInBackground = true; (or project-wide via Project Settings) once you intend to connect to the server (or accept connections on said server). If you don't, your multiplayer game will stall (and likely disconnect) if and when the application loses focus (such as by the player tabbing out), as netcode will be unable to tick (due to the application pausing). In fact, a Dedicated Server Build should probably always have Run in Background enabled. We provide suppressible error warnings for this case via WarnAboutApplicationRunInBackground.

Constructors

ClientServerBootstrap()

Initialize the bootstrap class and reset the static data everytime a new instance is created.

Declaration

public ClientServerBootstrap()

Fields

AutoConnectPort

The default port to use for auto connection. The default value is zero, which means do not auto connect. If this is set to a valid port, any call to CreateClientWorld - including CreateDefaultWorlds and Initialize - will try to connect to the specified port and address, assuming DefaultConnectAddress is valid. Any call to CreateServerWorld - including CreateDefaultWorlds and Initialize - will listen on the specified port and listen address.

Declaration

public static ushort AutoConnectPort

Field Value

Type	Description
ushort

DefaultConnectAddress

The default address to connect to when using auto connect (`AutoConnectPort` is not zero). If this value is `NetworkEndPoint.AnyIpv4` auto connect will not be used, even if the port is specified. This is to allow auto listen without auto connect.

The address specified in the `PlayMode Tools` window takes precedence over this when running in the Editor (in `PlayType.Client`). If that address is not valid or you are running in a player, then `DefaultConnectAddress` will be used instead.

Declaration

public static NetworkEndpoint DefaultConnectAddress

Field Value

Type	Description
NetworkEndpoint

Remarks

Note that the DefaultConnectAddress.Port will be clobbered by the AutoConnectPort if it's set.

DefaultListenAddress

The default address to listen on when using auto connect (AutoConnectPort is not zero).

Declaration

public static NetworkEndpoint DefaultListenAddress

Field Value

Type	Description
NetworkEndpoint

k_MaxNumThinClients

The maximum number of thin clients that can be created in the Editor. Created to avoid self-inflicted long editor hangs, although removed as users should be able to test large player counts (e.g. for UTP reasons).

Declaration

public const int k_MaxNumThinClients = 1000

Field Value

Type	Description
int

Properties

ClientWorld

A reference to the client world, assigned during the default client world creation. If there were multiple worlds created this will be the first one.

Declaration

public static World ClientWorld { get; }

Property Value

Type	Description
World

ClientWorlds

A list of all client worlds created during the default creation flow. If this type of world is created manually and not via the bootstrap APIs this list needs to be manually populated.

Declaration

public static List<World> ClientWorlds { get; }

Property Value

Type	Description
List<World>

HasClientWorlds

Check if a world with a GameClient is present.

Declaration

public static bool HasClientWorlds { get; }

Property Value

Type	Description
bool	If at least one world with GameClient flags has been created.

HasServerWorld

Check if a world with a GameServer is present.

Declaration

public static bool HasServerWorld { get; }

Property Value

Type	Description
bool	If at least one world with GameServer flags has been created.

RequestedNumThinClients

The number of thin clients to create. Only available in the Editor.

Declaration

public static int RequestedNumThinClients { get; }

Property Value

Type	Description
int

RequestedPlayType

The current play mode, used to configure drivers and worlds.
- In editor, this is determined by the PlayMode tools window.
- In builds, this is determined by the platform (and thus UNITY_SERVER and UNITY_CLIENT defines), which in turn are controlled by the Project Settings.

Declaration

public static ClientServerBootstrap.PlayType RequestedPlayType { get; }

Property Value

Type	Description
ClientServerBootstrap.PlayType

Remarks

In builds, use this flag to determine whether your build supports running as a client, a server, or both.

ServerWorld

A reference to the server world, assigned during the default server world creation. If there were multiple worlds created this will be the first one.

Declaration

public static World ServerWorld { get; }

Property Value

Type	Description
World

ServerWorlds

A list of all server worlds created during the default creation flow. If this type of world is created manually and not via the bootstrap APIs this list needs to be manually populated.

Declaration

public static List<World> ServerWorlds { get; }

Property Value

Type	Description
List<World>

ThinClientWorlds

A list of all thin client worlds created during the default creation flow. If this type of world is created manually and not via the bootstrap APIs this list needs to be manually populated.

Declaration

public static List<World> ThinClientWorlds { get; }

Property Value

Type	Description
List<World>

WillServerAutoListen

Denotes if the server should start listening for incoming connection automatically after the world has been created.

If the AutoConnectPort is set, the server should start listening for connection using the DefaultConnectAddress and AutoConnectPort.

Declaration

public static bool WillServerAutoListen { get; }

Property Value

Type	Description
bool

Methods

CreateClientWorld(string)

Utility method for creating new clients worlds. Can be used in custom implementations of Initialize as well as at runtime to add new clients dynamically.

Declaration

public static World CreateClientWorld(string name)

Parameters

Type	Name	Description
string	name	The client world name

Returns

Type	Description
World	Client world instance.

CreateDefaultClientServerWorlds()

Utility method for creating the default client and server worlds based on the settings in the PlayMode tools in the Editor or client/server defined in a player. Should be used in custom implementations of Initialize.

Declaration

protected virtual void CreateDefaultClientServerWorlds()

CreateLocalWorld(string)

Utility method for creating a local world without any netcode systems.

Declaration

public static World CreateLocalWorld(string defaultWorldName)

Parameters

Type	Name	Description
string	defaultWorldName	The name to use for the default world.

Returns

Type	Description
World	World with default systems added, set to run as the main local world. See WorldFlags.

CreateServerWorld(string)

Utility method for creating a new server world. Can be used in custom implementations of Initialize as well as in your game logic (in particular client/server build) when you need to create the server programmatically (for example, a frontend that allows selecting the role or other logic).

Declaration

public static World CreateServerWorld(string name)

Parameters

Type	Name	Description
string	name	The server world name.

Returns

Type	Description
World	Server world instance.

CreateThinClientWorld()

Utility method for creating thin clients worlds. Can be used in custom implementations of Initialize as well as at runtime to add new clients dynamically.

Declaration

public static World CreateThinClientWorld()

Returns

Type	Description
World	Thin client world instance.

DetermineIfBootstrappingEnabled(bool)

Automatically discovers whether or not there is an OverrideAutomaticNetcodeBootstrap present in the active scene, and if there is, uses its value to clobber the default.

Declaration

public static bool DetermineIfBootstrappingEnabled(bool logNonErrors = false)

Parameters

Type	Name	Description
bool	logNonErrors	If true, more details are logged, enabling debugging of flows.

Returns

Type	Description
bool	Whether there is an OverrideAutomaticNetcodeBootstrap. Otherwise false.

DiscoverAutomaticNetcodeBootstrap(bool)

Returns the first OverrideAutomaticNetcodeBootstrap in the active scene. Overrides added to any non-active scenes will report as errors.

Declaration

public static OverrideAutomaticNetcodeBootstrap DiscoverAutomaticNetcodeBootstrap(bool logNonErrors = false)

Parameters

Type	Name	Description
bool	logNonErrors	If true, more details are logged, enabling debugging of flows.

Returns

Type	Description
OverrideAutomaticNetcodeBootstrap	The first override in the active scene.

Remarks

This code includes an expensive FindObjectsOfType call, for validation purposes.

HasDefaultAddressAndPortSet(out NetworkEndpoint)

Returns true if user code has specified both an AutoConnectPort and DefaultConnectAddress set.

Declaration

public static bool HasDefaultAddressAndPortSet(out NetworkEndpoint autoConnectEp)

Parameters

Type	Name	Description
NetworkEndpoint	autoConnectEp	The resulting combined Unity.Networking.Transport.NetworkEndpoint.

Returns

Type	Description
bool	True if user code has specified both an AutoConnectPort and DefaultConnectAddress.

Initialize(string)

Implement the ICustomBootstrap interface. Create the default client and server worlds based on the RequestedPlayType. In the Editor, it also creates thin client worlds, if RequestedNumThinClients is not 0.

Declaration

public virtual bool Initialize(string defaultWorldName)

Parameters

Type	Name	Description
string	defaultWorldName	The name to use for the default world. Unused, can be null or empty.

Returns

Type	Description
bool

TryFindAutoConnectEndPoint(out NetworkEndpoint)

Optional client bootstrap helper method, so your custom bootstrap flows can copy this subset of auto-connect logic. Reads RequestedPlayType, and checks for default AutoConnect arguments if valid.

Declaration

public static bool TryFindAutoConnectEndPoint(out NetworkEndpoint autoConnectEp)

Parameters

Type	Name	Description
NetworkEndpoint	autoConnectEp	A valid endpoint for auto-connection.

Returns

Type	Description
bool	True if the auto-connect Endpoint is specified for this given RequestedPlayType.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if the RequestedPlayType enum has an unknown value.

Implements

ICustomBootstrap