Peer AutoMatch

Peer AutoMatch

Overview

The ability to automatically match players together, or AutoMatch, was added to the Peer SDK with version 2.01. The system is designed to be very flexible, allowing the application to use arbitrary values to rate possible matches, which helps to ensure that the best possible match is made.

To start, the application needs to get the local player's preferences, then start an AutoMatch attempt. The application is then responsible for rating potential matches and handling queries as to the local player's preferences. The local player will be placed in a staging room while waiting for a match and will be able to chat with the other players while waiting for a full match to be set up. The application does not need to present a chat interface or allow the user to chat. Once all the players in a match are in a room together, the application uses the peerStartGame() function to start the actual game.

The two most important aspects of implementing AutoMatch are determing what choices the user will have and how potential matches will be rated. The choices/preferences available to the user will determine when values need to be reported in the peerQR*Callback() functions, how to setup the filter passed to peerStartAutoMatch[WithSocket], and what values are available when rating potential matches. The method for rating potential matches will determine how Peer decides which match is the best and will dictate what values need to be reported in the peerQR*Callback() functions.

Implementation

Starting An Automatch

There are only a few functions directly involved in starting and running an AutoMatch. The basics of getting connected to the chat backend are the same as with regular Peer matchmaking. This involves calling peerInitialize(), peerSetTitle(), and peerConnect(), and using peerThink() to allow Peer to do any needed processing. See the "GameSpy Peer SDK" document for further information, specifically the sections Initializing, Thinking, Title, and Connecting. Once connected to the backend, Peer is ready to do AutoMatching.

To start the AutoMatch attempt, call either peerStartAutoMatch() or peerStartAutoMatchWithSocket(). The WithSocket version of the function allows the application to provide a UDP socket that Peer will be used for reporting. Both functions take a maxPlayers parameter, which specifices the maximum number of people that should be in the final match. For example, if the local player wants to player a 3v3 match, maxPlayers should be 6. The match can be started before the maxPlayers is reached, for example if an exact number of players is not needed, but an upper limit must still be specified.

The filter is a SQL-type filter, just like the filter used in peerStartListingGames(). It is used to rule out matches that are not acceptable. Potential matches that do not pass the filter will not be passed to the rating callback. The statusCallback is called whenever the status of the match changes, until either peerStopAutoMatch() is called, or the statusCallback is called with a status of PEERFailed or PEERComplete. The rateCallback is used to rate possible matches.

Once an AutoMatch attempt has been started, Peer handles everything, calling the rateCallback and the peerQR*Callback() functions whenever they are needed. The application is then responsible for assigning ratings to servers in the rateCallback, responding to queries through the peerQR*Callback() functions, updating the UI based on the statusCallback or peerGetAutoMatchStatus(), having the host start the game when reaching the PEERReady status, and having non-host players watch for the peerGameStartedCallback and/or the PEERComplete status. The application should also allow the user to cancel the AutoMatch attempt with peerStopAutoMatch().

Rating A Potential Match

During an AutoMatch attempt Peer may ask the application, through the peerAutoMatchRateCallback() passed to peerStartAutoMatch[WithSocket](), to rate a potential match. The application is responsible for assigning an integer rating value to the match, which is returned from the callback.

Peer uses the rating to determine if the match is acceptable and, if it is acceptable, how good of a match it is. If a value of 0 or less is returned from the callback, Peer will not attempt to join up to that match. If a value is 1 or greater than Peer may attempt to join the match. The higher the value returned, the better the match. If there are multiple acceptable matches, Peer will attempt to join them in order starting with the highest rated match, then the second highest rated match, etc.

The rating callback must take into account all of the local player's preferences compared to the settings/preferences for all of the players currently in the match, and come up with a single number representing how good the potential match is. Typically the callback will first check any "hard criteria", which are any settings that must match. For example if the player has selected that he only wants to play in a 2v2 match, the first line of the callback may check that the match is a 2v2 match:

if(SBServerGetIntValue(match, "maxplayers", 0) != 4)
	return 0;

A good method for comparing a list of "soft criteria" (such as preferences) is to assign each value a maximum weight, calculate the actual weight for each value by comparing the local value to the value reported by the server, then total all the weights and return that value as the rating. If a value is to be compared against the values of each player already in the match, then the existing players' values can be averaged, then compared against.

A game could, for example, assign maximum weights of 100 to ratings differences and 50 to map preferences. In the callback the application averages the players' ratings and compares them to the local player's rating, determining that, because there is a fairly large difference, the ratings differences actual weight is 25. The application then compares the local player's map preferences to each player's preferences, assigns a weight to each player based on how close the preferences match, then averages all of those individual weights to determine the overall actual weight for map preferences.

Because they preferences are fairly close, the actual weight for map preferences is 40. Adding together the actual weights for ratings differences and map preferences gives a total of 65, which the application then returns from the callback as the rating for the match.

Automatic Hosting

During an AutoMatch attempt, if the local player ends up as host of a staging room (see above for how a user may end up in the PEERWaiting status), then the peerQR*Callback() functions that were registered with peerInitialize() will be called whenever the local player is queried for his preferences. The application uses these callbacks to report the local player's preferences/settings for the AutoMatch. Any information that other players may need to decide if the local player is a suitable match should be reported.

It is entirely up the application to decide what information is needed and what information to report. Typically this would be information such as the local player's rank or rating, map preference, gametype preference, and/or the number of players to play with (maxplayers).

Because players use the reported information to decide if they want to join the local player's match, the local player must report both his own information and the information for any other players already in his staging room. This is because players that are looking for a match need to know if the match as a whole is suitable, and they may need to decide that based on all the players already in the room. For example, if one of the available settings is a yes/no preference for each of the available maps, then a user looking for a match will want to compare his preferences against the preferences of all the players already in the match.

The host of the room can report each player's preferences as a player key. Those looking for a match can then determine a score for map preferences by comparing his preferences to each of the other player's preferences. For more information on how to report this information, see the "GameSpy Peer SDK Reference" document, the "GameSpy Query and Reporting 2 SDK" document, and the Peer samples.