tilttek/generator

tilttek/generator tire des noms, des personnages, des auberges, des trésors, des rumeurs ou des cartes de listes et de gabarits qu'un auteur écrit en YAML ou en JSON, sans code. Une liste contient des entrées pondérées, avec des champs et des étiquettes. Un gabarit est une expression Twig dans un bac à sable : il puise dans les listes selon le poids et l'étiquette, appelle d'autres générateurs, lance des dés et façonne le texte avec les filtres de Twig et la grammaire d'une langue. Cette grammaire couvre l'élision et la contraction (le arbre → l'arbre, de el rey → del rey, di il re → del re), les articles selon le genre et le nombre, l'accord et le pluriel en français, en anglais, en espagnol, en allemand, en italien et en portugais, et toute autre langue qu'une application ajoute derrière le port Grammar. Un générateur retourne un texte, un résultat structuré (une auberge avec son nom, son aubergiste, son personnel et son menu) ou une carte (cases carrées, hexagones, ou salles reliées par des passages). Une liste peut inventer des mots nouveaux à partir de ses entrées par une chaîne de Markov au lieu de les rendre ; un générateur peut porter un état d'un tirage au suivant (une table à mémoire, pour la météo d'une campagne, un voyage ou l'exploration d'une carte), que l'appelant garde et repasse. Des tables aléatoires prêtes à tirer sont livrées dans tables/, en anglais et en français : rencontres, objets magiques, butins avec objets non identifiés, boutiques, accroches de scénario, rumeurs, oracle du jeu en solo et bonne aventure. Il ne garde de listes ni d'états pour personne, n'affiche pas de résultats et ne les sert pas : l'application tient ses propres listes, ses états et ses pages, et le bundle sert les tirages.

Elle s'adresse à tout code PHP qui crée du contenu aléatoire pour des gens : un générateur de noms, la boîte à outils d'un meneur de jeu, un oracle de jeu en solo, une table aléatoire dans un livre, un donjon pour une table virtuelle. tilttek/generator-bundle l'intègre à Symfony ; une application sans Symfony prend la bibliothèque seule.

C'est une bibliothèque PHP construite sur Twig, dont le bac à sable exécute les gabarits, sur Symfony Yaml, qui lit les fichiers, et sur tilttek/dice, qui lance les dés. Son hasard est un Random\Randomizer que passe l'appelant, ou le germe d'un tirage, qui fait revenir le même tirage. Chaque gabarit est compilé et vérifié à la construction du catalogue. Un gabarit qui ne compile pas, sort du bac à sable ou nomme une liste, une étiquette ou un générateur inexistants est alors une erreur, et non un texte vide plus tard.

La conception est sobre : un Reader ou un FileLoader donne un Catalog d'EntryList et de GeneratorDefinition, un Generator le vérifie et y fait des tirages qui donnent un DrawResult, et les classes Grammar fournissent les filtres de chaque langue ; Tables mène aux tables que livre la bibliothèque.

État

Documentation

Le répertoire examples/ contient des exemples neutres : des noms syllabiques, des noms inventés par une chaîne de Markov, un oracle oui ou non, une auberge française, un village, un donjon, et trois tables à mémoire : la météo en fleur d'hexagones, un voyage et une exploration d'hexagones.

Démarrage rapide

composer require tilttek/generator

# generators/inn.yaml
lists:
  inn.animal:
    - { text: sanglier, gender: m }
    - { text: oie, gender: f }
  inn.adjective:
    - { text: doré }
    - { text: vieux, f: vieille }
generators:
  inn.name:
    locale: fr
    templates:
      - "{% set animal = pick('inn.animal') %}{{ ('à ' ~ animal|article ~ ' ' ~ pick('inn.adjective')|agree(animal))|elide }}"
    filters: [upper_first]

use Tilttek\Generator\Draw;
use Tilttek\Generator\Generator;
use Tilttek\Generator\Loading\FileLoader;

$generator = new Generator(new FileLoader()->catalog(['generators']));

$generator->draw('inn.name', new Draw(3, unique: true))->results;   // ["À l'oie dorée", 'Au sanglier vieux', …]
$generator->draw('inn.name', new Draw(seed: 'table 7'))->first();   // the same text for the same seed

Prérequis

PHP 8.5 ou plus récent, avec l'extension mbstring.

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.