Getting Started
Unity Package Types
Components
Economy
Scripting
Guidelines
Support
Overview
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.
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|string> | Properties are used to store arbitrary data for a server, and can also be used for matchmaking. |
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.
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.
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 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 Propertiesis a Dictionary of key-value pairs. In this case we have a single propertyGameType- If a match is not found, a server with those properties is not found, a new empty server is created.
Server Properties To Matchis 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 matchesDeathmatchforGameType
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.
Check out this example on Spatial today https://www.spatial.io/s/Creator-Toolkit-Matchmaking-Demo-651db47a9693d3c35d88c578
Download the example unity project here:
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.
← Previous
