tilttek/quests

tilttek/quests turns the members' activity, recorded by tilttek/activity, into quests accomplished. A quest is a list of steps — play three games, read 300 pages of a rule book, publish a first sheet — done in order or in any order. It is open always, between two dates in a declared timezone, or at dates that come back, and is accomplished once per occurrence. Quests chain: accomplishing one opens the next. A member follows a quest as soon as it is open or once they accept it, and may abandon it. Besides the personal quest, three genres are built in: the challenge of the community, a collective goal everyone's activity advances — a thousand games this month —; the team quest, joined under a team towards a goal its members share; and the duel, a challenge one member sends another, won by the first to accomplish it. Rewards are declared, never executed: an accomplished quest tells the application its rewards — points, a badge, an item — and the members they go to, and the application gives them through the packages it has. Everything is replayed from the journal when a rule changes, and erasing a member removes what the quests kept of them.

It is for an application that gives its members goals to reach — a community site, a game site, a reading or writing platform, a club. tilttek/quests-bundle integrates it with Symfony, keeps the quests and their progress in Doctrine DBAL and computes seasonal dates with phil/almanac; an application without Symfony takes the library alone and writes its own stores, or uses those in memory.

It is a plain PHP library whose dependencies are tilttek/activity, the journal its steps read, phil/resource, the opaque reference of a member or a team, and psr/clock. Members are references the application gives, member:44: the library never reads a name, an e-mail or an account. It depends on no other gamification package: a site that wants only quests installs nothing else.

The design is small: a Quest holds its Steps, its Schedule, its Rewards and the quest it follows; a Catalog holds the quests; QuestProjection reads the journal, writes Contributions and Completions and decides duels; Quests accepts, abandons and reads where each quest stands; Duels sends and answers challenges; Evaluator and ProgressCalculator read a subject's progress from its contributions.

Status

Documentation

Quick start

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

Requirements

PHP 8.5 or later.

Contributing

Contributions are welcome on the PHIL monorepo: read the contribution guide and the code of conduct. Report a vulnerability privately, as the security policy explains, never in a public issue.

License

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