Aller au contenu

tilttek/luck-tokens

✅ publié

Jetons de chance, d'inspiration ou de destin qu'une table distribue et dépense, chaque mouvement dans un registre en ajout seulement.

Un meneur de jeu distribue un jeton pour un plan astucieux ; un joueur le dépense pour relancer ; un autre passe un bonus à un ami en difficulté ; au début de la session suivante, les points de destin remontent jusqu'à leur rafraîchissement. Chaque table dit quels jetons elle distribue — leur nom, combien un détenteur en garde au plus, s'ils se conservent d'une session à l'autre et comment ils se rafraîchissent, qui peut les accorder et s'ils passent d'un détenteur à un autre — et la bibliothèque garde chaque mouvement dans le registre de la table, qui ne fait que grandir, pour que le meneur de jeu et les joueurs vérifient chaque jeton.

Un solde ne tombe jamais sous zéro ni ne dépasse son plafond. Chaque opération porte un identifiant choisi par l'appelant : envoyée de nouveau — un double clic, une requête reprise —, elle n'écrit rien de plus et redonne ce qu'elle avait écrit. Deux opérations simultanées sur la même table n'écrivent pas toutes les deux après la même entrée : la seconde relit le registre et est vérifiée de nouveau. Une fois écrits, un octroi, une dépense, un transfert ou le début d'une session sont répartis comme un événement, pour qu'un lanceur de dés offre sa relance ou qu'une tour de dés montre le jeton dépensé. Toute heure est écrite en UTC. Un membre qui part est effacé de chaque registre sous un pseudonyme, les soldes des autres inchangés.

C'est une bibliothèque PHP simple. L'application garde les règles et le registre dans son propre stockage, par deux ports, et la bibliothèque fournit un stockage en mémoire de chacun. Les jetons ne sont pas des points : ils ne se gagnent pas par l'activité et ne s'échangent pas.

État

PartieÉtat
LuckTokens : octrois, dépenses, transferts et début d'une session, idempotents, vérifiés selon les règlesImplémenté et testé
TokenKind, TableRules : les sortes de jetons d'une table, leur plafond, leur conservation, leur rafraîchissement, leurs octrois et leurs transferts ; lus à partir de JSONImplémenté et testé
Ledger\LedgerEntry, Ledger\EntryType, Receipt, Balance : le registre en ajout seulement et ce qu'une opération a écritImplémenté et testé
Event\TokensGranted, TokensSpent, TokensTransferred, SessionStarted, répartis par PSR-14Implémenté et testé
eraseHolder() : un membre effacé sous un pseudonyme, et Event\HolderErasedImplémenté et testé
Contract\TokenRules, Contract\TokenLedger, Contract\HolderAccess, avec des stockages en mémoireImplémenté et testé
Exceptions sous une seule interface LuckTokensExceptionImplémenté et testé

Documentation

DocumentContenu
InstallationLes prérequis, l'installation et le câblage.
UtilisationLes sortes de jetons, octroyer, dépenser, passer, les sessions, lire le registre, et effacer un membre.
AccessibilitéAfficher les soldes et annoncer ce qui change.
Points d'extensionLes ports, écrire un registre, et les événements.
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, et ses exceptions.

Démarrage rapide

use Phil\Resource\ResourceReference;
use Tilttek\LuckTokens\LuckTokens;
use Tilttek\LuckTokens\Store\InMemoryTokenLedger;
use Tilttek\LuckTokens\Store\InMemoryTokenRules;
use Tilttek\LuckTokens\TableRules;

$table = ResourceReference::of('table', '12');
$gm = ResourceReference::of('member', '7');
$ana = ResourceReference::of('member', '8');

$rules = new InMemoryTokenRules();
$rules->save(TableRules::fromJson($table, '{"kinds": [{"key": "inspiration", "name": "Inspiration", "cap": 1}],
    "game_masters": ["member:7"]}'));
$tokens = new LuckTokens($rules, new InMemoryTokenLedger(), $eventDispatcher);

$tokens->grant($table, 'inspiration', $ana, 1, $gm, 'op-01J2', 'A clever plan');
$tokens->spend($table, 'inspiration', $ana, 1, $ana, 'op-01J3', 'Reroll the attack');
$tokens->log($table);   // both entries, for the audit

Prérequis

PHP 8.5 ou une version plus récente, phil/resource 0.1, psr/clock, psr/event-dispatcher et symfony/clock.

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.