Aller au contenu

Jouer

tilttek/quiz

À son rythme

SelfPacedQuizzes::start() démarre une partie d'un jeu-questionnaire pour un membre ; answer() répond à la question courante pour ce membre et montre la suivante, dont la minuterie démarre à cet instant. Après la dernière réponse, la partie est terminée : QuizCompleted est envoyé, puis PerfectScore quand toutes les réponses étaient bonnes et dans le temps et que la partie compte.

$quizzes->start('play-7', 'lore', Player::member('member:44'));
$quizzes->answer('play-7', 'member:44', ChoiceAnswer::of('b'));   // null: the play is not over
$play = $quizzes->play('play-7', 'member:44');
$play->position();     // the current question
$play->timer($quiz);   // its timer: remaining(), deadline()
// ... the last answer returns its AnswerResult, and the play is over
$quizzes->results('play-7', 'member:44');   // list<AnswerResult>
$quizzes->result('play-7', 'member:44');    // the View\ResultView of the result template

Un invité ne joue jamais à son rythme : la partie est refusée avec QuizRefused. Une partie terminée ne prend plus de réponses.

Une partie appartient à son joueur

Chaque appel sauf start() prend le membre qui joue. answer(), play(), results() et result() refusent la partie d'un autre avec QuizRefused, comme ils refusent une partie qui n'existe pas, pour qu'un membre n'apprenne jamais que la partie d'un autre existe. L'application passe le membre de la requête, jamais un identifiant lu dans un formulaire.

Les résultats une fois la partie terminée

Les réponses d'un membre ne disent rien avant la fin de la partie : answer() renvoie null pour toutes les réponses sauf la dernière, et results() et result() refusent une partie qui n'est pas terminée. Un membre ne peut pas apprendre les bonnes réponses au milieu d'une partie pour s'en servir dans la même partie. Un jeu-questionnaire fait pour enseigner en cours de route montre chaque résultat tout de suite :

SelfPaced\FeedbackCe qu'un membre voit avant la fin
AfterPlay, par défautRien : answer() renvoie null, results() et result() sont refusés
AfterEachAnswerLe résultat de chaque réponse, renvoyé par answer(), ainsi que les résultats et le score jusqu'ici

SelfPaced\Play::results() et score() sont l'enregistrement que garde le dépôt ; une page les montre par results() et result() du service, qui appliquent la règle.

Les parties qui comptent, et l'entraînement

Une fois une partie terminée, son membre connaît les bonnes réponses ; toute partie démarrée après la première en a déjà vu les questions. Chaque partie porte sa attempt : 1 pour la première partie du membre au jeu-questionnaire, une de plus pour chaque partie qu'il a démarrée avant, terminée ou non. Seule la première compte :

SelfPaced\ReplaysLa deuxième partie d'un membre à un jeu-questionnaire
Practice, par défautJouée et notée pour que le membre la voie ; isPractice() est vrai, QuizCompleted et la vue du résultat disent practice, et PerfectScore n'est pas envoyé
RefusedRefusée avec QuizRefused : chaque membre joue chaque jeu-questionnaire une fois

PerfectScore est donc envoyé une fois au plus par jeu-questionnaire et par membre : pour la première partie, quand elle est parfaite. Un jeu-questionnaire dont l'entraînement mérite aussi des feux d'artifice règle SelfPaced\PerfectScoreRule::EveryPerfectPlay : chaque partie parfaite envoie alors PerfectScore, avec practice vrai pour celles qui ne comptent pas, pour qu'un écouteur qui attribue un insigne les laisse tout de même de côté. Deux parties démarrées en même temps ne comptent jamais toutes deux : le dépôt refuse une seconde partie à la même tentative, et start() compte de nouveau et prend la tentative suivante, jusqu'à SelfPacedQuizzes::ATTEMPTS fois.

Effacer un membre

SelfPacedQuizzes::erasePlayer() supprime toutes les parties d'un membre et renvoie combien il y en avait, quand son compte est effacé. Un membre qui joue de nouveau ensuite repart à la tentative 1 : les parties qui disaient ce qu'il avait vu disparaissent avec le compte.

