Matchmaking

Matchmaking in MPE4S is done using the following methods:

When joining a lobby, you will trigger either a SteamManager.OnStartOwner or SteamManager.OnStartMember depending on if you are the lobby host, and SteamManager.OnShutdown will trigger when leaving one. If you fail to join a lobby, you will trigger a SteamManager.OnStartFail callback. When other members join or leave your lobby, they will trigger either a SteamManager.OnJoin or SteamManager.OnDisconnect respectively.

Buttons to host, find, or browse lobbies and friends are found on the SteamManager inspector, developer UI, and the editor windows.

If a SteamManager.Host(), SteamManager.Connect(ulong), or SteamManager.FindLobby() call fails, it will trigger a SteamManager.OnStartFail callback.

Lobby Management

Once in a lobby, you can access details about the lobby. If you are the owner, you can also set the details. When not in a lobby, or in a lobby but not the owner, setting details will impact your details for the next lobby you are the owner of. While in a lobby, you can use SteamManager.IsOwner to check if you are the owner, and SteamManager.OwnerId to get the ID of the owner. If you need to check if you are in a lobby, you can use SteamManager.InLobby and SteamManager.LobbyId to get the ID of your lobby.

  • SteamManager.MaxMembers - How many players can join the lobby up to a maximum of 250.
  • SteamManager.Mode - Controls who is able to see and join this lobby.
    • Invite Only - Only players invited by current lobby members can join. Does not show up in searches.
    • Invite and Friends - Friends of lobby members or players invited by current lobby members can join. Does not show up in searches.
    • Public - Anyone may join, and your friends can see you are in a lobby. Shows up in searches.
    • Invisible - Anyone can join, but not visible to your friends. Shows up in searches.
  • SteamManager.Open - If the lobby is open for new players to join or not, regardless of if they can see the lobby based on the mode or not.

Kicking and Banning

The lobby owner can kick and ban users using SteamManager.Kick(ulong) and SteamManager.Ban(ulong) respectively. Users can be unbanned by the owner using SteamManager.Unban(ulong). All users can see which users are banned from the current lobby using SteamManager.Banned(bool).

Host Migration

If at any point, the owner of a lobby leaves, a new owner will be chosen and trigger a SteamManager.OnOwnerChange callback.

The owner of the lobby can transfer ownership to a user in the lobby using SteamManager.TransferOwner(ulong), or SteamManager.TransferOwner() to choose a member to transfer ownership to, prioritizing any friends that are in the lobby. These will trigger a SteamManager.OnOwnerChange callback, at which point the SteamManager.OwnerId will be updated.

Limitations

No networking integrations come with host migration built-in by default, so when the owner leaves, the default behaviour of every networking integration is to have all members leave the lobby. However, each integration has the ability to choose to stay in the lobby by disabling autoDisconnect on the respective SteamTransport. Then, by listening for the respective SteamTransport.OnStopping callback, you can serialize required data to then resume the match again as a new host. See the documentation related to your networking integrations for more:

Data

All users can set their own member data, and the owner can set lobby data. All users can see the lobby and the member data of other users in the lobby. Additionally, lobby data can be requested by users outside of the lobby, whereas member data cannot. Because of this, lobby data is directly tied to searching for lobbies.

Both member data and lobby data work on key-value pairs.

Lobby Data

All members can access data for their current lobby with SteamManager.Data to get all data in the lobby, and SteamManager.GetData(string) to get a specific data entry.

As the owner, use SteamManager.SetData(string, string) to set a specific key-value pair or SetData(IEnumerable<KeyValuePair<string, string>>) to set multiple key-value pairs. To delete a key-value pair, simply pass NULL for the given value. To delete all lobby data as the owner, use SteamManager.ClearData().

To get data from a lobby that was returned from a search result, you can use SteamManager.GetData(ulong) to get all the data in a lobby, and SteamManager.GetData(ulong, string) to get a specific data entry.

When lobby data is updated, it will trigger a SteamManager.OnLobbyDataUpdate callback.

Reserved Keys

Note that the following lobby data keys are reserved internally by MPE4S as well as the Steamworks API itself, and you cannot set or delete them. SteamManager.ClearData() safely ignores these keys, and they are not returned from any getting lobby data methods.

  • _v - Ensures we only match lobbies of the current game version.
  • _o - Allows for getting if the lobby is open.
  • _m - Allows for getting the lobby mode of the lobby.
  • _f - Allows for a lobby of users to matchmake together into another lobby.
  • _b_ - Starts banned lists. Unlike other keys which cannot be an exact match, you cannot start any lobby data key with this prefix.
  • __gameserverIP - The game server IP, which is not used directly with MPE4S.
  • __gameserverPort - The game server port, which is not used directly with MPE4S.
  • __gameserverSteamID - The game server Steam ID of the owner.

Member Data

Use SteamManager.GetMemberData(ulong, string) to get a given data value for a given key of a member in the lobby. SteamManager.GetMemberData(string) gets your own member data for a given key. Use SteamManager.SetMemberData(string, string) to set a specific key-value pair or SetMemberData(IEnumerable<KeyValuePair<string, string>>) to set multiple key-value pairs. To delete a key-value pair, simply pass NULL for the given value. Note that unlike lobby data, there are no methods to get all member data for a user or clear all your data.

When a member's data is updated, it will trigger a SteamManager.OnUserDataUpdate callback.

For accessing member data from a SteamUser component, use SteamUser.GetMemberData(string). For more on the SteamUser component, see the documentation page for users.

Reserved Key

All networking integrations use the _i member data key to synchronize unique member identifiers over the network. Since networking integrations are optional, MPE4S does not prevent you from manually setting this key. If you are using a networking integration, ensure you are not manually setting this key or networking synchronization will not function correctly.

Searching

Search settings are configured through SteamSearchParameters. These are ScriptableObjects which can be created by right-clicking in the project window and going to Create > Kaiju Solutions > Multiplayer Engine for Steam > Steam Search Parameters. To use a SteamSearchParameters object, assign it to the SteamManager in the inspector or by setting SteamManager.Parameters via code.

The API documentation and editor tooltips for the SteamSearchParameters describe in detail what each attribute does. When you host a lobby, all string, number, and near data from the currently assigned SteamSearchParameters will be set to the lobby data automatically. If you are promoted to being the owner of the lobby, this does not automatically happen, as the game state, such as potentially a mode, may have changed since you last searched for lobbies. However, this could still be manually done by calling SteamSearchParameters.Set() on the given SteamSearchParameters.

If you wish to get or set any properties of the currently assigned SteamSearchParameters, the SteamManager API provides means to do so. If there is not a currently assigned SteamSearchParameters when setting these values, one will be dynamically created.

MPE4S allows for matchmaking as a group. To do so, all members of the matchmaking party need to be in a lobby together. Once ready, the owner can request to find another lobby using SteamManager.FindLobby(). If one is found, all members of the lobby will attempt to join said found lobby. This will automatically only look for open lobbies with enough space to allow all current members to join.

If searching with no SteamSearchParameters assigned to the SteamManager API, both requesting a lobby list and automatic matchmaking will return the maximum number of lobbies at the default distance and ordering them by the most populated lobbies with openings. During individual automatic matchmaking, this will prioritize joining friends over public lobbies.