Each server for a given space has a maximum user capacity, which can be customized. When a single server hits that limit, a new one is spawned where additional users can connect to. This sharding of the space can also be turned off, which limits the number of concurrent participants to a fixed value.

Additionally, through scripting, creators can teleport users between servers, and this system can be used for matchmaking. The system is flexible, and can be used to create many different features, such as:

Grouping users into servers that match game types
Grouping admins into a single server by default.
Making a lobby waiting area where users can select their destination
Allow users to have private voice conversations by teleporting them to private servers.

Users are able to switch between servers through our core UI, but creators can customize and enhance the functionality using scripting.

<aside> <img src="/icons/clipping_gray.svg" alt="/icons/clipping_gray.svg" width="40px" /> There is a maximum of 50 players per server, and there are no limits to how many servers your space can have. The default server size (if you don’t change anything in your project settings) is 16 players.

Spaces published before Toolkit version 0.80 (Oct 4, 2023) will be set to 50 players per instance, which is unchanged from before the update. This can be changed by the space creator when publishing a new update to the space.

</aside>

Untitled

Server Properties

All these properties can be configured either through the Space package settings, or through Visual Scripting.

	Data Type	Description
Is Host	boolean	Host instances are considered the “main” or “leader” instance. Today, the only difference is that when you add content to the space from within the Spatial app, only the host instance will save those changes.
In the future, we may use the host server as the source for cross-server replication.
Is Open	boolean	Users can only join servers that are open
Is Visible	boolean	Servers that are set to invisible don’t show up in the “Switch Server” menu, and users will not be elected to randomly join them. You can use invisible servers as private servers, or for in-progress PVP games that should not allow additional participants.
Capacity	integer	The maximum capacity of users that can join a server. The platform maximum is set to `50` but this can be configured to any value between 2 and 50.
Properties	Pair<string, integer	boolean

Space Settings

Space packages allow you to customize server instancing at a basic level.

When a user joins a space for the first time, they will enter a Server that has these initial settings. Additionally, the system will always try to fill servers before sending users to more empty servers.

Untitled

<aside> <img src="/icons/flag_gray.svg" alt="/icons/flag_gray.svg" width="40px" /> Disabling Server Instancing This feature can be completely turned off. When it is off, the space always only has 1 server, and will only allow concurrent user capacity to the specified setting. Users who attempt to join while the server is at capacity will get a message explaining that the space is at capacity. Also note that when this feature is turned off, matchmaking features are not available.

</aside>

Visual Scripting Nodes

Action Nodes

Get Space Participant Count	Returns the number of participants in the current space (sum of all servers)
Get Server Participant Count	Returns the number of participants in the current server
Get Total Servers Count	Returns the total number of servers active for the current space
Get/Set Server Open	Set/Get server open state; Servers that are closed are not accepting new participants
Get/Set Server Visible	Set/Get server visible state; Servers that are not visible are not shown in the instance switcher UI and won't be randomly selected when joining a space
Get/Set Server Max Participants	Modify or retrieve the maximum number of participants allowed in the current server
Get/Set Server Properties	Modify or retrieve custom properties for the current server; Properties are used to store arbitrary data for a server, and used for matchmaking
Teleport To New Server	Teleport the current user to a new server (create new server with the requested properties)
Teleport Actors To New Server	Teleport the given list of actors to a new server with the requested matchmaking filters
Teleport To Best Match Server	Teleport the current user to the best match server based on the given matchmaking filters

Trigger Nodes

On Connected Changed	Triggered when the current user connects or disconnects from the current server
On Space Participant Count Changed	Triggered when the number of participants in the current space changes
On Server Participant Count Changed	Triggered when the number of participants in the current server changes

Advanced Matchmaking

Matchmaking is the concept of finding a best match server for a given user. Through scripting, developers can customize this behavior to fit their experiences.

Finding matches is done by using Server Properties and specifying which properties need to match. Server properties are limited to string, boolean, and integer values.

<aside> <img src="/icons/die1_gray.svg" alt="/icons/die1_gray.svg" width="40px" /> Example 1 - Game Types I have two servers that have a property named GameType. One is GameType=Deathmatch and the other is GameType=CaptureTheFlag. When finding a game for a user, we can specify that we want to find a server where GameType is set to CaptureTheFlag when the user interacts with GUI in your space.

</aside>

<aside> <img src="/icons/die2_gray.svg" alt="/icons/die2_gray.svg" width="40px" /> Example 2 - Skill Matching To match users based on skill, you may define a server property Skill and map your in-experience skill value to an integer value, where 0 represents low skill and 1, 2, ... represent higher skill players. Now, when sending users to a matching server, specify that the Skill property should match your locally computed value. Note that skill-based matching is more suited when you have higher concurrent users in your space.

</aside>

Matching a user through scripting

Using Teleport To Best Match Server you can move the user to a server that matches certain properties

Server Properties is a Dictionary of key-value pairs. In this case we have a single property GameType
- If a match is not found, a server with those properties is not found, a new empty server is created.
Server Properties To Match is a List of strings, specifying which properties should match. The matchmaking system will look through all open and visible existing servers, and select a server that matches Deathmatch for GameType

Untitled

Matchmaking Example

Matchmaking can be done in many different ways. Here’s an example of a lobby system, where users are asked to jump onto a platform to organize into games. Once someone enters a platform and the minimum player count is reached, a countdown starts. When the countdown reaches 0, all users on the platform are teleported to a new server for that specific game.

Advanced Concepts

Detecting when user has changed and connected to a server

You can use the On Connected Changed node to get notified when a user disconnects and reconnects. If a full disconnect and reconnect has happened, it is likely that the user has switched server.

Handling local variables and scene state when switching server

It is important to understand that when a user changes server, that the state (Scene Variables, Object Variables, Graph Variables, ..) are not reset. On one hand, this is great because you can store state that can be transferred between Servers, but on the other hand this does require you to manually reset certain state that defines how your space operates.

For example, in the matchmaking example on this page, when the user disconnects from a server, we reset the timers, or else they continue after we have switched the server.

Untitled