tilttek/quests

tilttek/quests transforme l'activité des membres, enregistrée par tilttek/activity, en quêtes accomplies. Une quête est une liste d'étapes (jouer trois parties, lire 300 pages d'un livre de règles, publier une première fiche) faites dans l'ordre ou dans n'importe quel ordre. Elle est ouverte en tout temps, entre deux dates dans un fuseau horaire déclaré, ou à des dates qui reviennent, et elle est accomplie une fois par occurrence. Les quêtes s'enchaînent : en accomplir une ouvre la suivante. Un membre suit une quête dès qu'elle est ouverte ou une fois qu'il l'accepte, et peut l'abandonner. En plus de la quête personnelle, trois genres sont intégrés. Le défi de la communauté est un objectif collectif que fait avancer l'activité de tout le monde (mille parties ce mois-ci). La quête d'équipe se rejoint sous une équipe, vers un objectif que partagent ses membres. Le duel est un défi qu'un membre lance à un autre, gagné par le premier qui l'accomplit. Les récompenses sont déclarées, jamais exécutées : une quête accomplie indique à l'application ses récompenses (des points, un badge, un objet) et les membres à qui elles vont, et l'application les donne par les paquets qu'elle a. Tout est rejoué à partir du journal quand une règle change, et effacer un membre retire ce que les quêtes ont gardé de lui.

Elle s'adresse à une application qui donne des objectifs à atteindre à ses membres : un site communautaire, un site de jeux, une plateforme de lecture ou d'écriture, un club. tilttek/quests-bundle l'intègre à Symfony, garde les quêtes et leur progression dans Doctrine DBAL et calcule les dates saisonnières avec phil/almanac. Une application sans Symfony prend la bibliothèque seule et écrit ses propres magasins, ou utilise ceux en mémoire.

C'est une bibliothèque PHP simple dont les dépendances sont tilttek/activity, le journal que lisent ses étapes, phil/resource, la référence opaque d'un membre ou d'une équipe, et psr/clock. Les membres sont des références que donne l'application, member:44 : la bibliothèque ne lit jamais un nom, un courriel ou un compte. Elle ne dépend d'aucun autre paquet de ludification : un site qui ne veut que des quêtes n'installe rien d'autre.

La conception est petite : une Quest contient ses Step, son Schedule, ses Reward et la quête qu'elle suit ; un Catalog contient les quêtes. QuestProjection lit le journal, écrit les Contribution et les Completion, et départage les duels. Quests accepte, abandonne et lit où en est chaque quête. Duels lance les défis et y répond. Evaluator et ProgressCalculator lisent la progression d'un sujet à partir de ses contributions.

État

Documentation

Démarrage rapide

composer require tilttek/quests

use Tilttek\Quests\InMemoryCatalog;
use Tilttek\Quests\QuestReader;

$catalog = InMemoryCatalog::fromArray([
    'first-steps' => [
        'ordered' => true,
        'steps' => [['code' => 'play', 'verbs' => ['game.played'], 'count' => 3], ['code' => 'write', 'verbs' => ['sheet.published']]],
        'rewards' => [['kind' => 'points', 'code' => 'xp', 'amount' => 50]],
    ],
    'thousand-games' => ['kind' => 'community', 'opens' => '2026-12-01', 'closes' => '2027-01-01', 'steps' => [['verbs' => ['game.played'], 'count' => 1000]]],
], new QuestReader('America/Toronto'));

// Wire QuestProjection to the journal, then read:
$quests->status($member, 'first-steps')->progress->done(); // 1

Prérequis

PHP 8.5 ou plus récent.

Contribuer

Les contributions sont les bienvenues sur le monodépôt de PHIL : lisez le guide de contribution et le code de conduite. 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.