En direct

L'animateur ouvre une session ; la bibliothèque tire un NIP à six chiffres qu'aucune autre session non terminée ne détient, à partir de la source sécurisée du système par défaut. Les joueurs rejoignent la session par le NIP à tout moment jusqu'à sa fin ; celui qui arrive en retard manque les questions déjà fermées. join() prend le NIP tel que le joueur l'a saisi : les espaces et les traits d'union entre les chiffres sont écartés (123 456, 123-456), et une saisie qui n'est pas faite de six chiffres ASCII une fois ceux-ci écartés, ou qui dépasse 16 octets, est refusée avec InvalidQuiz avant qu'aucun dépôt soit interrogé ; Pin::parse() la lit de la même façon pour un formulaire.

$session = $live->open('night-12', 'lore');
$live->join($session->pin, Player::member('member:44'));
$live->join($session->pin, Player::guest('guest-91', 'Pixel'));

$live->next('night-12');                                   // shows the first question to all
$live->answer('night-12', 'member:44', ChoiceAnswer::of('b'));
$live->close('night-12');                                  // the players without an answer are timed out
$live->session('night-12')->leaderboard()->top(3);
// ... next(), answer(), close() for each question
$live->finish('night-12');
ÉtatDepuisGestes
Lobbyopen()next()
Questionnext()answer() par chaque joueur une fois, close()
Reviewclose()next(), finish()
Finishedfinish()claimGuest()

Chaque joueur répond une fois à une question ; une réponse une fois le temps écoulé est refusée. Fermer une question déjà fermée ne fait rien.

GesteÉvénement, une fois la session enregistrée
Un joueur se joint pour la première foisPlayerJoined
next()QuestionShown, avec la position de la question
close() d'une question montréeQuestionClosed, avec la position de la question
finish()LiveQuizFinished, puis QuizCompleted pour chaque joueur, suivi de PerfectScore pour celui qui a bien répondu à toutes les questions, puis TeamWon pour chaque équipe gagnante, puis GuestInvited pour chaque invité

Un joueur qui se joint de nouveau, et une question déjà fermée, ne disent rien. Les écrans suivent ces gestes par les mises à jour en direct.

Les événements de la fin sont gardés dans la session terminée, dans la même version, et chacun y reste 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é. La session reste terminée : appeler finish() de nouveau envoie les événements restants, et deliver($session) fait de même et renvoie combien sont partis. Une fois tous les événements partis, finish() est de nouveau refusé.

try {
    $live->finish('night-12');
} catch (ListenerFailed $failure) {   // whatever the listener threw
    $live->deliver('night-12');
}

Un événement de la fin peut donc être envoyé plus d'une fois. Les écouteurs sont idempotents : chacun de ces événements porte une key(), la même chaque fois qu'il est envoyé de nouveau (night-12/finished, trivia/night-12/member:44/completed), et un écouteur qui donne des points ou un badge le fait une fois par clé.

Une session accepte jusqu'à 1 000 joueurs. Beaucoup de joueurs répondent en même temps : chaque réponse est une nouvelle version de la session, et LiveQuizzes relit la session et refait le changement quand une autre réponse a été enregistrée avant, jusqu'à huit fois ; voir Stockage.

Les invités

Un invité joue en direct seulement, sous un pseudonyme de 1 à 24 caractères, sans espaces aux extrémités, sans caractères de contrôle ni invisibles, pris une seule fois par session quelle que soit sa casse. L'application donne à l'invité un identifiant opaque ; le pseudonyme ne quitte jamais la session, et aucun événement ne le porte.

Une fois la session terminée, GuestInvited dit à l'application de proposer à l'invité de devenir membre. S'il accepte, LiveQuizzes::claimGuest() donne la place, l'équipe et les réponses de l'invité au membre, sauf si le membre a déjà joué la session ; la session oublie alors le pseudonyme.

Filtrer les pseudonymes

