Aller au contenu

tilttek/rating

✅ publié

Des cotes par jeu pour les joueurs, tirées de leurs résultats : Elo avec un K décroissant, OpenSkill avec Plackett-Luce ou Thurstone-Mosteller et un classement prudent, privées par défaut et publiques avec le consentement du membre.

Une cote mesure la force d'un membre à un jeu par rapport aux membres qu'il a affrontés : elle monte avec une victoire contre un camp plus fort et baisse avec une défaite contre un camp plus faible. Chaque jeu a ses propres cotes, dans un seul système de cotes :

  • Elo, d'abord pour les duels : un facteur K configurable, fixe ou décroissant à mesure qu'un membre joue et monte ; les parties de plusieurs joueurs et les parties par équipes lues par paires de camps ; les nulles.
  • OpenSkill, l'approximation bayésienne de Weng et Lin, pour un nombre quelconque de joueurs ou d'équipes : une habileté et son incertitude, le modèle Plackett-Luce ou le modèle Thurstone-Mosteller, et un classement ordonné par l'estimation prudente mu − 3 × sigma, de sorte qu'un nouveau venu monte à mesure que l'incertitude diminue.

Une cote est privée par défaut : seul le membre la voit jusqu'à ce qu'il la rende publique, et seules les cotes publiques figurent au classement ; une cote après peu de parties est marquée provisoire, et le classement peut l'omettre. Chaque résultat n'est compté qu'une fois : l'enregistrer de nouveau est refusé. Un résultat amical est joué hors des cotes et ne change rien. Les membres sont désignés par des identifiants stables et opaques, jamais par un nom. Les cotes sont gardées en nombres entiers d'une virgule fixe, arrondis une fois par jeu : rejouer les résultats d'un jeu à partir de leur source donne donc les mêmes cotes à chaque fois — après une correction, un résultat supprimé ou un changement de système.

Le paquet s'adresse à une application qui tient des soirées de jeu, un classement de club ou des tables en ligne et veut un niveau pour chaque joueur, montré avec soin. C'est une bibliothèque PHP simple : le dépôt de stockage et la source des résultats sont ceux de l'application ; un résultat coté envoie des événements que l'application écoute, pour montrer le changement ou jouer une célébration quand une cote atteint un nouveau sommet.

État

PartieÉtat
Ratings : l'enregistrement de chaque résultat une fois, les résultats amicaux, les cotes provisoires, le classement avec ou sans elles, la publication et le masquage, la relecture, l'export et l'effacementImplémenté et testé
GameResult : les duels, les rangs de plusieurs joueurs, les parties par équipes, les nulles, écrits et lus en valeurs simplesImplémenté et testé
Elo\EloSystem, Elo\KFactor, Elo\KFactorStep : Elo avec un K fixe ou décroissant, une échelle et un plancherImplémenté et testé
OpenSkill\OpenSkillSystem : Plackett-Luce et Thurstone-Mosteller, l'estimation prudenteImplémenté et testé
MemberRating, Visibility, RatingChange : la cote d'un membre telle qu'elle est stockée, privée par défautImplémenté et testé
Contract\RatingStore, Store\InMemoryRatingStore, Contract\PlaySourceImplémenté et testé
Event\RatingChanged, Event\PeakReached : les moments d'une célébrationImplémenté et testé
Exceptions sous une seule interface RatingExceptionImplémenté et testé
Une source de résultats qui lit tilttek/play-logNon fournie : tilttek/play-log n'est pas encore écrit ; l'application implémente Contract\PlaySource
Glicko-2Non fourni

Documentation

DocumentContenu
InstallationLes prérequis, l'installation et le branchement.
Enregistrer des résultatsLes résultats, les camps et les rangs, chaque résultat enregistré une fois, les résultats amicaux, les changements et les événements.
EloLa formule, le facteur K, les parties de plusieurs joueurs et d'équipes, l'échelle et le plancher.
OpenSkillLes habiletés et l'incertitude, les deux modèles, les réglages et l'estimation prudente.
Vie privée et classementPrivé par défaut, la publication, le classement, les cotes provisoires, l'export et l'effacement.
RejouerLa source des résultats, le déterminisme et le changement de système.
CélébrationsLes événements d'un changement de cote et d'une nouvelle cote record, avec le kit PHIL UX.
StockageLe contrat du dépôt de stockage, les versions et les résultats concurrents.
Points d'extensionCe qu'une application donne à la bibliothèque.
ExceptionsRatingException et ses exceptions, avec leurs messages.
TestsLes tests de la bibliothèque, sa cible de fuzzing et ses bancs d'essai.
RéférenceChaque type de la bibliothèque, avec son rôle.

Démarrage rapide

use Tilttek\Rating\Elo\{EloSystem, KFactor};
use Tilttek\Rating\{GameResult, Ratings};
use Tilttek\Rating\Store\InMemoryRatingStore;

$ratings = new Ratings(new InMemoryRatingStore(), new EloSystem(KFactor::chess()));

$ratings->record(GameResult::duel('play-81', 'chess', new DateTimeImmutable(), 'member-1042', 'member-1077'));
$ratings->rating('chess', 'member-1042')->value();     // 1520.0, seen by the member alone
$ratings->publish('chess', 'member-1042');             // on the member's own choice
$ratings->standings('chess');                          // the public ratings, highest first

Prérequis

PHP 8.5 ou une version plus récente et psr/event-dispatcher.

Contribuer

Les contributions sont les bienvenues sur le monodépôt de PHIL : lisez le guide de contribution et le code de conduite, en anglais. Signalez une vulnérabilité en privé, comme l'explique la politique de sécurité, jamais dans un ticket public.

Licence

MIT, © Philippe Gamache, doing business as Le Gnome Archiviste; a Tilttek project. Voir LICENSE.