Instructions et résultats

Une entrée contient une instruction ou plus, séparées par ; ou ,. Les instructions sont lancées dans l'ordre, chacune avec son propre résultat, et chacune peut parler de celles qui la précèdent — jamais de celles qui la suivent. Un résultat est un nombre, un texte ou une liste.

$result = $dice->roll($dice->parse('8d10; @1c[>=6]; @1c[=1]; "$2 successes, $3 ones"'), $randomizer);

$result->totals();    // [44, 5, 1, null], for instance
$result->outputs();   // [44, 5, 1, "5 successes, 1 ones"]

Instructions et références

@ seul reste les dés de l'ensemble précédent, dans la même instruction (notation) ; @ suivi d'un nombre représente les dés de cette instruction. Les dés des instructions acceptent les modificateurs qui jugent des dés une fois lancés — garder et écarter, réussites, filtres, tris, marques critiques —, aucun qui en lance davantage.

Une instruction fusionnée n'a plus de total : ExpressionResult::total() est null et mergedInto donne le numéro de l'instruction qui a pris ses dés. Son résultat est quand même gardé, et $n le lit toujours ; ses dés ne peuvent plus être liés ni fusionnés. Une référence ne prend pas les dés de l'instruction qu'elle lit : $1 est une valeur, @1 un ensemble de dés.

Groupes

{4d6, 2d10}kh1 lance chaque expression du groupe avec son propre total, puis juge les totaux comme des dés déjà lancés : garder et écarter, réussites ({3d6, 3d6, 3d6}>=10), filtres, tris, marques critiques. Une expression d'un groupe ne voit pas les dés extérieurs, et les dés précédents (@) après un groupe sont ses totaux. Les totaux sont énumérés dans DiceResult::parts sous les noms expression-1, expression-2 et ainsi de suite.

Listes de textes

Un élément s'écrit tel quel, jusqu'à la virgule, au crochet ou au poids qui le termine, ses espaces retirées ; entre guillemets doubles, il peut contenir n'importe quel caractère, une virgule ou un crochet compris. Un élément est un texte ou une clé de traduction, jamais du HTML. Les intervalles d'une liste se suivent, du premier au dernier, sans trou ; une liste est pondérée ou sur des intervalles, pas les deux. Une liste unique tire parmi les éléments restants, selon leurs poids ou la largeur de leurs intervalles.

ListResult garde les éléments tirés, l'indice de chacun dans la liste (draws), le nombre lancé pour chacun (rolls : de 1 au poids total, ou sur les intervalles) et le nombre d'éléments quand il a été lancé. Chaque tirage compte comme un dé au regard des limites.

Textes et phrases

Un texte s'écrit entre guillemets doubles : "Critical!", "weapon.sword". Sans marqueurs, c'est un texte ou une clé de traduction, tel que le lit l'application — jamais du HTML ; la page l'échappe. Avec des marqueurs, c'est une phrase, dont les marqueurs sont remplacés par des résultats au moment du lancer :

Une liste s'écrit avec ses éléments séparés par une virgule et une espace, ou accolés quand elle n'a pas de séparateur. Une barre oblique inversée écrit un saut de ligne, \n, et écrit tel quel une barre oblique inversée, un guillemet double, %, $, @, [ ou un chiffre qui la suit : "50\% off" ; "$1\2" est le résultat de l'instruction 1 suivi du chiffre 2. Un signe qui n'est pas suivi d'un chiffre s'écrit tel quel : "100 %".

Branches

Une branche s'applique à l'opérande juste avant elle — des dés, une liste de valeurs, un groupe, une référence, une expression entre parenthèses : (1d20+5)i[>=15]{…}. Sa condition est un validateur entre crochets, avec la portée dans laquelle elle juge le sujet : sa valeur par défaut, all: ou any: des dés qui y comptent, total: leur somme sans ce qui leur est ajouté. Un sujet sans dés est jugé comme un seul dé de sa valeur. Une branche contient tout ce que peut contenir une instruction : un nombre, des dés, un texte, une liste, une autre branche. Seule la branche retenue est lancée. Le sujet est un nombre : un texte ou une liste ne peut pas être jugé.

BranchResult garde le sujet, les cas vrais — par leur indice à partir de 0, un if étant un seul cas —, si la branche par défaut a donné le résultat, et le résultat.

Répétitions

repeat(4d6kh3, 6) lance son premier argument autant de fois que le dit son second — un nombre, ou une expression lancée d'abord — et donne les résultats dans une liste. Ce qu'il répète peut être un texte ou une liste, dont les éléments rejoignent la liste. Chaque répétition compte au regard des limites, celles d'un repeat() dans un repeat() une fois pour chaque passage.

Commentaires

Les commentaires ne prennent part ni au lancer ni à la forme canonique ; Pool::$comments les garde, selon l'indice à partir de 0 de l'instruction dans laquelle ils sont écrits. Un commentaire jusqu'à la fin de la ligne se termine à un saut de ligne : une instruction qui le suit commence donc à la ligne suivante. Un commentaire entre crochets ne contient ni guillemet ni # ; après un modificateur qui prend un seuil entre crochets — une relance, une explosion, une marque critique, des occurrences —, les crochets sont lus comme le seuil.

Résultats

NodeResult::output() donne le nombre, le texte ou la liste ; value() donne le nombre, et lève CannotRoll pour un texte ou une liste. ExpressionResult::output() est la sortie d'une instruction, text() la même écrite comme l'écrit une phrase, total() le nombre quand c'en est un. PoolResult::outputs() énumère les sorties, totals() les totaux.

La forme canonique

La forme canonique sépare les instructions par ", ", écrit les dés d'une instruction @n et ceux de plusieurs b[…] ou m[…], les groupes {a, b}, une liste nL avec u puis n et ses éléments tels qu'écrits, sauf s'ils exigent des guillemets, un aiguillage S — en majuscule, comme L et le F des dés Fudge, pour qu'aucun ne se lise comme un tri ou un chiffre —, un if i, et un texte entre guillemets doubles avec les échappements qu'il exige. Les commentaires ne sont pas écrits.