Un Contract\PseudonymFilter donné à LiveQuizzes refuse les pseudonymes que l'application ne veut pas ; sans filtre, tout pseudonyme de la bonne forme est permis. La bibliothèque en donne deux :

FiltreRefuse
Pseudonym\WordListFilter::defaults()Une courte liste à la bibliothèque, en anglais et en français : les noms qui feraient passer un invité pour l'animateur ou le personnel (admin, host, animateur, moderator…) et les insultes courantes
new Pseudonym\WordListFilter($words, $anywhere)La seule liste de l'application
Pseudonym\ChainFilterCe que refuse l'un quelconque de ses filtres, interrogés dans l'ordre

Une liste de mots met le pseudonyme et ses mots sous une forme commune avant de les comparer : minuscules, accents écartés, substitutions courantes de chiffres et de symboles lues comme des lettres (4dm1n est admin), tout ce qui n'est pas une lettre écarté. Un mot de words est refusé comme mot entier du pseudonyme, ou comme pseudonyme entier une fois ses mots joints (Ad Min) ; un mot de anywhere est refusé où qu'il se trouve, pour les termes qu'aucun mot courant ne contient. Scunthorpe, Cassandra et Salopette passent. Une liste contient jusqu'à 10 000 mots d'au plus 64 caractères ; un texte de plus de 64 caractères est refusé.

La liste de la bibliothèque est courte exprès et n'est pas de la modération : une application ajoute ses propres mots, ou un service de modération, et garde la liste de la bibliothèque devant :

use Tilttek\Quiz\Pseudonym\{ChainFilter, WordListFilter};

$filter = new ChainFilter(
    WordListFilter::defaults()->with($applicationWords, $applicationTermsAnywhere),
    $moderationService,          // a Contract\PseudonymFilter of the application
);

Les équipes

Une session peut se jouer par équipes : open($session, $quiz, ['red', 'blue', 'green']) déclare de 2 à 50 équipes, par identifiant ; l'application garde leurs noms et leurs couleurs. Un joueur se joint à l'équipe donnée, join($pin, $player, 'blue'), ou, sans équipe, à celle qui a le moins de joueurs, la première déclarée en cas d'égalité ; un joueur qui se joint de nouveau reste dans son équipe. Une session sans équipes refuse une équipe.

$session = $live->open('night-12', 'lore', ['red', 'blue'], TeamScoring::Average);
$live->join($session->pin, Player::member('member:44'), 'red');
$live->join($session->pin, Player::guest('guest-91', 'Pixel'));          // the smaller team
$live->session('night-12')->teamLeaderboard()->top(1);                    // list<Team\TeamStanding>

Chaque joueur répond toujours pour lui-même, et garde sa propre place dans leaderboard(). teamLeaderboard() classe les équipes selon le Team\TeamScoring de la session :

TeamScoringLe score et le temps d'une équipe
Total, la valeur par défautLa somme des scores et des temps de ses joueurs : une équipe plus nombreuse peut marquer davantage
AverageLeur moyenne, arrondie à l'entier le plus proche, la moitié vers le haut : les équipes de tailles différentes rivalisent à armes égales ; une équipe sans joueurs marque 0

Le score le plus élevé vient d'abord, puis le moins de millisecondes ; les équipes égales sur les deux partagent un rang (1, 1, 3). Un Team\TeamStanding contient le rang, l'équipe, son score, les réponses de ses joueurs entièrement bonnes, son temps et son nombre de joueurs. members($team) énumère les joueurs d'une équipe, teamOf($player) l'équipe d'un joueur. À la fin, TeamWon est envoyé pour chaque équipe au premier rang avec un score supérieur à 0.

Les classements

LiveSession::leaderboard() classe les joueurs : le score le plus élevé d'abord ; à scores égaux, le joueur dont les réponses qui comptent ont pris le moins de millisecondes ; les joueurs égaux sur les deux partagent un rang, et le rang suivant saute les places qu'ils occupent (1, 1, 3). Une mauvaise réponse, ou aucune, ne compte jamais dans le temps. top(3) garde les rangs jusqu'à 3, égalités à la limite comprises ; standingOf() lit la place d'un joueur.