Servers and Matchmaking

When a user joins a space, they are automatically put into a server. Each server has a maximum user capacity: when a server reaches that limit, a new server is created for additional users to connect to.

The Spatial Creator Toolkit provides granular control over server instancing. You can customize the server capacity or disable it altogether to limit the total number of concurrent participants to a fixed value. Through scripting, creators can create a complex matchmaking system. For example, you can:

  • Group users into servers that match game types
  • Group admins into a single server by default.
  • Make 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.


The maximum server size is 50 players per server. 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.

You can set basic server instancing settings on your Space package configuration. When a user joins a space for the first time, they will enter a server with these initial settings. The system will always try to fill servers before sending users to more empty servers.

Space package server property settings

Switch server UI

Server instancing can be disabled altogether. If disabled, 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 and will not be allowed to join the space. When this feature is turned off, matchmaking features are not available.


Spaces published before Toolkit version 0.80 (Oct 4, 2023) will have a server size of 50. This can be changed by the space creator when publishing a new update to the space. Spaces published after version 0.80 have a default server size of 16.

Server Properties

The following configuration properties are available for each server.

PropertyData TypeDescription
Is HostbooleanHost 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 OpenbooleanUsers can only join servers that are open
Is VisiblebooleanServers 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.
CapacityintegerThe 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.
PropertiesPair<string, integer | boolean | string>Properties are used to store arbitrary data for a server, and can also be used for matchmaking.

Visual Scripting Nodes

Action Nodes

Get Space Participant CountReturns the number of participants in the current space (sum of all servers)
Get Server Participant CountReturns the number of participants in the current server
Get Total Servers CountReturns the total number of servers active for the current space
Get/Set Server OpenSet/Get server open state; Servers that are closed are not accepting new participants
Get/Set Server VisibleSet/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 ParticipantsModify or retrieve the maximum number of participants allowed in the current server
Get/Set Server PropertiesModify 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 ServerTeleport the current user to a new server (create new server with the requested properties)
Teleport Actors To New ServerTeleport the given list of actors to a new server with the requested matchmaking filters
Teleport To Best Match ServerTeleport the current user to the best match server based on the given matchmaking filters

Trigger Nodes

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

Advanced Matchmaking


Check out our Matchmaking Template for a fully implemented example of a matchmaking/lobby system!

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.

Some common examples of matchmaking scenarios include:

  • 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.
  • 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.

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

Server Properties

Server Properties Scripting Example

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, 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.

Advanced matchmaking: Visual Scripting graph