Class ClientServerBootstrap

ClientServerBootstrap is responsible to configure and create the Server and Client worlds at runtime when the game start (in the editor when entering PlayMode). The ClientServerBootstrap is meant to be a base class for your own custom boostrap code and provides utility methods that make it easy creating the client and server worlds. It also support connecting the client to server automatically, using the AutoConnectPort port and DefaultConnectAddress. For the server, it allow binding the server transport to a specific listening port and address (especially useful when running the server on some cloud provider) 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 will stall (and likely disconnect) if and when the application loses focus (e.g. 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. If at least one world with GameClient flags has been created.

Declaration

public static bool HasClientWorlds { get; }

Property Value

Type	Description
bool

HasServerWorld

Check if a world with a GameServer is present. If at least one world with GameServer flags has been created.

Declaration

public static bool HasServerWorld { get; }

Property Value

Type	Description
bool

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.

Declaration

public static ClientServerBootstrap.PlayType RequestedPlayType { get; }

Property Value

Type	Description
ClientServerBootstrap.PlayType

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

Check 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 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

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.

Name of the world instantiated. World with default systems added, set to run as the Main Live world. See WorldFlags.Game

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	A new world instance.

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 server programmatically (ex: frontend that allow 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

CreateThinClientWorld()

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

Declaration

public static World CreateThinClientWorld()

Returns

Type	Description
World

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, we'll log more details, enabling debugging of flows.

Returns

Type	Description
bool

DiscoverAutomaticNetcodeBootstrap(bool)

Returns the first Override in the Active scene. Overrides in the non-active scene will report as errors.

Declaration

public static OverrideAutomaticNetcodeBootstrap DiscoverAutomaticNetcodeBootstrap(bool logNonErrors = false)

Parameters

Type	Name	Description
bool	logNonErrors	If true, we'll log more details, enabling debugging of flows.

Returns

Type	Description
OverrideAutomaticNetcodeBootstrap	The first Override in the Active scene.

Remarks

Unfortunately, this code includes a FindObjectsOfType call, for validation purposes.

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

Implements

ICustomBootstrap