Enregistrer des résultats
tilttek/ratingUn résultat
GameResult est une partie jouée : un identifiant stable, le jeu, le moment où elle a été jouée, ses camps et le rang
de chaque camp. Un camp est un joueur ou une équipe ; le rang 1 est le premier, et les camps du même rang ont fait nulle.
GameResult::duel('play-81', 'chess', $at, 'member-1042', 'member-1077'); // the first won
GameResult::duel('play-82', 'chess', $at, 'member-1042', 'member-1077', draw: true); // a draw
GameResult::placings('play-83', 'catan', $at, [['member-7'], ['member-3', 'member-9'], ['member-5']]);
new GameResult('play-84', 'pandemic-legacy', $at, [['m-1', 'm-2'], ['m-3', 'm-4']], [2, 1]); // team 2 won
placings() liste les membres à partir de la première place, chaque place contenant ceux qui ont terminé ensemble. Un
résultat a de 2 à 64 camps de 1 à 32 membres, 256 membres au plus, chacun sur un seul camp. Les identifiants du
résultat, du jeu et des membres sont de 1 à 128 lettres, chiffres, _, ., :, @ ou -, commençant par une lettre
ou un chiffre : une référence opaque, jamais un nom.
toArray() donne le résultat en valeurs simples et fromArray() les relit, le moment en ISO 8601 avec son décalage —
ce que garde une source de résultats.
Enregistrer
$changes = $ratings->record($result);
foreach ($changes as $change) {
$change->member; $change->before; $change->after; $change->delta(); $change->peak;
}
record() refuse un résultat que son jeu compte déjà, lit la cote de chaque membre — la cote initiale pour la première partie cotée d'un membre à ce jeu —, cote le
résultat avec le système, et garde d'un coup les nouvelles cotes de tous les membres. Un changement est en centièmes :
la cote Elo, ou l'estimation prudente d'une habileté. peak est vrai quand le membre a dépassé le score le plus haut
qu'il avait atteint, une fois qu'il a joué les parties cotées que demande celebrateAfter.
Un résultat s'enregistre une fois. Le dépôt de stockage compte l'identifiant de chaque résultat qu'il a coté, jeu par
jeu, dans la même écriture que les cotes : enregistrer de nouveau le même résultat — un double clic, un message livré
deux fois — lance Exception\ResultAlreadyRecorded, ne garde rien et n'envoie rien, une fois tous les événements du
résultat remis ; tant qu'il en reste, il les envoie à la place, ne recote rien et ne renvoie aucun changement. Deux
enregistrements du même résultat en même temps ne comptent jamais tous les deux : la première écriture compte le
résultat, et la seconde est refusée, par le résultat ou par les versions des cotes. Une relecture compte de nouveau les
résultats qu'elle a cotés, à partir de sa source ; un résultat amical n'est jamais compté, donc l'enregistrer deux fois
ne change rien deux fois.
Résultats amicaux
Un résultat construit avec friendly: true est joué hors des cotes : record() ne change rien, ne garde rien et
n'envoie rien. Une relecture le lit à sa place dans l'ordre, et le saute.
Les événements
Une fois les cotes gardées, record() envoie, membre par membre dans l'ordre du résultat, Event\RatingChanged, puis
Event\PeakReached pour un membre dont le changement est un nouveau score record. Voir Célébrations.
Les événements sont gardés avec le résultat, dans la même écriture que les cotes, et chacun reste dans le dépôt de
stockage jusqu'à ce qu'il ait été envoyé sans exception. Un écouteur qui lance une exception y laisse son événement ;
les autres événements sont envoyés quand même, et la première exception est relancée une fois chaque événement essayé.
Les cotes restent gardées : l'application rattrape l'échec en enregistrant de nouveau le même résultat, ce qui envoie
les événements restants sans rien recoter, ou par deliver($game, $result), qui renvoie combien sont partis.
try {
$ratings->record($result);
} catch (ListenerFailed $failure) { // whatever the listener threw
$ratings->deliver($result->game, $result->id);
}
Un événement peut donc être envoyé plus d'une fois. Les écouteurs sont idempotents : chaque événement porte une
key(), la même chaque fois qu'il est envoyé de nouveau (chess/r1/ann/changed, chess/r1/ann/peak), et un écouteur
qui donne des points ou envoie un message le fait une fois par clé. Sans répartiteur, rien n'est gardé à remettre.