Cette page n’est pas encore traduite : la version anglaise est affichée.

Matchmaking

Amener un joueur dans la bonne salle. Les tickets décrivent le joueur et filtrent les autres. Le matchmaker détermine un placement, réserve une place, puis le trafic de jeu va directement à la salle.

Le matchmaker n’intervient qu’une fois, pour décider où vous devez aller. Il ne se trouve pas sur le chemin du match : il produit un placement et une réservation de place (seat) limitée dans le temps, et dès l’arrivée le trafic de jeu va droit à la salle. Une file d’attente chargée ne ralentit donc jamais une partie.

Quand l’utiliser

• Vous devez acheminer les joueurs vers des salles selon des critères déclarés (mode, région, rang), et non au moyen d’une liste de lobbies faite maison.
• Les critères d’appariement doivent venir des données de la plateforme, pas de ce qu’affirme le client : inscrivez le rang dans le hook qui précède la mise en file.
• Les files doivent s’élargir avec le temps, côté serveur, pendant que le client garde un seul ticket et n’interroge jamais le serveur.
• Les groupes de joueurs (party) doivent arriver ensemble dans le même match : un groupe entre en entier ou pas du tout.
• Vous utilisez un matchmaker externe et avez seulement besoin que sa décision aboutisse à un placement et à une réservation de place.
• Inutile quand les joueurs choisissent eux-mêmes leur session : la liste des salles et Join suffisent.

Qui fait quoi

En bref

// client — one call for the common case
var seat = await playserv.Matchmaking.Find("ranked-duo");
var room = await playserv.Rooms.Join(seat);

// client — one call for the common case
const seat = await playserv.matchmaking.find('ranked-duo');
const room = await playserv.rooms.join(seat);

# client — one call for the common case
seat = await playserv.matchmaking.find("ranked-duo")
room = await playserv.rooms.join(seat)

// client — one call for the common case
Client->Matchmaking->Of<FRankedDuo>()->Tickets->Create(FPSTicketClaim{ .Mode = TEXT("duo") },
    TPSOnResult<FPSTicket*>::CreateWeakLambda(this, [this](const TPSResult<FPSTicket*>& TicketResult)
    {
        if (!TicketResult.HasValue()) { return; }
        // the seat arrives as the ticket's outcome
        TPSSubscription Placement = TicketResult.Value()->Subscribe([this](const FPSSeat& Seat)
        {
            Client->Rooms->Join(Seat,
                TPSOnResult<FPSRoom*>::CreateWeakLambda(this, [this](const TPSResult<FPSRoom*>& JoinResult)
                {
                    if (!JoinResult.HasValue()) { return; }
                    EnterMatch(JoinResult.Value());
                }));
        });
    }));
// co_await support ships later: a built-in SDK coroutine wrapper that respects Unreal's GC and threading.

// client — one call for the common case
var seat = await playserv.Matchmaking.Find("ranked-duo");
var room = await playserv.Rooms.Join(seat);

[Matchmaker("ranked-duo")]
public static class RankedDuo
{
    public static Size Size = Size.Exactly(4, multiple: 2);
    public static string Filter = "mode == 'duo' && region == self.region";
    public static Relax[] Relax =
    {
        Relax.After(15.Seconds(), "abs(rank - self.rank) < 300"),
        Relax.After(45.Seconds(), "abs(rank - self.rank) < 800"),
    };
}

@Matchmaker('ranked-duo')
export class RankedDuo {
  static size = Size.exactly(4, { multiple: 2 });
  static filter = "mode == 'duo' && region == self.region";
  static relax = [
    Relax.after(seconds(15), 'abs(rank - self.rank) < 300'),
    Relax.after(seconds(45), 'abs(rank - self.rank) < 800'),
  ];
}

@matchmaker("ranked-duo")
class RankedDuo:
    size = Size.exactly(4, multiple=2)
    filter = "mode == 'duo' && region == self.region"
    relax = [
        Relax.after(seconds(15), "abs(rank - self.rank) < 300"),
        Relax.after(seconds(45), "abs(rank - self.rank) < 800"),
    ]

USTRUCT(PSMatchmaker = (Name = "ranked-duo", Size = "Exactly:4", Multiple = 2,
                       Filter = "mode == 'duo' && region == self.region"))
