Instructions and results

An input holds one instruction or more, separated by ; or ,. The instructions are rolled in order, each with its own result, and each may speak of those before it — never of those after. A result is a number, a text or a list.

$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 and references

@ alone stays the dice of the set before, in the same instruction (notation); @ followed by a number is the dice of that instruction. The dice of instructions take the modifiers that judge dice once rolled — keep and drop, successes, filters, sorts, critical marks —, none that rolls more.

A merged instruction has no total any more: ExpressionResult::total() is null and mergedInto gives the number of the instruction that took its dice. Its result is still kept, and $n still reads it; its dice cannot be bound or merged again. A reference does not take the dice of the instruction it reads: $1 is a value, @1 a set of dice.

Groups

{4d6, 2d10}kh1 rolls each expression of the group with its own total, then judges the totals as dice already rolled: keep and drop, successes ({3d6, 3d6, 3d6}>=10), filters, sorts, critical marks. An expression of a group does not see the dice outside it, and the dice before (@) after a group are its totals. The totals are listed in DiceResult::parts as expression-1, expression-2 and so on.

Text lists

An item is written as it is, up to the comma, the bracket or the weight that ends it, its spaces trimmed; between double quotes, it may hold any character, a comma or a bracket included. An item is a text or a translation key, never HTML. The ranges of a list follow each other, from the first to the last, with no gap; a list is weighted or on ranges, not both. A unique list draws among the items left, by their weights or the width of their ranges.

ListResult keeps the items drawn, the index of each in the list (draws), the number rolled for each (rolls: from 1 to the total weight, or on the ranges) and the count when it was rolled. Each draw counts as a die against the limits.

Texts and sentences

A text is written between double quotes: "Critical!", "weapon.sword". Without placeholders, it is a text or a translation key, as the application reads it — never HTML; the page escapes it. With placeholders, it is a sentence, whose placeholders are replaced by results when it is rolled:

A list is written with its items separated by a comma and a space, or together when it has no separator. A backslash writes a line break, \n, and writes as such a backslash, a double quote, %, $, @, [ or a digit that follows it: "50\% off", "$1\2" is the result of instruction 1 followed by the digit 2. A sign not followed by a digit is written as such: "100 %".

Branches

A branch applies to the operand just before it — dice, a list of values, a group, a reference, an expression between parentheses: (1d20+5)i[>=15]{…}. Its condition is a validator between brackets, with the scope it judges the subject in: its value by default, all: or any: of the dice that count in it, total: their sum without what is added to them. A subject without dice is judged as one die of its value. A branch holds anything an instruction may: a number, dice, a text, a list, another branch. Only the branch that holds is rolled. The subject is a number: a text or a list cannot be judged.

BranchResult keeps the subject, the cases that held — by their index from 0, an if being one case —, whether the default branch gave the result, and the result.

Repetitions

repeat(4d6kh3, 6) rolls its first argument as many times as its second says — a number, or an expression rolled first — and gives the results in a list. What it repeats may be a text or a list, whose items join the list. Each repetition counts against the limits, those of repeat() within repeat() once for each time.

Comments

Comments take no part in the roll nor in the canonical form; Pool::$comments keeps them, by the index from 0 of the instruction they are written in. A comment to the end of the line ends at a line break, so an instruction after it starts on the next line. A comment between brackets holds no quote nor #; after a modifier that takes a threshold between brackets — a reroll, an explosion, a critical mark, occurrences —, brackets are read as the threshold.

Results

NodeResult::output() gives the number, the text or the list; value() gives the number, and raises CannotRoll for a text or a list. ExpressionResult::output() is the output of an instruction, text() the same written as a sentence writes it, total() the number when it is one; PoolResult::outputs() lists the outputs, totals() the totals.

The canonical form

The canonical form separates the instructions by ", ", writes the dice of one instruction @n and those of several b[…] or m[…], the groups {a, b}, a list nL with u then n and its items as written unless they need quotes, a switch S — capital, as L and the F of Fudge dice, so that neither reads as a sort or a digit —, an if i, and a text between double quotes with the escapes it needs. Comments are not written.