Dice expression syntax

Quick reference

Constants and dice

An expression is a sum of terms. Each term is either an integer constant (K) or a dice term (NdM, possibly with a modifier). Whitespace between tokens is optional and ignored; the d can be uppercase (D) too.

• 5 — a constant 5 (degenerate "distribution" with one outcome).
• 1d6 — one six-sided die. Six equally-likely faces, mean 3.5.
• 2d6 — two d6 summed. The classic triangular distribution: 36 outcomes, mean 7, mode 7.
• 4d6 — four d6, used in 5e ability score generation (the "drop the lowest" variant isn't yet supported as a single expression).

Additive modifiers

The most common 5e weapon-damage form: NdM plus your ability modifier. + and - are left-associative; you can chain any number of terms.

• 1d8+3 — longsword with +3 STR. Range 4–11, mean 7.5.
• 2d6+5 — greatsword with +5 STR. Range 7–17, mean 12.
• 1d12+5 — greataxe with +5 STR. Same modifier; very different shape.

For mixing different dice (e.g., weapon + sneak attack die, base damage + elemental rider), see the next section.

Mixing dice and constants — the main reason to use the engine

Anyone can compute 2d6 alone. The interesting cases combine different dice — weapon + sneak attack, base damage + elemental rider, primary swing + bonus-action attack — and the resulting distribution isn't an obvious shape. Convolving exact rationals is what this engine does well.

Add as many dice and constant terms as you want, in any order, with + or - between them. Whitespace is optional.

• 2d6 + 1d4 — pure dice mix, no constant. Range 3–16, mean 19/2 = 9.5.
• 1d8 + 1d6 + 3 — 5e rogue with a shortbow + sneak attack die + DEX modifier. Three independent terms. Range 5–17, mean 11.
• 2d6 + 1d4 - 2 — dice plus dice plus a negative constant. Useful for "deal 2d6 + 1d4 damage, target gains 2 temp HP" kind of net-damage scenarios. Range 1–14.
• 1d8 + 3 ↔ 3 + 1d8 — order doesn't matter for + terms; both produce the same distribution and the same slug encoding when you flip them through the parser.

The convolved shape is what you'd expect from the central limit theorem — adding more independent dice pulls the distribution toward a bell curve. Side by side: pure 1d8+1d6 (no modifier) vs the rogue pattern with +3 (same shape, shifted right by 3):

Exploding dice (!)

On a maximum-face roll, roll the die again and add. Recurses up to depth 20 (truncation error ~M⁻²⁰, well below floating-point noise for any practical M). Notation: append ! to the dice term.

• 1d6! — the canonical exploding die. Mean 21/5 = 4.2.
• 1d8! — slightly tighter explosion rate.
• Why this matters →

Constraint: a 1-sided die can't explode (it would loop forever). Combining ! with r on the same die is rejected — pick one modifier per die term.

Reroll once (r<K>)

If the first roll is ≤ K, roll a second time and keep the second result (whether it's higher or lower). The 5e Great Weapon Fighting style is exactly NdMr1 — reroll any 1s and 2s once. (Strict 5e GWF rerolls 1s AND 2s; the engine currently supports only an inclusive ≤ K threshold, so r2 covers both.)

• 2d6r1+5 — greatsword with GWF "reroll 1s" rule. Compare to plain 2d6+5.
• 1d12r1+5 — greataxe with the same rule.

Keep-highest / keep-lowest (kh1 / kl1)

Roll N dice, keep only the single highest (kh1) or single lowest (kl1). When N=2 this is exactly 5e advantage and disadvantage.

• 2d20kh1 — d20 with advantage. Mean 553/40 = 13.825.
• 2d20kl1 — d20 with disadvantage. Mean 287/40 = 7.175.
• Why this matters →

Constraint: only kh1 / kl1 are evaluated today. Larger keep counts (e.g. 4d6kh3 for 5e ability score generation) parse but error with a clear message — that requires the order-statistic engine extension, on the roadmap.

Combination rules

• One modifier per die term. 1d6!r1 is rejected — pick exploding or reroll.
• Modifiers attach to the dice term, not to the sum. 2d6!+5 means "exploding 2d6, then add 5", not "explode the whole sum".
• No multiplication, no parentheses. The grammar is intentionally additive-only. 3 × 1d6 is just 3d6 (which has the same distribution as one die's worth tripled in count, by linearity).
• Case-insensitive operators. 2D20KH1 works the same as 2d20kh1.
• Whitespace is ignored between tokens. 2d6 + 1d4 - 2 and 2d6+1d4-2 are equivalent.

What's not yet supported

• Generic keep-K (kh3, kl2, …). Parses but rejects with KeepNotImplemented. Needs the order-statistic engine extension — straightforward but not done yet.
• Multiplication (3 × 1d6). Use 3d6 instead — the engine has no multiplication operator.
• Comparison / threshold operators (≥, =, …). The kill-probability question is asked via the URL (/kill/<expr>/<hp>) or the per-page HP slider, not via expression syntax.
• Conditional / Boolean logic. No "roll X, on success roll Y" expressions. Use the attack-resolution API (Diceplots.Engine.resolve_attack/1) for hit/miss/crit compositions; that's a different layer from raw damage expressions.

URL slug encoding

Pages under /strike/<slug> and /vs/<a>/<b> use a tiny URL-safe substitution so links don't need percent-encoding:

• + ↔ p
• - ↔ m
• whitespace stripped on encode

So 2d6+5 becomes /strike/2d6p5. Modifiers that don't contain + or - (like !, r1, kh1) pass through unchanged.

Error messages

The parser surfaces specific errors rather than a generic "syntax error". Common ones:

• unexpected end of input — truncated expression.
• unexpected character: 'x' — couldn't parse past x.
• dice count must be at least 1 — 0d6.
• dice must have at least 1 side — 1d0.
• a 1-sided die cannot explode — 1d1!.
• a die can carry at most one modifier (! or r<N>) — 1d6!r1.
• keep N not yet supported — only keep-1 (advantage / disadvantage) works today — 4d6kh3.

Try it yourself

↦ Comparison tool — type any expression and see the distribution ↦ Concepts — counterintuitive damage math