Matchmaking
The module PulseOnlineMatchmaking matches players through queues. A queue is a data asset with the game mode, the teams, rules for the search and, optionally, a skill rating (Weng-Lin, as in OpenSkill) with optional rating features (placement matches, seasons, rank tiers, …). Rules, features, the rating model and the place where ratings are kept are instanced structs, so a game picks what it needs and adds its own in C++.
How a ticket works (session search, the default without a matchmaking service):
StartMatchmaking(Player, Queue)reads the ratings of the player (and of the party when the player leads one).- It searches game sessions of the queue. The rules filter and score them; the best one is joined.
- Nothing fits: it waits
Search Interval Secondsand searches again. Rules open up over the waiting time (wider rating window, higher ping, other regions). - After
Host After Secondsit hosts a match itself and advertises the queue, its rating, region and pool, so the next players find it. WithHost After Seconds< 0 it never hosts (dedicated servers only). Timeout Secondsends the ticket;CancelMatchmakingcancels it.
A party leader matches the whole party: the ticket runs the party matchmaking request (reservations for every member, members follow, see Party). Members cannot start a ticket.
Matchmaking service
A backend, an extension or a service provider can bring a matchmaking service (IPulseOnlineMatchmakingService: FlexMatch, PlayFab, a service of the game). It takes tickets: StartTicket with FPulseOnlineMatchmakingTicketParams (local user, other party members, queue name, match size, attributes) and reports Queued, Searching and exactly once Found, Failed or Cancelled; CancelTicket cancels.
Each queue picks its Matchmaker:
| Matchmaker | Meaning |
|---|---|
| Auto (default) | Tickets at the matchmaking service when the backend has one, else the session search. |
| Session Search | Always the session search of this page, also with a service (casual queues next to ranked ones at a service). |
| Service | Only the service; without one the request fails with Pulse.Result.Failure.Online.NotSupported. |
After the ratings the matchmaking request starts the ticket with MakeTicketParams and does what the found match (FPulseOnlineMatchmakingMatch) says:
| Action | What happens |
|---|---|
| Join Session | Joins Session (a join request of the request class table). A failed join ends the ticket. |
| Travel | Travels to ConnectAddress (a server the service started) when bTravel is set. In a party the address goes to the members through the party data (PULSE_PARTY_MATCH_ADDRESS) and they travel there too. |
| Host Session | Hosts with PrepareHostRequest; the match Attributes go into the session (ExtraSettings, keys not starting with PULSE_). |
bUsedService, TicketId and Match of the request tell what happened; the states of the request are the same (Searching while the ticket runs, then Joining or Hosting, Found). A party leader holds the ticket for the whole party (PartyMembers); the found match goes through the party matchmaking request, which reserves slots and publishes it to the party, so the members follow as with the search. While the ticket waits the party is in the state Matchmaking; a member that leaves (or joins) ends the ticket with Pulse.Result.Failure.Cancelled, start it again for the new party. A failed ticket answers with the reason of the service, a cancelled request cancels its ticket (also during the join or host step of a found match), and a service that does not answer within TimeoutSeconds of the queue fails with Timeout. A HostRequest of the caller gets the queue and match settings only for the ticket and is handed back without them. bTravel off keeps the leader of a party where it is; the members still follow.
The same rating features write into the ticket: the attributes carry Pulse.Rating.Mu (the search rating of the player or the party), Pulse.Rating.Sigma (the mean uncertainty), Pulse.Region, Pulse.GameMode and Pulse.PartySize. ReportMatchResult works the same with either matchmaker.
Blueprint: Ticket parameters for a matchmaking service
- Queue asset:
Matchmaker=Service(orAutoto use the service only when the backend has one). - Blueprint child of
Pulse Online Matchmaking Request→ overrideMake Ticket Params:Parent: Make Ticket Params→Attributes→Add(KeyMap, Value = the map the player picked) → return. - Project Settings > Pulse > Online > Request Classes:
Pulse Online Matchmaking Request→ the Blueprint. Start Matchmaking→Execute Online Request→ Success →Used Service,Match(Action, Connect Address) of the request.
Hooks
The matchmaking request has two Blueprint native events (override in a Blueprint child or in C++ with _Implementation, put the class into the request class table):
| Hook | Purpose |
|---|---|
PrepareHostRequest | The host request of the ticket (HostRequest, else one of the table) with the queue settings. |
MakeTicketParams | What a ticket at the matchmaking service asks for; add the rules of your service. |
The search of a ticket is a UPulseOnlineMatchmakingSearchRequest with the hooks of the find request (Sessions).
Ratings are written only by a server, by default only by a dedicated server (Rated Results Only On Dedicated Server): matches on listen servers are unrated, because the host could change the result.
Queues
Create a data asset of type Pulse Online Queue Definition (Primary Asset Type PulseOnlineQueue):
| Property | Meaning |
|---|---|
| Queue Tag | Pulse.Online.Queue.*; identifies the queue (advertisement PULSE_MM_QUEUE, lookups, stat names). |
| Game Mode | Advertised as GAMEMODE; used by the Game Mode rule. |
| Team Count, Team Size | Teams of a match; team balancing and the simulation use them. |
| Matchmaker | Auto, Session Search or Service (Matchmaking service). |
| Use Lobbies | Player hosted lobbies (true) or dedicated server sessions (false). |
| Search Interval / Host After / Timeout Seconds | Timing of the ticket (see above). |
| Host Map ID | Map of matches the ticket hosts; empty creates the session in the current world. |
| Rules | Search rules (below). |
| Rating Model | Empty: the queue is unrated. Default: Weng-Lin. |
| Rating Features | Optional building blocks (below). |
| Rating Store | Where ratings are kept; empty uses the store of the settings (online stats). |
| Stat Prefix | Prefix of the rating stats; default PULSE_MMR_<last part of the tag>. |
| Party Rating Mode, Weighted Top Share, Party Spread Penalty | How a party’s rating is computed. |
Queues listed in the settings (Queues) or registered with RegisterQueue are found by tag (FindQueue).
| Setting | Default | Meaning |
|---|---|---|
| Enable Matchmaking | true | Creates UPulseOnlineMatchmakingSubsystem. |
| Queues | – | Queues found by tag. |
| Region | – | Region of this player (Region rule). -PulseRegion= wins. |
| Rated Results Only On Dedicated Server | true | Listen server matches are unrated. |
| Rating Store | Online Stats | Default rating store. |
| Server Queue | – | Queue a dedicated server serves and advertises. -PulseQueue= wins. |
Rules
| Rule | What it does |
|---|---|
| Game Mode | Only sessions with the same GAMEMODE (default: the queue’s game mode). |
| Region | Own region first (PULSE_MM_REGION), any region after Any Region After Seconds; same region scores better. |
| Ping | Maximum ping from Start Max Ping to End Max Ping over Widen Seconds; lower ping scores better. |
| Rating Window | Only sessions whose rating (PULSE_MM_RATING) is within the window around the own rating; the window opens from Start Window to End Window. Closer ratings score better. Hosts advertise their rating. |
| Fill | Prefers fuller (or emptier) sessions. |
Own rules derive from FPulseOnlineMatchRule:
USTRUCT(DisplayName = "Same Build")
struct FMyMatchRule_SameBuild : public FPulseOnlineMatchRule
{
GENERATED_BODY()
virtual void AddSearchFilters(const FPulseOnlineMatchContext& Context, TMap<FName, FPulseOnlineSearchFilter>& Filters) const override
{
Filters.Add(TEXT("MY_BUILD"), FPulseOnlineSearchFilter::Make(FPulseOnlineSetting::Make(GetBuildId())));
}
virtual void AddHostSettings(const FPulseOnlineMatchContext& Context, TMap<FName, FPulseOnlineSettingAdvertisement>& Settings) const override
{
Settings.Add(TEXT("MY_BUILD"), FPulseOnlineSettingAdvertisement::Make(FPulseOnlineSetting::Make(GetBuildId())));
}
};
ScoreResult checks and scores a found session on the client (return false to drop it); AcceptsPair is used by the simulation, which has no sessions. The context (FPulseOnlineMatchContext) has the queue, the waiting time, the search rating, the party size, the region and the pool. With OSSv2 (add-on PulseOnlineOSSv2), declare the PULSE_MM_* attributes (and your own) in the attribute schema.
Skill rating
The default model is Weng-Lin with Plackett-Luce (the model of OpenSkill): every player has a rating with a mean Mu (skill) and an uncertainty Sigma. It rates teams of any size, any number of teams, placements (battle royale) and draws. New players start with a high Sigma, so their first matches move them quickly.
- Search rating:
Mu. A party usesParty Rating Mode(average, maximum, or average weighted towards the best member) plusParty Spread Penaltyper point between best and worst member. - Shown rating:
(Mu - 3 Sigma) * Display Scale + Display Offset(e.g. scale 40 and offset 1000 for numbers around 1000); rank tiers use it. - Win probability and match quality:
PredictWinandGetMatchQualityof the model, for picking between candidates and for UI. - Team balancing:
BalanceTeams(Queue, Players)splits players into teams with equal rating sums; players with the sameGroup(a party) stay together.
Own models derive from FPulseOnlineRatingModel (Rate, PredictWin, GetMatchQuality, GetDisplayRating, GetSearchRating, GetDefaultRating). The math of the default model is in Pulse::Online::Rating.
Reporting results
The server reports a finished match:
FPulseOnlineMatchResult Result;
Result.TeamPlacements = { 0, 1 }; // team 0 won, team 1 lost; equal placements are a draw
for (APlayerState* Player : GameState->PlayerArray)
{
FPulseOnlineMatchPlayerResult& Entry = Result.Players.AddDefaulted_GetRef();
Entry.UserId = Player->GetUniqueId();
Entry.Team = GetTeamOf(Player);
Entry.bLeft = HasLeftEarly(Player); // leaver feature
}
UPulseOnlineMatchmakingSubsystem::Get(this)->ReportMatchResult(Queue, Result);
The request reads the ratings of all players, applies the model and the features, writes the new ratings and broadcasts OnRatingChanged and the message Pulse.Message.Online.RatingChanged (FPulseOnlineRatingChangedMessage). OldRatings and NewRatings of the request hold the values in the order of Result.Players.
Where ratings are kept
| Store | Content |
|---|---|
| Online Stats (default) | Stats of the online service (module PulseOnlineStats): <Prefix>_MU, _SIGMA (times 1000), _GAMES, _SGAMES, _SEASON, _LAST. Create them in the service portal with aggregation latest (EOS: LATEST). Clients read; the server writes through the server stats service (EOS: PulseOnlineEOS with a trusted server client). |
| Memory | In the game instance; for tests, LAN or servers without online stats. Lost on shutdown. |
Own stores derive from FPulseOnlineRatingStore (Load, Save), e.g. a bridge to a save system.
Rating features
All optional, per queue:
| Feature | What it does |
|---|---|
| Placement Matches | The first Placement Matches matches move Mu Mu Change Multiplier times as much. |
| Inactivity | After Grace Days without a match Sigma grows by Sigma Per Day per day (up to the start Sigma). |
| Seasons | When Current Season changes, Mu is pulled towards the start (Keep Share) and Sigma raised; season matches start at 0. |
| Rank Tiers | Tiers (name, minimum shown rating, tag, icon) from the shown rating; “Unranked” until Matches Before Ranked season matches. GetRatingDisplay returns them. |
| Newcomer Pool | Parties of players with fewer than Newcomer Matches matches search and host in their own pool. |
| Smurf Detection | New accounts that gain more than Suspicious Mu Gain Per Match per match get a higher Sigma. |
| Leaver Penalty | A player with bLeft gains nothing and loses Extra Mu Penalty. |
Own features derive from FPulseOnlineRatingFeature and override any of PrepareRating (after reading), PrepareSearch (search rating, pool), PrepareMatchResult, AdjustNewRating and FillDisplay.
Dedicated servers
A dedicated server serves one queue (Server Queue or -PulseQueue=Pulse.Online.Queue.Ranked): after every login and logout it advertises the queue and the average rating of its players (UpdateServerAdvertisement). For the first advertisement add the queue to the host request of the server with AddQueueAdvertisement(HostRequest, Queue, Context). Set Use Lobbies of the queue to false and Host After Seconds to -1, so players only join servers.
Simulation
Open a queue asset and press Run Simulation (category Simulation): simulated players with a hidden true skill play the queue (Region and Rating Window rules, balanced teams, results from skill plus noise, the queue’s model and features). The summary shows waiting times, match quality, how often the favourite won and how well the ratings follow the true skill; the full report (Markdown and JSON) is written to Saved/PulseOnline/Matchmaking. In a running game the cheat PulseOnlineSimulateQueue does the same; in C++ call Pulse::Online::Matchmaking::RunSimulation.
The report also splits the players by their hidden true skill into skill bands of the same size (Skill Band Count, 5 by default, weakest first). Per band it gives the average and 90th percentile wait, the match quality, how often its players won and the skill gap (how far a player’s true skill is from the average of the others in his matches). The spreads say how fair the queue is: Wait Spread Seconds (highest minus lowest band wait), Win Rate Spread and Quality Spread. Quality Over Time is the match quality in ten parts of the run, first to last: it rises while the ratings settle. The same seed gives the same report.
Queue workshop
A queue opens in the config workshop: the tree shows its sections, rules and rating features (rules and features as cards). The preview Simulation plays the queue with its Simulation settings when it opens and after every finished change:
- Wait per skill band: average wait as bars, the 90th percentile as a line, weakest band left.
- Fairness per skill band: win rate and match quality in percent; the marker is the win rate of fair matches (100 % / team count). A queue without rating, or with a narrow player pool, shows strong bands winning more.
- Match quality over the run: the ten parts of
Quality Over Time. - A table of the bands (true skill range, players, matches, waits, won, quality, skill gap).
- Before and After: Keep as Before keeps the current run; after a change of the queue the rows show the kept run faint and the new one bright (matches, waits, spreads, quality, favourite, correlation).
- Where used: the assets that reference the queue.
- Run Again plays it again, Write Report also writes the Markdown and JSON files.
The workshop only simulates: it changes neither the queue nor a running game, and matchmaking never adjusts itself to the players. Matchmaking has no difficulty knob, so the workshop has no values per difficulty level.
Testing
- Specs:
PulseOnline.Matchmaking(rating math, rules, features, simulation with skill bands, Mock flows, the Matchmaker of a queue with a test service: join, travel, host, failure, cancel, party ticket);PulseOnline.Editor.QueueWorkshop(chart data of the queue workshop, Before and After, registration). PulseOnlineStatusnames the matchmaker of the backend (service and its source, or the session search).- Cheats:
PulseOnlineMatchmake,PulseOnlineMatchmakeCancel,PulseOnlineRating,PulseOnlineReportMatch,PulseOnlineSimulateQueue(see Debugging). Without a queue argument they use the debug queuePulse.Online.Queue.Debug(rated 1v1, hosts after 5 s). - PIE with the Mock backend (listen server + client):
PulseOnlineMatchmakeon the server hosts after 5 s, on the client joins;PulseOnlineReportMatch Debug 0 Forcerates the match on the listen server.