game-common / pragma.matchmaking / MatchmakingPlugin / matchParties /
matchParties #
open fun matchParties(queueKey: MatchmakingRpc.MatchmakingQueueKey, anchor: Matchmaking.Matchable, other: Matchmaking.Matchable): NewGameInstance?
Called during the main matchmaking loop. The anchor Matchmaking.Matchable represents a collection of parties that could form the teams for a match. Parties can be moved between the matchable and the anchor. This method is called many times, evaluating each party that has joined the matchmaking queue. When the criteria to start a new game is met, return a NewGameInstance from this method to be sent to the game server.
If an anchor Matchmaking.Matchable is compared against every other Matchmaking.Matchable in the queue without finding matches for its parties, the next matchmaking loop will select a new anchor Matchmaking.Matchable and restart comparison against all other Matchmaking.Matchable objects in queue.
Things that can be done in this method:
- Move parties between the anchor Matchmaking.Matchable and the matchable Matchmaking.Matchable by calling Matchmaking.Matchable.takePartiesFrom on either matchable. In subsequent calls to the matchParties function, any parties that were moved will be left in the matchable they were moved to.
- If a complete game can be formed with the parties presented, create and return a NewGameInstance with those players.
- Return null to continue the matchmaking loop, if the requirements to start a new game have not been met.
If returning a NewGameInstance:
- Add parties to the new game instance by calling NewGameInstance.addParty or NewGameInstance.addParties. You can optionally set their team number or use the default team number 0.
- Assign players to a team as necessary using NewGameInstance.setTeamByPlayer or NewGameInstance.setTeamByPlayers.
- Set the NewGameInstance.ext using NewGameInstance.setExtGameInstance or the constructor.
- Set the NewGameInstance.gameServerZone using NewGameInstance.setGameServerZone or the constructor.
- Call the NewGameInstance.continueMatchmaking method with a MatchmakingQueueKey if the NewGameInstance should continue to find players in a matchmaking queue after being created.
When a NewGameInstance is returned, the engine will:
- Hand off all game instance details to the GameInstance service, allowing for match allocation to begin.
- Send any players within that NewGameInstance to the game
- Remove all players that are in the match from matchmaking
If the new game instance is marked to continue matchmaking, they will be reinserted into matchmaking with the match after allocation completes.
If this method throws an exception both the anchor Matchmaking.Matchable and matchable Matchmaking.Matchable will be removed from the queue along with their players, who are notified.
Used by:
- MatchmakingService (runs forever, see MatchmakingConfig)
Parameters #
queueKey | There are separate queues for each distinct MatchmakingQueueKey. |
anchor | The current Matchmaking.Matchable that matchmaking is attempting to find compatible parties for. |
other | A set of parties to be considered from the same matchmaking queue. |