struct FRankedDuo
{
    GENERATED_BODY()

    UPROPERTY(PSRelax = (After = "15s", Filter = "abs(rank - self.rank) < 300")) FPSRelax First;
    UPROPERTY(PSRelax = (After = "45s", Filter = "abs(rank - self.rank) < 800")) FPSRelax Second;
};
// declarations compile into the same pushed model — playserv push from the UE project or CI

[Matchmaker("ranked-duo")]
public static class RankedDuo
{
    public static Size Size = Size.Exactly(4, multiple: 2);
    public static string Filter = "mode == 'duo' && region == self.region";
    public static Relax[] Relax =
    {
        Relax.After(15.Seconds(), "abs(rank - self.rank) < 300"),
        Relax.After(45.Seconds(), "abs(rank - self.rank) < 800"),
    };
}

Les critères qu’on ne peut pas confier au client sont inscrits dans le hook qui précède la mise en file :

[Before(Matchmaking.Enqueue)]                     // the server has the last word
public static async Task<Ticket> StampRank(Ticket t)
{
    var rows = await PlayServ.Leaderboards.ForOwners("ranked", new[] { t.Player });
    t.Properties["rank"] = rows[0].Rank;          // the row carries its rank in the full table
    return t;
}

// the server has the last word
export const stampRank = before(Matchmaking.enqueue, async (t: Ticket) => {
  const rows = await PlayServ.leaderboards.forOwners('ranked', [t.player]);
  t.properties.rank = rows[0].rank;               // the row carries its rank in the full table
  return t;
});

@before(matchmaking.enqueue)                      # the server has the last word
async def stamp_rank(t: Ticket) -> Ticket:
    rows = await playserv.leaderboards.for_owners("ranked", [t.player])
    t.properties["rank"] = rows[0].rank           # the row carries its rank in the full table
    return t

Cette lecture est la lecture par liste de propriétaires de Leaderboards — celle qu’utilise une cohorte d’amis —, et chaque ligne renvoyée porte le rang de son propriétaire dans le classement (leaderboard) complet. Le hook peut demander la ligne de quelqu’un d’autre parce que le prédicat du classement l’autorise pour une fonction cloud ; une session joueur qui pose la même question n’obtient que la sienne.

Le modèle

Ce que porte un ticket.

Le participant d’un ticket est un acteur ou un groupe : un groupe entre en entier, et c’est précisément cela, un groupe de joueurs. Son ticket est indivisible : le groupe entre tout entier dans une composition (roster), ou pas du tout.

Ce que déclare un type de file.

Les états d’un ticket. created → queued → matched · cancelled · expired, les trois derniers étant terminaux.

Erreurs

• Un second ticket dans la même file est un conflit ; ne réessayez pas, lisez le ticket existant.
• Une propriété non déclarée, ou une exigence qui en nomme une, est un échec de validation — et non un oubli silencieux qui ressurgirait plus tard sous la forme « aucun adversaire trouvé ».
• Une file suspendue répond unavailable, pas forbidden : les droits de l’appelant sont intacts et la situation est temporaire ; il faut donc réessayer en espaçant les tentatives.
• Une salle impossible à créer pour le résultat répond de même unavailable, à réessayer en espaçant les tentatives.
• Une réservation qui échoue est un conflit qui mérite un nouvel essai : le ticket reste dans la file.
• Un ticket introuvable ou appartenant à quelqu’un d’autre, comme un acteur qu’un prédicat n’admet pas dans la file, répondent not found : un refus ne révèle ni le ticket ni la file.

Limites

Les chiffres viendront avec le chapitre sur les limites de la plateforme ; ce qui se passe à chaque plafond, lui, est déjà fixé.

• Tickets dans une file : la création est refusée comme conflit, et les tickets existants ne sont pas évincés pour faire de la place.
• La durée de vie d’un ticket : un passage à expired avec un événement.
• Paliers de l’échelle : une déclaration qui en compte trop est refusée dès la déclaration.
• Taille du groupe dans un ticket : le ticket est refusé comme échec de validation.
• Propriétés déclarées par type de file : refusées dès la déclaration.
• Rythme de création de tickets : un refus pour limite de débit, avec une échéance.
• Rétention de l’historique de matchmaking : passée la période déclarée, une entrée n’est plus lisible.