Dice Notation

The Basics

A roll is written the way you'd say it at the table. Type the dice, add a modifier, and that's a roll. If you've used Roll20, this will feel familiar — the same shorthand works here.

Dice Buttons in Notes

Wrap any roll in double braces to turn it into a clickable button inside a note. Anyone at the table can tap it to roll.

{{2d6}}          a button that rolls 2d6
{{d20+5}}        a d20 with a +5
{{4d6kh3}}       roll four d6, keep the best three

Labels

Add a label after a pipe to say what the roll is for. The label shows on the button and in the result.

{{4d6kh3|Ability Score}}
{{2d6+2|Longsword Damage}}

Named Rolls

Give a roll a name with = and you can reuse it elsewhere in the same note with @Name. Handy for a damage roll you reference from an attack, or a stat you roll against repeatedly.

{{Damage = 2d6+3}}      defines a named roll
{{@Damage}}             rolls it again by name

{{Might = 3}}           a named value
{{d20 + @Might}}        rolls d20 and adds it

@Field references also pull from a character sheet — so {{d20 + @Might}} uses whatever Might is on the sheet at roll time, not a number frozen into the note.

Rolls That Judge Themselves

A plain roll just shows a number. But most systems want more than a number — a hit or a miss, a degree of success, a count of successes. Add one of the words below and the roll decides its own result and shows it. You never have to add up whether you passed.

vs — Beat a Target

Roll the total and compare it to a number. Meet or beat it and it's a success.

d20+5 vs 15

Shows Hit or Miss. A natural 20 reads as a Critical. Don't know the target, or want it secret? Write vs ? and it asks when you roll — or, if the difficulty is meant to stay hidden, leaves it blank and just shows the total.

d20+5 vs ?      asks for the target at roll time

under — Roll Beneath a Number

For skill-under systems: roll at or below the target to succeed. Pair it with bands to grade the result — a low roll is a better success.

d100 under 50 bands 1:crit, /5:extreme, /2:hard, 96..100:fumble

Shows the degree that fits: Extreme, Hard, an ordinary success, or a Fumble at the top of the range. The /5 and /2mean “a fifth of the skill” and “half the skill” — the thresholds move with the number automatically.

count — Dice Pools

Roll a handful of dice and count how many clear a bar. The count is the result, not the total. Add bane to also count a bad face — ones that cost you.

5d6 count >=4               how many dice show 4 or higher
8d6 count 6 bane 1          count 6s as hits, 1s as banes

Shows something like 3 Successes, or 2 Successes · 1 Bane.

best — Judge the Highest Die

Roll several dice but only the single highest one matters. Combine with bands to name the outcome.

3d6 best bands 6:full, 4..5:partial, ..3:bad

Your best die of a 6 shows Full Success; a 4 or 5 is a Partial; 3 or under is trouble.

bands — Degrees of Success

Map the total onto named outcomes. This is the 2d6 shape at the heart of Powered by the Apocalypse: a miss, a mixed result, a clean hit.

2d6+1 bands ..6:miss, 7..9:partial, 10..:full

A total of 8 shows 7–9: Partial. ..6means “6 and below”; 10..means “10 and up”.

margin — How Much You Beat It By

Attach margin to a vs or under roll to report the distance from the target as a second number — the effect, the degree, the overkill.

2d6+2 vs 8 margin

A total of 11 shows Success · Effect +3.

beats — Roll Against Roll

Roll a second thing and compare. Good for opposed checks. Add each and your total is checked against every die on the other side individually — the Ironsworn shape, where beating both, one, or neither gives a strong hit, weak hit, or miss.

d20+4 beats d20+2          opposed check
d6+3 beats 2d10 each       count how many you beat

Shows Win / Lose, or with each, Weak Hit (1 of 2).

Your Game System Does the Work

When you create a game, you pick a system. From then on, a bare roll gets the right treatment on its own. In a Call of Cthulhu game, d100 against a skill already knows to roll under and grade the degrees. In D&D, a d20 check already knows a natural 20 is special. You write the dice; the system fills in what your table expects.

Spelling it out always wins. If you write the full notation — the vs, the bands, the count— that's exactly what you get, in any game, regardless of the system default. Reach for that when you want a roll to behave a specific way and never change its mind.

Cheat Sheet by System

One line per system: what you can write, and what shows up when the dice land.

Reference

Every piece of the notation in one place. A roll is dice and modifiers, optionally followed by one or more of the judging clauses.

Dice and Modifiers

Judging Clauses

Targets and Values

In Notes

See Also

• MCP Server — Let an AI assistant roll dice and read results with this same notation
• SDK Guide — Trigger rolls from a custom character sheet