Unity Package Types
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.
All these properties can be configured either through the
Space package settings, or through Visual Scripting.
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.
Users can only join servers that are open
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.
The maximum capacity of users that can join a server. The platform maximum is set to
Properties are used to store arbitrary data for a server, and can also be used for matchmaking.
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
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
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
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
GameType. One is
GameType=Deathmatchand the other is
GameType=CaptureTheFlag. When finding a game for a user, we can specify that we want to find a server where
GameTypeis set to
CaptureTheFlagwhen the user interacts with GUI in your space.
Skilland map your in-experience skill value to an integer value, where
0represents low skill and
...represent higher skill players. Now, when sending users to a matching server, specify that the
Skillproperty 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
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 property
- 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 matches
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:
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.