Abstract
This document defines the RANDSUM Dice Notation (RDN), a human-readable, machine-parseable format for expressing dice rolls in tabletop role-playing games. RDN specifies a three-stage execution pipeline with deterministic modifier ordering, a faceted classification system for modifiers, and four conformance levels for partial implementation. The notation supports standard dice, custom faces, geometric dice, draw dice, and modifiers that run in three pipeline stages. This specification is intended to enable interoperable dice notation processing across virtual tabletop platforms, chat bots, and game automation tools.
Status of This Document
This document is a community specification published by the RANDSUM project. It is not an Internet Standards Track specification; a submission to the IETF is forthcoming. Distribution of this document is unlimited.
This is a draft release. The specification is believed to be stable for implementation but may undergo revisions before the 1.0 release. Feedback is welcome via the specification repository.
Sections and appendices marked (Informative) are non-normative. Examples, notes and tables of contents are informative. Everything else is normative.
1. Introduction
1.1 Purpose
This document is the formal specification for RANDSUM Dice Notation (RDN), a compact language for describing dice rolls, modifiers, and resolution mechanics used in tabletop role-playing games and related systems.
1.2 Scope
This specification covers:
- Dice types and their generation models
- Modifier taxonomy, classification, and execution semantics
- The three-stage execution pipeline and two-channel architecture
- Condition expression sub-grammar
- Notation syntax overview
- Safety limits and implementation guidance
- Conformance levels for partial implementations, and the badges that advertise them
This specification is language-agnostic. It describes the required behavior of any conforming implementation without prescribing implementation language, data structures, or API shape.
1.3 Conventions
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals, as shown here.
Where the prose of this specification and the grammar in Appendix F disagree, the prose governs. The conformance vectors file (Section 11.3) is normative; Appendix G presents it for readers, and where the two differ the file governs. The reference implementation (Section 11.5) is informative: where it and this document disagree, this document governs.
A classification line or an “Options” line under a modifier, and the Options column of Appendix C, give the reference implementation’s names for a modifier’s settings (ComparisonOptions, greaterThanOrEqual, once). Those names are informative. This specification prescribes behavior, not an API.
1.4 Versioning
This is version 0.9.0 of the RANDSUM Dice Notation Specification. Future versions will follow semantic versioning: breaking changes increment the major version, additive changes increment the minor version. While the specification is a draft, a revision corrects a version in place and is listed in Section 1.5; a conformance claim names the version, not the revision, and is a claim against that version’s current revision. A revision MAY correct or tighten a requirement, and Section 1.5 says so when one does.
An implementation MAY accept notation beyond this grammar in a mode of its own. A conformance claim covers its behavior with such extensions off, where input outside the grammar MUST be rejected (Section 8.3).
1.5 Document History
| Version | Date | Changes |
|---|---|---|
| 0.9.0 | 2026-03-21 | Initial public draft. Three-stage pipeline, 26 modifiers, four conformance levels, faceted classification, ABNF grammar, 48 conformance test vectors, security considerations, IANA section. |
| 0.9.0 rev. 2 | 2026-10-31 | Audit against the reference implementation. Whitespace (8.2), multi-pool expressions (8.7), annotations (8.6) and repeat scope (6.8.3) now match the parser; Inflation and Reduction start past the die’s own size (6.7.9, 6.7.10); Keep Middle takes a count and runs as Drop (6.7.2); conditional Drop may empty the pool (6.5.4); Unique’s exemption list and its error (6.5.3); a modifier that sets a value appears once per expression (8.3); the ABNF top level, conditions and faces corrected (Appendix F); feature levels made consistent with the vectors, Conditional Drop moved to Level 2 (Section 10); conformance badges (10.7); vector 39 corrected and vector 55 listed (Appendix G). Explode, Compound and Penetrate chain by default, and Penetrate subtracts 1 with no minimum (6.5.6, 6.5.8, 6.5.9, 9.1); Reroll Once rerolls each matching die once (6.7.3); vectors 56 to 59 cover them. |
| 0.9.0 rev. 3 | 2026-10-31 | The specification, its vectors and a conformance runner move to their own repository, github.com/RANDSUM/notation-spec, under CC BY 4.0 (text) and MIT (vectors and runner). Vectors 31, 33 and 51 gain an unseeded field that states what a result must satisfy when the seed cannot be replayed, replacing the multiset comparison; the vectors file gains a JSON Schema; the conformance runner and its adapter protocol (11.3). No vector changes its expected result. |
| 0.9.0 rev. 4 | 2026-10-31 | The specification is published at its own address, https://notation.randsum.dev/. The badge URLs (10.7), the conformance vectors’ location and $id (11.3) and the JSON Schema move with it; the old randsum.dev addresses redirect. No normative change. |
| 0.9.0 rev. 5 | 2026-11-01 | A geometric die takes only Scale modifiers (4.3): a modifier that reads or changes individual dice, such as g6L or 3g6#{>6}, MUST be rejected; error vectors 60 and 61 cover it. Custom Faces dice MAY take a quantity, as Section 4.2 and vector 31 already show (4.6 said otherwise). |
| 0.9.0 rev. 6 | 2026-11-20 | Audit of the text, grammar, vectors and reference implementation. Newly stated: the order of authority among prose, grammar, vectors and reference implementation (1.3); what a claim against a revised version means, and extensions (1.4); dice that survive a Drop or Keep stay in pool order, the earliest of tied dice is removed, and a Stage 2 modifier finishes one die before the next (6.5.1); the Reroll limit counts dice rerolled and is a positive integer (6.5.2); the order Unique examines dice in (6.5.3); positional Drop and Keep are checked against the quantity written (6.5.4, 6.5.5); Keep highest and Keep lowest MUST NOT be combined, and explosion forms do not consume their trigger (6.9); what a repeat yields (6.8.3); whitespace is defined (8.2); a ! form once matched is committed, so 4d6!!! is Compound then Explode and 4d6!!p is an error (8.3, P3); consecutive repeats count as their product, and an operand MUST be exactly representable (9.4). Corrected: a repeated operator in a condition list is an alternative like any other (5.2); the Replace grammar no longer admits V{=4=6}, Reroll’s count is positive, and Reroll Once takes none (Appendix F); Margin of Success is one of the Scale modifiers a geometric die takes (4.3); the error vectors Section 11.4 listed. Vectors 62 to 105 cover the features and orderings that had none: several pools, whitespace, conditional Drop and Explode, counts and depths, Wild Die’s two paths, Inflation and Reduction, truncating division on a negative total, and modifier order against notation order. A vector answers several pools as one pool in notation order (11.3). |
| 0.9.0 rev. 7 | 2026-11-22 | The items the rev. 6 audit left open. A repeated notation now has vectors: a vector’s expectedResults and an adapter’s results hold the pool and total of each evaluation (11.3, 11.3.1), and vectors 106 and 107 cover xN. In Count’s deduct mode no value may be both a success and a failure, whichever operators state the two sides (6.6.2). A pool value or total that is not an exact integer MUST be signalled as an error (9.4). A canonical form, where an implementation offers one, MUST re-parse to the same roll (11.5). |
2. Glossary
The following terms are used normatively throughout this specification.
| Term | Definition |
|---|---|
| Die Expression | A notation string that describes one or more dice and their modifiers. Example: 4d6L. |
| Roll | A single random outcome produced by a die. A numeric value selected from the die’s face set. |
| Pool | The ordered array of roll values produced by evaluating a die expression. Modified in-place by Stage 1 and Stage 2 modifiers. |
| Total | The scalar numeric result derived from a pool, typically by summation, but optionally by counting (see Reinterpret). |
| Modifier | A named transformation applied to a pool or total during the execution pipeline. Each modifier has a priority, stage, verb, and channel. |
| Primitive | A modifier or die type that provides irreducible behavior not expressible as a composition of other features. |
| Alias | A notation convenience that de-aliases to one or more primitives with identical observable behavior. |
| Macro | A modifier that dispatches to different primitive behaviors based on runtime state. |
| Stage | One of three ordered phases of the execution pipeline. Each stage has a contract governing what operations are permitted. |
| Verb | The operational classification of a modifier describing what it does to the pool or total. One of: Clamp, Map, Filter, Substitute, Generate, Accumulate, Scale, Reinterpret. |
| Channel | The output target of a modifier: Pool (transforms the rolls array) or Total (transforms the scalar total). |
| Priority | A numeric value that determines execution order within the pipeline. Lower numbers execute first. |
| Condition Expression | A sub-grammar for specifying numeric comparisons used by multiple modifiers. See Section 5. |
| Die Type | The generation model and face configuration of a die. Standard, Custom Faces, Geometric, or Draw. |
| Condition | A single comparison operator and operand within a condition expression (e.g., >=7, <3). |
| Presentation Directive | A notation feature that affects display ordering but does not alter the total. Sort is the sole presentation directive. |
| Parser Directive | A notation feature resolved at parse time before the execution pipeline runs. Repeat (xN) is the sole parser directive. |
| Notation Metadata | Information embedded in notation that does not participate in the execution pipeline. Annotations ([text]) are the sole metadata feature. |
3. Classification System
3.1 Faceted Classification Overview
Every modifier in RDN is classified along four independent facets:
- Derivation Status – whether the feature is primitive, alias, or macro
- Pipeline Stage – when the modifier executes (Stage 1, 2, or 3)
- Operational Verb – what the modifier does (Clamp, Map, Filter, etc.)
- Output Channel – where the modifier writes its result (Pool or Total)
These facets are orthogonal but not fully independent: certain combinations are constrained (see Section 3.6). Together they form a complete taxonomy of every modifier in the system.
3.2 Derivation Status
| Status | Definition | Set |
|---|---|---|
| Primitive | Irreducible behavior. Cannot be expressed as a composition of other modifiers. | Closed |
| Alias | De-aliases to one or more primitives. Observable behavior is identical to the de-aliased form. | Closed |
| Macro | Dispatches to different primitives based on runtime state. | Closed |
The set of derivation statuses is closed. No other status exists or may be added without a new specification version.
3.3 Pipeline Stage
| Stage | Name | Priority Range | Contract | Boundary Signal |
|---|---|---|---|---|
| 1 | Deterministic Value Shaping | 10–39 | No RNG. Pure value transformations over the dice array. No pool size changes. | Rolls no dice |
| 2 | Pool Dynamics | 40–69 | Both stochastic and deterministic pool operations. Stochastic modifiers roll further dice. Drop/Keep run after explosions so the filter operates on the expanded pool. | May roll dice |
| 3 | Total Derivation | 80–100 | Pool is frozen. Operates on the scalar total only. | Changes no die value |
Stage boundaries are structural: a modifier that rolls dice cannot run in Stage 1, and a Stage 3 modifier cannot change a die’s value.
3.4 Operational Verb
| Verb | Stage | Description |
|---|---|---|
| Clamp | 1 | Constrain individual die values to boundaries. Pool size unchanged. |
| Map | 1 | Deterministic value substitution. Pool size unchanged. |
| Filter | 2 | Remove dice from the pool. Pool shrinks. |
| Substitute | 2 | Re-randomize matching dice. Pool size unchanged. |
| Generate | 2 | Append new dice to the pool. Pool grows. |
| Accumulate | 2 | Fold additional rolls into an existing die. Pool size preserved. |
| Scale | 3 | Arithmetic transformation of the total. |
| Reinterpret | 3 | Replace the aggregation model (sum to cardinality). |
There are exactly 8 operational verbs. Wild Die uses Dispatch (see Section 3.2 on Macros), which is not a verb but a macro classification.
3.5 Output Channel
| Channel | Description | Used By |
|---|---|---|
| Pool | Modifier transforms the rolls array. The resulting array is input to the next modifier. | Stage 1, Stage 2 |
| Total | Modifier transforms the scalar total. The pool passes through unchanged. | Stage 3 |
A modifier MUST use exactly one channel. No modifier uses both channels simultaneously.
3.6 Facet Interaction Constraints
The following constraints govern valid facet combinations:
-
Channel is determined by Stage. Stage 1 and Stage 2 modifiers use the Pool channel. Stage 3 modifiers use the Total channel. An implementation MUST NOT assign a Stage 1 modifier to the Total channel or vice versa.
-
Macros do not have a Verb. A macro dispatches to multiple primitives at runtime; its verb varies by execution path. Wild Die dispatches to Accumulate, Filter, or no-op depending on the rolled value.
-
Aliases inherit facets from their parent primitive. An alias’s Stage, Verb, and Channel are identical to the primitive it de-aliases to. Keep inherits Stage 2 / Filter / Pool from Drop. Minus inherits Stage 3 / Scale / Total from Plus. An alias MAY run at its own priority (Keep at 66, Minus at 91, Multiply Total at 100); Keep Middle has none of its own and runs as Drop at 65.
3.7 Valid Facet Combinations
| Stage | Verb | Channel | Modifiers |
|---|---|---|---|
| 1 | Clamp | Pool | Cap |
| 1 | Map | Pool | Replace |
| 2 | Substitute | Pool | Reroll, Reroll Once (alias), Unique |
| 2 | Generate | Pool | Explode, Explode Sequence, Inflation (alias), Reduction (alias) |
| 2 | Accumulate | Pool | Compound, Penetrate |
| 2 | Filter | Pool | Drop, Keep (alias), Keep Middle (alias) |
| 2 | Dispatch | Pool | Wild Die (macro) |
| 3 | Reinterpret | Total | Count, Count Successes (alias), Count Failures (alias) |
| 3 | Scale | Total | Multiply, Plus, Minus (alias), Margin of Success (alias), Integer Divide, Modulo, Multiply Total (alias) |
Sort (Stage 3, priority 95) is a Presentation Directive, not an operational modifier. It reorders the pool array for display but does not alter the total. It is classified under the Pool channel as a special case: it mutates the array ordering but not the array contents or the total.
4. Dice Expressions
4.1 Standard Dice (NdS)
Classification: Primitive
| Property | Value |
|---|---|
| Notation | NdS where N is quantity (default 1), S is number of sides |
| Generation Model | Uniform random selection |
| Face Type | Numeric, sequential integers |
| Face Range | [1..S] |
A standard die produces values uniformly distributed over the integers 1 through S inclusive. When N is omitted, it defaults to 1. When S is a positive integer, the die has faces numbered 1 through S.
Implementations MUST support S values of at least 1 through 1000. The quantity N MUST be a positive integer.
4.2 Custom Faces (d{…})
Classification: Primitive
| Property | Value |
|---|---|
| Notation | Nd{f1,f2,...,fN} |
| Generation Model | Uniform random selection |
| Face Type | Numeric or string, arbitrary values |
| Face Range | Exactly the listed face values |
Custom faces dice select uniformly from the explicitly listed face values. Duplicate values are permitted and create weighted distributions: d{1,1,2} has a 2/3 probability of producing 1.
A face is any text other than , and }; surrounding whitespace is trimmed. Every face MUST be non-empty: d{a,} MUST be rejected. When every face is an integer (optionally negative), the faces are numeric and the die sums like any other. Otherwise every face is a string, the roll result contains the string values, and the pool has no meaningful numeric total: a conforming implementation MUST NOT present a sum of string faces as the roll’s result. What a modifier does to a die with string faces is implementation-defined in this version.
4.3 Geometric Dice (gN)
Classification: Primitive
| Property | Value |
|---|---|
| Notation | gN, QgN where Q is quantity (default 1) |
| Generation Model | Open-ended (repeat until termination) |
| Face Type | Numeric, sequential integers |
| Face Range | [1..N] per roll |
| Termination | Stops when a roll is not equal to N (not max) |
| Safety Cap | 1000 iterations |
A geometric die rolls a standard dN repeatedly as long as each roll equals N (the maximum). The total is the sum of all rolls in the sequence. The die terminates when a roll is less than N, or when the safety cap of 1000 iterations is reached. g1 therefore always reaches the cap.
A geometric pool holds every roll of every sequence, not one value per die, so a geometric die takes only the Scale modifiers (Section 3.7: Multiply, Plus, Minus, Margin of Success, Integer Divide, Modulo, Multiply Total), which act on the total. Any other modifier, which reads or changes individual dice (Cap, Replace, Reroll, Unique, Explode and its relatives, Drop, Keep, Wild Die, Count, Sort), MUST be rejected: g6L and 3g6#{>6} are errors, while g6+3 and 2g6*2 are valid.
4.4 Draw Dice (DDN)
Classification: Primitive
| Property | Value |
|---|---|
| Notation | QddN or QDDN where Q is quantity, N is sides |
| Generation Model | Sampling without replacement |
| Face Type | Numeric, sequential integers |
| Face Range | [1..N] |
Draw dice sample without replacement from the face set [1..N]. Each value appears at most once within each pass through the pool. If the quantity Q exceeds N, the pool is exhausted and then reshuffled, and drawing continues from the fresh pool until all Q values are produced. For example, 8DD6 produces 8 values: the first 6 are a permutation of [1..6], then the pool reshuffles and 2 more values are drawn from it. Implementations SHOULD use Fisher-Yates shuffle or an equivalent unbiased algorithm for each shuffle pass. A modifier that rolls a draw die again (Reroll, Unique, Explode) takes its new value uniformly from [1..N], not from what is left of the pass.
4.5 Dice Aliases
4.5.1 Percentile (d%)
Classification: Alias
De-aliases to: Standard die 1d100.
The notation d% is equivalent to 1d100. Implementations MUST treat d% identically to 1d100 in all contexts.
4.5.2 Fate/Fudge (dF, dF.2)
Classification: Alias
Fate Core (dF): De-aliases to d{-1,0,1} (a custom faces die). Produces values in {-1, 0, +1}.
Extended Fudge (dF.2): De-aliases to d{-2,-1,0,1,2} (a custom faces die). Produces values in {-2, -1, 0, +1, +2}.
dF.1 is an alias for dF (standard Fate die with faces [-1, 0, 1]). Implementations that accept dF.1 MUST treat it identically to dF.
The standard Fate roll is 4dF, producing a total in the range [-4, +4].
4.5.3 Zero-Bias (zN)
Classification: Alias
De-aliases to: Custom Faces die d{0,1,2,...,N-1}. Produces values in [0..N-1] instead of [1..N].
4.6 Dice Type Classification Table
| Die Type | Generation Model | Face Type | Primitive/Alias | Notation |
|---|---|---|---|---|
| Standard | Uniform selection | Numeric sequential | Primitive | NdS |
| Custom Faces | Uniform selection | Numeric or string, arbitrary | Primitive | Nd{...} |
| Geometric | Open-ended repeat | Numeric sequential | Primitive | gN |
| Draw | Without replacement | Numeric sequential | Primitive | DDN |
| Percentile | Uniform selection | Numeric sequential | Alias (Standard) | d% |
| Fate/Fudge | Uniform selection | Numeric mapped | Alias (Custom) | dF, dF.2 |
| Zero-Bias | Uniform selection | Numeric shifted | Alias (Custom Faces) | zN |
Modifiers apply to every die type (die-core *modifier): 4dF+1, d%+5 and 3DD6L are valid. A geometric die takes only Scale modifiers (Section 4.3). A modifier that triggers on the maximum face without a condition (Explode !, Compound !!, Penetrate !p, Explode Sequence !s{}/!i/!r, Wild Die W) MUST be rejected on Fate, Zero-Bias and Custom Faces dice, whose faces are not [1..N]. A conditional form such as 4dF!{>0} is valid.
Every die type MAY take a quantity: 2d%, 3dF, 3z6, 3g6, 3DD6 and 2d{a,b,c} are valid.
5. Condition Expressions
Condition expressions are a shared sub-grammar used by Cap, Drop, Reroll, Count, and the conditional forms of Explode, Compound and Penetrate. Replace uses a single condition as the left side of each rule (Section 6.4.3).
5.1 Operator Syntax
A condition consists of an optional comparison operator followed by a non-negative integer operand. Negative operands are not part of this version: on a Fate die, match −1 with <0 rather than =-1.
| Operator | Meaning | Example |
|---|---|---|
>N |
Greater than N | >5 |
<N |
Less than N | <3 |
>=N |
Greater than or equal to N | >=7 |
<=N |
Less than or equal to N | <=2 |
=N |
Exactly equal to N | =4 |
N (bare integer) |
Modifier-specific (see Section 5.3) | 5 |
5.2 Condition Lists
Multiple conditions MAY be specified by separating them with commas within braces:
{>=7,<3} -- matches values >= 7 OR values < 3{1,6} -- bare integers, interpretation depends on modifier{>=5,<=2} -- matches values >= 5 OR values <= 2Conditions within a list are combined with logical OR unless the modifier specifies otherwise (see Count deduct mode in Section 6.6.2). An operator written more than once is an alternative like any other: {>2,>4} matches every value above 2, and R{<2,>5} rerolls a die below 2 or above 5.
5.3 Modifier-Specific Semantics
The bare integer form (no operator prefix) has different semantics depending on the modifier:
| Modifier | Bare Integer Meaning |
|---|---|
| Cap | Maximum cap: no result exceeds N. Equivalent to >N (clamp down to N). |
| Drop | Exact match: drop dice showing exactly N. Equivalent to =N. |
| Reroll | Exact match: reroll dice showing exactly N. Equivalent to =N. |
| Count | Exact match: count dice showing exactly N. Equivalent to =N. |
| Explode, Compound, Penetrate (conditional forms) | Exact match: trigger on dice showing exactly N. Equivalent to =N. |
The Cap modifier’s bare integer interpretation is the only case where a bare integer does not mean exact match.
6. Execution Pipeline
This section is normative. Conforming implementations MUST execute modifiers according to the rules described here.
6.1 Three-Stage Model
The execution pipeline processes modifiers in three sequential stages:
- Stage 1 – Deterministic Value Shaping (priority 10–39): Pure value transformations of the pool array. No random number generation. No pool size changes.
- Stage 2 – Pool Dynamics (priority 40–69): Both stochastic and deterministic pool operations. Requires a roll function for stochastic modifiers. Drop and Keep run after explosions so the filter operates on the expanded pool.
- Stage 3 – Total Derivation (priority 80–100): Pool is frozen. Operates on the scalar total.
Modifiers execute in ascending priority order. Within a stage, priority ordering is strict: a modifier with priority 20 MUST execute before a modifier with priority 30.
6.2 Two-Channel Architecture
The pipeline maintains two output channels:
- Pool channel: An ordered array of numeric values representing individual die results. Stage 1 and Stage 2 modifiers write to this channel.
- Total channel: A transformation of the computed scalar total. Stage 3 modifiers write to this channel.
Mutual exclusion invariant: A single modifier invocation MUST write to exactly one channel. No modifier writes to both channels simultaneously.
The total is computed by summing the final pool array, then applying each Stage 3 modifier’s transformation in priority order.
6.3 Priority Ordering
Implementations MUST apply modifiers in the order of this table, whatever order the notation writes them in. The numbers label that order and leave room between stages; only the order is observable.
| Priority | Modifier | Stage |
|---|---|---|
| 10 | Cap | 1 |
| 30 | Replace | 1 |
| 40 | Reroll | 2 |
| 50 | Explode | 2 |
| 51 | Compound | 2 |
| 52 | Penetrate | 2 |
| 53 | Explode Sequence | 2 |
| 55 | Wild Die | 2 |
| 60 | Unique | 2 |
| 65 | Drop | 2 |
| 66 | Keep (alias for Drop) | 2 |
| 80 | Count | 3 |
| 85 | Multiply | 3 |
| 90 | Plus | 3 |
| 91 | Minus (alias for Plus) | 3 |
| 93 | Integer Divide | 3 |
| 94 | Modulo | 3 |
| 95 | Sort | 3 |
| 100 | Multiply Total (alias for Multiply) | 3 |
6.4 Stage 1 – Deterministic Value Shaping
6.4.1 Contract
Stage 1 modifiers:
- MUST NOT invoke a random number generator.
- MUST be pure functions: given the same pool and options, they produce the same output.
- MUST NOT change pool size (no dice are added or removed).
6.4.2 Cap
Primitive | Stage 1 | Clamp | Pool channel | Priority 10
Notation: C{condition-list}
Options: ComparisonOptions
Effect: Constrains individual die values to specified boundaries. Values exceeding an upper bound are clamped down to the bound. Values below a lower bound are clamped up to the bound. Pool size is unchanged.
Bounds: Each condition sets one bound, and a die beyond it is set to the operand:
| Condition | Effect on each die |
|---|---|
>N, >=N, =N, bare N |
Upper bound: a die above N becomes N |
<N, <=N |
Lower bound: a die below N becomes N |
Evaluation order: Upper bounds are applied first (greaterThan, greaterThanOrEqual, exact), then lower bounds (lessThan, lessThanOrEqual). 4d6C{>5,<2} on [6, 1, 3, 2] gives [5, 2, 3, 2].
Bare integer semantics: A bare integer N in the condition expression means “maximum cap” – no result exceeds N. This differs from other modifiers where bare integers mean exact match (see Section 5.3).
Pool size: Unchanged.
Aliases: None.
6.4.3 Replace
Primitive | Stage 1 | Map | Pool channel | Priority 30
Notation: V{from=to,...}, where from is a non-negative integer or a single >, >=, < or <= condition (V{>4=6}) and to is a non-negative integer
Options: ReplaceOptions (from/to value pairs)
Effect: Deterministic substitution of die values. For each die in the pool, if its value matches a from value or condition, it is replaced with the corresponding to value. Pool size is unchanged.
Multiple replacement rules are applied in the order specified. A die may be replaced multiple times if subsequent rules match the replaced value.
Pool size: Unchanged.
Aliases: None.
6.5 Stage 2 – Pool Dynamics
6.5.1 Contract
Stage 2 modifiers:
- MAY roll further dice and introduce their values into the pool.
- MAY grow, shrink, or preserve the pool size depending on the modifier.
Order within a modifier: A Stage 2 modifier takes the dice in pool order and finishes every roll for one die before it moves to the next. 2d6!! on [6, 6] with compound rolls [6, 2, 3] gives [14, 9], and 3d6R{1} on [1, 1, 3] with rerolls [1, 4, 5] gives [4, 5, 3].
Order within the pool: Dice that a modifier does not remove keep their relative order, and new dice are appended. Where several dice tie for removal by value (Drop, Keep, Wild Die), the one earliest in the pool is removed: 3d6L on [1, 5, 1] gives [5, 1].
6.5.2 Reroll
Primitive | Stage 2 | Substitute | Pool channel | Priority 40
Notation: R{condition-list}, R{condition-list}N
Options: RerollOptions (comparison conditions, optional max count, optional once flag)
Effect: Re-randomizes dice matching the condition expression. Each matching die is re-rolled. If the new value still matches, the die is re-rolled again, up to a safety maximum of 99 attempts per die. The optional trailing N, a positive integer, limits the number of dice rerolled: dice are taken in pool order, and after N dice have been rerolled the rest are left as rolled. With once (Reroll Once, Section 6.7.3), each matching die is re-rolled a single time and the new value stands.
An exact (bare or =N) value that is not one of the die’s faces MUST be rejected, whatever Cap or Replace could make a die show: 1d6R{7} is an error.
Pool size: Unchanged.
Aliases: Reroll Once (Section 6.7.3).
6.5.3 Unique
Primitive | Stage 2 | Substitute | Pool channel | Priority 60
Notation: U, U{N1,N2,...}
Options: boolean or UniqueOptions
Effect: Enforces that no two dice in the pool share the same value. Dice are examined in pool order. A die showing a value that an earlier die already shows is re-rolled until it shows a value no earlier die shows. Dice later in the pool are not consulted, so one of them may be re-rolled in its turn: 3d6U on [3, 3, 5] with rerolls [5, 4] gives [3, 5, 4]. If no unique value is found within the reroll safety limit (Section 9.3), the implementation MUST signal an error rather than return a pool with duplicates.
U applies to all dice. U{N1,N2,...} exempts the listed values, which MAY repeat: 4d6U{1} allows several 1s. A pool with more dice than the die has distinct face values cannot be unique and MUST be rejected, unless an exempt value is one of those faces: 7d6U is an error and 7d6U{1} is not.
Pool size: Unchanged.
Aliases: None.
6.5.4 Drop
Primitive | Stage 2 | Filter | Pool channel | Priority 65
Notation: L, Ln, H, Hn, D{condition-list}
Options: DropOptions (highest, lowest, and/or comparison conditions)
Effect: Removes dice from the pool. L drops the lowest-valued die (or Ln drops the N lowest). H drops the highest-valued die (or Hn drops the N highest). D{...} drops dice matching comparison conditions.
When both positional (highest/lowest) and conditional drops are specified, conditional filtering is applied first, then positional drops operate on the remaining pool. Repeated positional drops add up: 4d6LL drops the two lowest, as does 4d6L2. L0 and H0 drop nothing.
The dice that remain keep their pool order (Section 6.5.1): 4d6L on [6, 1, 3, 2] gives [6, 3, 2].
Drop runs after all explosion-family modifiers (priority 50–55), so the filter operates on the fully expanded pool.
Pool size: Shrinks.
Validation: The number of dice dropped by position (L, H, and Keep Middle) MUST be less than the die expression’s quantity, whatever a roll later adds or removes: 2d6L2 is an error, and so is 1d6!L. A conditional drop depends on the roll, so it MAY empty the pool: 2d6D{>=1} yields an empty pool with a total of 0.
Aliases: Keep (Section 6.7.1), Keep Middle (Section 6.7.2).
6.5.5 Keep
Alias | Stage 2 | Filter | Pool channel | Priority 66
Notation: K, Kn, kl, klN
De-aliases to: Drop (inverse). Keeping the highest N dice from a pool of Q dice is equivalent to dropping the lowest (Q - N) dice.
Validation: N MUST be at least 1 and at most the die expression’s quantity: 4d6K0 and 2d6K3 are errors. Keep highest and Keep lowest MUST NOT be combined (Section 6.9).
Pool size: Shrinks.
Aliases: None (is itself an alias).
6.5.6 Explode
Primitive | Stage 2 | Generate | Pool channel | Priority 50
Notation: !
Options: boolean | ComparisonOptions
Effect: Each die showing its maximum value triggers one additional die roll appended to the pool. Explosions chain: a new die that also triggers adds another, until a new die does not trigger or the depth limit is reached (Section 9.1). 4d6! on [6, 6, 1, 1] with explosion rolls [6, 2, 3] gives [6, 6, 1, 1, 6, 2, 3]: the first 6 explodes into a 6, which explodes into a 2, and the second 6 explodes into a 3.
Conditional Explode (!{condition}): When a condition expression is provided, the explosion triggers on values matching the condition instead of only on the maximum value, and new dice chain on the same condition. Bare ! with no condition defaults to triggering on the die’s maximum face value.
Pool size: Grows (one new die per triggered explosion).
Aliases: None.
6.5.7 Explode Sequence
Primitive | Stage 2 | Generate | Pool channel | Priority 53
Notation: !s{N1,N2,...}
Options: number[] (sequence of die sizes)
Effect: Each die showing its maximum value starts the sequence: the first listed size is rolled and appended to the pool. If that die also shows its maximum, the next size is rolled, and so on. When the sequence is exhausted, the last die size repeats (capped by the explosion depth limit). Every size MUST be a positive integer: !s{0} is an error.
Pool size: Grows.
Aliases: Inflation (Section 6.7.9), Reduction (Section 6.7.10).
6.5.8 Compound
Primitive | Stage 2 | Accumulate | Pool channel | Priority 51
Notation: !!, !!N
Options: boolean | number | ComparisonOptions (explosion depth; true and 0 = unlimited up to the safety cap, integer N = at most N additional rolls)
Effect: Like Explode, but instead of adding new dice to the pool, each additional roll is added to the triggering die’s value. Pool size is preserved. The resulting die value may exceed the die’s maximum face value. Rolls keep being added while the added roll is also a maximum: bare !! and !!0 up to the safety cap (Section 9.1), and !!N up to N rolls. 2d6!! on [6, 1] with compound rolls [6, 6, 2] gives [20, 1].
Conditional Compound (!!{condition}): When a condition expression is provided, the compound triggers on values matching the condition instead of only on the maximum value, and keeps adding while the added roll matches. A depth and a condition MUST NOT be combined: !!2{>4} is an error.
Pool size: Preserved.
Aliases: None.
6.5.9 Penetrate
Primitive | Stage 2 | Accumulate | Pool channel | Priority 52
Notation: !p, !pN
Options: boolean | number | ComparisonOptions (explosion depth)
Effect: Like Compound, but each added roll has 1 subtracted from it before accumulation, so an added 1 contributes nothing. Whether the chain continues is decided by the added roll before the subtraction. Depth follows Compound: bare !p and !p0 continue while the added roll is also a maximum, up to the safety cap, and !pN up to N rolls. 2d6!p on [6, 1] with penetrate rolls [6, 6, 1] gives [16, 1].
Conditional Penetrate (!p{condition}): When a condition expression is provided, the penetrate triggers on values matching the condition instead of only on the maximum value, and continues while the added roll matches. A depth and a condition MUST NOT be combined: !p2{>4} is an error.
Pool size: Preserved.
Aliases: None.
6.5.10 Wild Die
Macro | Stage 2 | Dispatch | Pool channel | Priority 55
Notation: W
Options: boolean
Effect: The Wild Die macro implements the D6 System wild die mechanic. It examines the last die of the pool as it stands when Wild Die runs, after Explode and its relatives have added theirs, and dispatches:
- Maximum value: Compound-explode the wild die (Accumulate behavior). The wild die’s value is replaced with the accumulated total. Rolls keep being added while the added roll is also a maximum, up to the safety cap (Section 9.1).
- Value of 1: Drop the wild die AND the highest remaining non-wild die (Filter behavior). Pool shrinks by 2, or to empty when the wild die is the only die.
- Any other value: No operation. Pool unchanged.
Pool size: Varies (preserved on max, shrinks by 2 on 1, unchanged otherwise).
Aliases: None.
6.6 Stage 3 – Total Derivation
6.6.1 Contract
Stage 3 modifiers:
- MUST NOT modify the pool array.
- Operate exclusively on the scalar total.
- The pool is frozen: its contents are final after Stage 2 completes.
Presentation directive carve-out: Presentation directives (Sort) MAY reorder the pool array but MUST NOT alter its values or the total. Sort does not violate the Stage 3 immutability contract because it changes only presentation order, not values.
6.6.2 Count
Primitive | Stage 3 | Reinterpret | Total channel | Priority 80
Notation: #{condition-list}
Options: CountOptions (comparison conditions, optional deduct flag)
Effect: Replaces the default sum aggregation with a cardinality count. Instead of summing all die values, the total becomes the number of dice matching the specified conditions.
Count is the only modifier that changes what the total means rather than what the total is. All subsequent Scale modifiers operate on the count result, not the original sum.
Dual-condition deduct mode: When both an upper condition (greaterThan/greaterThanOrEqual) and a lower condition (lessThan/lessThanOrEqual) are specified, the modifier automatically activates deduct mode. Dice matching the upper condition are counted as successes; dice matching the lower condition are counted as failures and subtracted from the success count. A die matching an exact value counts as a success. No value may be both a success and a failure: the highest value the lower conditions match MUST be below the lowest value the upper conditions and exact values match. S{7,7}, #{>=7,<=7}, #{>=3,<8} and #{=2,>=9,<=2} are errors; #{>7,<8} is not, since no integer is both above 7 and below 8.
Pool size: N/A (Total channel).
Aliases: Count Successes (Section 6.7.7), Count Failures (Section 6.7.8).
6.6.3 Multiply
Primitive | Stage 3 | Scale | Total channel | Priority 85
Notation: *N
Options: number
Effect: Multiplies the current total by N. This is a pre-arithmetic multiplication: it runs before Plus/Minus (priority 90/91) but after Count (priority 80).
Pool size: N/A (Total channel).
Aliases: Multiply Total (Section 6.7.6).
6.6.4 Plus
Primitive | Stage 3 | Scale | Total channel | Priority 90
Notation: +N
Options: number
Effect: Adds N to the current total.
Pool size: N/A (Total channel).
Aliases: Minus (Section 6.7.4), Margin of Success (Section 6.7.5).
6.6.5 Integer Divide
Primitive | Stage 3 | Scale | Total channel | Priority 93
Notation: //N
Options: number
Effect: Divides the current total by N using truncating integer division (round toward zero): 1d6-7//2 on [1] is −3, not −4. N MUST be a positive integer; //0 is an error.
Pool size: N/A (Total channel).
Aliases: None.
6.6.6 Modulo
Primitive | Stage 3 | Scale | Total channel | Priority 94
Notation: %N
Options: number
Effect: Replaces the current total with the remainder of truncating division by N, which takes the sign of the total: 1d6-8%3 on [1] is −1. N MUST be a positive integer; %0 is an error.
Pool size: N/A (Total channel).
Aliases: None.
6.7 Modifier Aliases
Each alias de-aliases to a normative primitive form. An alias MUST produce identical observable behavior to its de-aliased form.
6.7.1 Keep
Notation: K, Kn, kl, klN
De-aliases to: Drop (inverse).
Keeping the highest N dice from a pool of Q dice is equivalent to dropping the lowest (Q - N) dice. KN on a pool of Q dice de-aliases to L(Q-N). klN (keep lowest) de-aliases to H(Q-N).
When N is omitted, it defaults to 1.
Inherits: Stage 2 | Filter | Pool channel | Priority 66.
6.7.2 Keep Middle
Notation: KM, KMn
De-aliases to: Drop lowest n + Drop highest n (n defaults to 1).
Removes the n lowest and the n highest dice from the pool, keeping only the middle values. It adds to any other positional drop: 5d6KML drops the lowest two and the highest one.
Inherits: Stage 2 | Filter | Pool channel | Priority 65 (it is a Drop).
6.7.3 Reroll Once
Notation: ro{condition-list}
De-aliases to: Reroll in its once form (Section 6.5.2): each matching die is rerolled at most once. Reroll Once takes no count: 4d6ro{1}2 is an error.
Every die that matches is rerolled one time, and the new result stands even if it matches again: 4d6ro{1} on [1, 1, 3, 4] with rerolls [1, 2] gives [1, 2, 3, 4].
Inherits: Stage 2 | Substitute | Pool channel | Priority 40.
6.7.4 Minus
Notation: -N
De-aliases to: Plus with negated operand. -N is equivalent to +(-N).
Inherits: Stage 3 | Scale | Total channel | Priority 91.
6.7.5 Margin of Success
Notation: ms{N}
De-aliases to: Minus N, which itself de-aliases to Plus (-N). This is a transitive de-aliasing chain: ms{N} -> -N -> +(-N).
Subtracts a target number from the total to compute how far above or below the target the roll landed.
Inherits: Stage 3 | Scale | Total channel | Priority 91.
6.7.6 Multiply Total
Notation: **N
De-aliases to: Multiply at priority 100 (post-arithmetic phase).
Unlike Multiply (*N, priority 85) which runs before Plus/Minus, Multiply Total runs after all arithmetic modifiers have been applied.
Inherits: Stage 3 | Scale | Total channel | Priority 100.
6.7.7 Count Successes
Notation: S{N}
De-aliases to: Count with greaterThanOrEqual: N. Optionally S{N,B} de-aliases to Count with greaterThanOrEqual: N, lessThanOrEqual: B, deduct: true.
Counts dice meeting or exceeding threshold N. Used in dice pool systems (e.g., World of Darkness).
Inherits: Stage 3 | Reinterpret | Total channel | Priority 80.
6.7.8 Count Failures
Notation: F{N}
De-aliases to: Count with lessThanOrEqual: N.
Counts dice at or below threshold N.
Inherits: Stage 3 | Reinterpret | Total channel | Priority 80.
6.7.9 Inflation
Notation: !i
De-aliases to: Explode Sequence over the standard die set {4, 6, 8, 10, 12, 20, 100}, keeping only the sizes larger than the die’s own, in ascending order. On a d6, !i is !s{8,10,12,20,100}; on a d20 it is !s{100}; on a d100 there is no larger size and !i does nothing.
On a maximum roll, the next larger standard die is rolled; past d100, d100 repeats.
Inherits: Stage 2 | Generate | Pool channel | Priority 53.
6.7.10 Reduction
Notation: !r
De-aliases to: Explode Sequence over the standard die set, keeping only the sizes smaller than the die’s own, in descending order. On a d20, !r is !s{12,10,8,6,4}; on a d6 it is !s{4}; on a d4 there is no smaller size and !r does nothing.
Reduction takes no condition block. !r followed by { or o{ is Explode then Reroll (Section 8.3).
On a maximum roll, the next smaller standard die is rolled; below d4, d4 repeats.
Inherits: Stage 2 | Generate | Pool channel | Priority 53.
6.8 Non-Modifier Notation Features
The following features appear in notation but are not modifiers in the pipeline sense.
6.8.1 Sort
Classification: Presentation Directive
Notation: sa (ascending), sd (descending)
Priority: 95
Effect: Reorders the pool array for display purposes. Sort does not alter the total. It runs in Stage 3 by execution ordering (the pool is frozen before sort runs), but produces no arithmetic change.
Sort is the only feature that modifies the pool array in Stage 3. This is a presentation-only reordering: the set of values is unchanged, only their order differs.
6.8.2 Annotations
Classification: Notation Metadata
Notation: [text]
Priority: None (no pipeline participation)
Effect: Attaches a label or descriptor to a die expression. Annotations have no effect on rolls, pools, or totals. They are preserved for display and logging purposes. A die expression takes at most one annotation, after its die core or any of its modifiers: 2d6+3[fire] and 2d6[fire]+3 are equivalent, and 2d6[a][b] MUST be rejected.
Examples: 2d6+3[fire], 1d8[healing], 1d20+5+2d6[fire].
6.8.3 Repeat
Classification: Parser Directive
Notation: xN
Priority: None (pre-pipeline expansion)
Effect: Expands the whole notation string into N independent roll evaluations. 4d6Lx6 is equivalent to rolling 4d6L six separate times, producing six independent results; 1d20+2d6x3 repeats both pools three times.
Repeat is resolved at parse time before the execution pipeline runs. Each repeated expression is evaluated independently with its own pool, modifiers, and total. Repeat MUST come last, after every pool, modifier and annotation; 2d6x2+3 MUST be rejected. Consecutive repeats multiply: 4d6x2x3 is six evaluations. N MUST be a positive integer.
The result of a repeated notation is its N results, in order. This version defines no combined total for them; an implementation that also reports one (the reference implementation reports their sum) does so outside this specification.
6.9 Modifier Composition Rules
When multiple modifiers are applied to the same die expression, the following composition rules govern their interaction:
Count + Scale: Count (priority 80) replaces the sum with a cardinality count before any Scale modifiers run. Plus (+N, priority 90), Minus (-N, priority 91), Multiply (*N, priority 85), and other Scale modifiers operate on the count result, not the original sum. Example: 5d10S{7}+2 counts successes >= 7, then adds 2 to that count.
Explosion + Filter: Explosions (Stage 2, priority 50–55) run before drop/keep (priority 65–66), so the pool is fully expanded before filtering. 4d6L! explodes first, then drops the lowest from the expanded pool – matching Roll20 and Foundry VTT conventions.
Cap + Drop: Cap (priority 10) runs before Drop (priority 65). A value that would have been dropped may first be capped, potentially changing which dice are “lowest” or “highest”. Example: 4d6C{>5}L caps all values at 5, then drops the lowest of the capped results.
Multiply + Plus: Multiply (priority 85) runs before Plus (priority 90). 2d6*2+3 doubles the sum first, then adds 3. To multiply after arithmetic, use Multiply Total (**N, priority 100): 2d6+3**2 adds 3 first, then doubles the result.
Count + Count: A die expression MUST NOT contain more than one Count-family modifier (#{}, S{}, F{}); implementations MUST reject it (Appendix F, P5). Each pool of a multi-pool notation is its own die expression: 2d6S{3}+2d6S{3} is valid.
Keep + Keep: Keep highest and Keep lowest name two different sets of dice to keep, so a die expression MUST NOT hold both: 4d6K2kl MUST be rejected.
Explosion + Explosion: Explode, Compound, Penetrate and Explode Sequence do not consume their trigger. A die still showing a triggering value when a later one of them runs triggers that one too: 2d6!!L! on [6, 1] adds an explosion die for the 6 and then compounds the 6.
Repeated modifiers: Within one die expression, a modifier that sets a single value MUST appear at most once. Writing it twice (2d6*2*3, 4d6V{1=6}V{2=6}, 4d6sasd, 4d6!i!r) MUST be rejected rather than resolved by keeping one occurrence. The forms whose repeats add up MAY repeat: Plus, Minus, Margin of Success, and positional Drop (L, H). A flag with no operand (!, !!, !p, !i, !r, W, U, sa, sd) MAY be written twice to the same effect: 4d6!L! explodes once.
7. Operational Groups (Informative)
This section is non-normative.
See Appendix E for the operational group reference.
8. Notation Syntax
This section defines the lexical rules of the notation; Appendix F gives its grammar. For a practical guide with interactive examples, see https://randsum.dev/notation/randsum-dice-notation/.
8.0 Character Encoding
RDN notation strings are sequences of Unicode scalar values. Implementations SHOULD accept UTF-8 [RFC3629] encoded input. All syntactic tokens (d, L, H, K, C, R, V, etc.) are drawn from the ASCII subset. Annotation text ([text]) and custom face labels (d{face1,face2}) MAY contain arbitrary Unicode text excluding their respective closing delimiters (] and }), and for a face the comma that separates faces. Implementations that render annotation text in HTML MUST sanitize against injection attacks (see Section 9.6).
8.1 Case Insensitivity
All RDN notation is case-insensitive. 2d8, 2D8, 2d8l, and 2D8L are equivalent. Implementations MUST treat uppercase and lowercase notation identically. Face labels and annotation text are content, not notation, and keep their case.
8.2 Whitespace
Whitespace is the space (U+0020), tab (U+0009), carriage return (U+000D) and line feed (U+000A) characters. RDN notation strings MUST NOT contain whitespace between tokens: 4d6L is valid, and 4 d6 L and 4d6 L MUST be rejected. Leading and trailing whitespace MUST be ignored. Whitespace within annotation text ([fire damage]) is preserved as part of the text content; whitespace around a custom face (d{fire, ice}) is trimmed, and whitespace inside one is kept.
8.3 Lexical Segmentation
RDN notation is parsed left-to-right. After the core die expression (NdS or special die type) is consumed, the remaining suffix is matched against modifier patterns in a longest-match, priority-ordered fashion. When two modifier patterns could match at the same position, the more specific pattern takes precedence (e.g., !! is matched as Compound before ! is matched as Explode; ** is matched as Multiply Total before * is matched as Multiply).
Any characters in the notation string that do not match a recognized die expression, modifier, annotation, or repeat operator MUST cause the implementation to reject the notation as invalid. Implementations MUST NOT silently discard unrecognized characters, nor a recognized token whose meaning another token overrides (Section 6.9, Repeated modifiers).
Disambiguation rules:
Sfollowed by{is Count Successes, not SortSfollowed byaord(not followed by{or a digit) is Sortd{...}orD{...}at the die-core position (start of expression or after+/-pool separator) is Custom Faces.D{...}at a modifier position (after a die-core has been consumed) is conditional Drop. Case-insensitive matching applies to token identity; positional context resolves the ambiguity.!!is Compound;!alone is Explode;!pis Penetrate;!s{...}is Explode Sequence;!iis Inflation;!ris Reduction- The choice among the
!forms is committed: once a longer form matches, the parser does not go back and read a bare!.4d6!!!is Compound then Explode, and4d6!sais Explode then Sort.4d6!!pis Compound followed by a straypand MUST be rejected, never Explode then Penetrate; write4d6!p!.!!directly befores{MUST be rejected, because it could also be read as Explode then Explode Sequence; write4d6S{3}!! KLandKMare Keep Lowest and Keep Middle, neverKfollowed byLor byms{...}!R{...}or!ro{...}is Explode followed by Reroll (or Reroll Once), not Reduction: Reduction takes no condition block!RR{...}is Reduction (!R) followed by Reroll (R{...})**is Multiply Total;*is Multiply//is Integer Divide+or-followed by a die core (+2d6,-d4,+4dF,+d%) starts an additional pool (Section 8.7); followed by digits alone it is arithmetic Plus/Minus
8.4 Base Syntax
The base die expression follows the form NdS where:
Nis the quantity of dice (positive integer, default 1 if omitted)dis the die separator (literal character)Sis the number of sides (positive integer)
Special die types replace the dS portion: d%, dF, dF.2, d{...}, zN, gN, DDN.
8.5 Modifier Suffix Chaining
Modifiers are appended as suffixes to the base die expression. Multiple modifiers chain left to right in notation, but execute in priority order regardless of notation position.
4d6L!+2 -- Drop lowest, explode, add 2 -- Execution: Explode(50) -> Drop(65) -> Plus(90)The notation order does not determine execution order. Priority ordering (Section 6.3) is the sole determinant.
8.6 Annotations
Annotations are enclosed in square brackets. A die expression takes at most one, after its die core or any of its modifiers, and before a repeat:
2d6+3[fire damage]2d6[fire damage]+31d8[healing]4d6L[strength]x6Annotations do not affect the roll result. They are metadata only.
8.7 Multi-Roll Expressions
Multiple die expressions within a single notation string are combined via arithmetic operators. + introduces an additive pool and - introduces a subtractive pool: 1d20+5+2d6 rolls 1d20, adds 5, and adds the result of 2d6. The first pool MAY carry a sign (-1d6). Each pool is evaluated with its own modifiers, which bind to the pool before them: in 1d20+5+2d6L the +5 belongs to the d20 and the L to the 2d6. Any die type may start a pool: 1d20+4dF, 2d6-g6. The notation’s total is the signed sum of the pool totals. Because a modifier binds to the pool before it, 1d20-1d6+3 on [10] and [1] is 10 − (1 + 3) = 6, and a leading sign covers its pool’s modifiers: -1d6+2 on [4] is −6. A Custom Faces die with string faces has no total, so it MUST NOT share a notation with another pool or with a repeat.
Comma-separated notation (e.g., 1d20+5, 2d6) is not part of the RDN grammar. Implementations that accept multiple independent roll expressions SHOULD provide a separate API mechanism (e.g., variadic arguments, array input) rather than overloading the notation string.
8.8 Repeat Operator
The repeat operator xN expands the whole notation string into N independent evaluations:
4d6Lx6 -- Six independent rolls of 4d6-drop-lowestRepeat is a parser directive resolved before the execution pipeline. It MUST come last (Section 6.8.3).
9. Safety and Limits
Implementations MUST enforce safety limits to prevent unbounded computation.
9.1 Explosion Depth
Explode MUST add at most 1000 new dice per original die. Compound and Penetrate MUST stop after at most 1000 additional rolls per die, including when no depth or a depth of 0 (unlimited) is specified, and Explode Sequence after at most the sequence’s length plus 1000 rolls per triggering die. Wild Die’s compounding stops after at most 1000 additional rolls.
Implementations MAY offer a different limit as an option but MUST NOT allow the limit to be removed. The values above are the defaults, and the ones a conformance claim is made with.
9.2 Geometric Die Cap
Geometric dice (gN) MUST terminate after at most 1000 iterations, even if every roll equals the maximum.
9.3 Reroll Attempts
The Reroll modifier MUST terminate after at most 99 re-roll attempts per die. If the condition is still matched after 99 attempts, the current value stands. Unique makes at most the same number of attempts per die, and then signals an error rather than let a duplicate stand (Section 6.5.3).
9.4 Pool Size Considerations
Implementations SHOULD impose a reasonable upper bound on pool size to prevent memory exhaustion. The limits of Sections 9.1 to 9.3 are per die and do not bound a roll on their own: quantity, the explosion limit and the repeat count multiply. Implementations SHOULD bound the total number of die rolls one notation string can cause. An implementation that limits the repeat count MUST apply that limit to the product of consecutive repeats, so that 1d6x1000x1000 is one million evaluations and not two counts of one thousand.
Every operand, pool value and total is an integer. An implementation MUST reject an operand it cannot represent exactly, and MUST signal an error rather than return a pool value or a total that is not an exact integer: a result that has overflowed, rounded or become infinite is not a result.
Implementations MAY reject die expressions where the initial pool size exceeds an implementation-defined maximum. Such limits SHOULD be documented and SHOULD be at least 1000 dice.
Note: The reference implementation (Section 11.5) rejects input longer than 1000 characters, a quantity above 10,000, sides above 1,000,000, repeat counts whose product is above 1000, and an operand above 2^53 − 1; a roll whose pool value or total passes 2^53 − 1 is an error.
9.5 Error Semantics
Conforming implementations MUST reject invalid notation before execution and MUST signal an error. The error signaling mechanism is implementation-defined (exceptions, error objects, result types). Implementations MUST NOT silently ignore invalid notation or produce a result from partially-parsed input.
Examples of invalid notation that MUST be rejected:
- Malformed expressions (e.g.,
4d,d,2d6+,4d6R) - Out-of-range values (e.g.,
d0, negative pool sizes) - Notation that violates explicit constraints defined in this specification
9.6 Security Considerations
RDN notation strings MAY originate from untrusted sources (user input, network messages, database records). Implementers need to weigh the following.
Denial of Service: Crafted notation can cause excessive computation. The explosion depth cap (Section 9.1), geometric die iteration cap (Section 9.2), and reroll attempt cap (Section 9.3) provide baseline protection, but implementations SHOULD impose additional limits on:
- Total pool size (number of dice across all pools)
- Repeat operator count (
xN— large N values generate many independent evaluations) - Input string length
Input Validation: Implementations MUST validate notation strings before execution. Notation strings MUST NOT be interpolated into shell commands, SQL queries, or other injection-susceptible contexts without proper escaping. The annotation feature ([text]) permits arbitrary text content — implementations that display annotations MUST sanitize them against cross-site scripting (XSS) if rendered in HTML contexts.
Resource Exhaustion: Implementations SHOULD set timeouts on notation evaluation to prevent unbounded computation from blocking other operations.
Randomness: RDN does not require cryptographically secure random number generation. Pseudorandom number generators (PRNGs) are acceptable for tabletop gaming use cases. Implementations used in contexts where roll integrity matters (e.g., gambling, competitive play) SHOULD use a CSPRNG and SHOULD document their randomness source.
Annotation Privacy: Annotation text ([text]) may contain personally identifiable information (PII) or sensitive context (e.g., character names, campaign details). Implementations that log, persist, or transmit roll results SHOULD treat annotation content as potentially sensitive and apply appropriate data handling policies.
10. Conformance Levels
Implementations MAY claim conformance to this specification at one of four levels. Each level is a strict superset of the previous level. The levels follow how widely a feature is supported by the dice platforms named in Section 13.2 ([ROLL20], [FOUNDRYVTT], [AVRAE], [RPGDICEROLLER], [SOPHIESDICE], [GNOLL], [DICEMAIDEN]), so that Level 2 is enough to run most published games.
10.1 Feature Levels
Table 10.1 is normative: it assigns every feature of this specification to exactly one level.
| Feature | Notation | Section | Level |
|---|---|---|---|
| Standard dice | NdS |
4.1 | 1 |
| Additional pools | +NdS, -NdS, leading - |
8.7 | 1 |
| Plus | +N |
6.6.4 | 1 |
| Minus | -N |
6.7.4 | 1 |
| Multiply | *N |
6.6.3 | 1 |
| Drop lowest / highest | L, Ln, H, Hn |
6.5.4 | 1 |
| Keep highest / lowest | K, Kn, kl, klN |
6.7.1 | 1 |
| Case insensitivity, whitespace | (lexical) | 8.1, 8.2 | 1 |
| Rejecting invalid notation | (errors) | 9.5 | 1 |
| Condition expressions | {>=N,<N,...} |
5 | 2 |
| Conditional drop | D{...} |
6.5.4 | 2 |
| Reroll | R{...}, R{...}N |
6.5.2 | 2 |
| Reroll Once | ro{...} |
6.7.3 | 2 |
| Explode | ! |
6.5.6 | 2 |
| Conditional explode | !{...} |
6.5.6 | 2 |
| Count | #{...} |
6.6.2 | 2 |
| Count Successes | S{N}, S{N,B} |
6.7.7 | 2 |
| Count Failures | F{N} |
6.7.8 | 2 |
| Cap | C{...} |
6.4.2 | 3 |
| Replace | V{...} |
6.4.3 | 3 |
| Compound | !!, !!N |
6.5.8 | 3 |
| Penetrate | !p, !pN |
6.5.9 | 3 |
| Unique | U, U{...} |
6.5.3 | 3 |
| Keep Middle | KM, KMn |
6.7.2 | 3 |
| Multiply Total | **N |
6.7.6 | 3 |
| Integer Divide | //N |
6.6.5 | 3 |
| Modulo | %N |
6.6.6 | 3 |
| Sort | sa, sd |
6.8.1 | 3 |
| Annotations | [text] |
6.8.2 | 3 |
| Custom Faces dice | d{...} |
4.2 | 3 |
| Percentile dice | d% |
4.5.1 | 3 |
| Fate/Fudge dice | dF, dF.1, dF.2 |
4.5.2 | 3 |
| Zero-Bias dice | zN |
4.5.3 | 4 |
| Geometric dice | gN |
4.3 | 4 |
| Draw dice | DDN |
4.4 | 4 |
| Explode Sequence | !s{...} |
6.5.7 | 4 |
| Inflation | !i |
6.7.9 | 4 |
| Reduction | !r |
6.7.10 | 4 |
| Wild Die | W |
6.5.10 | 4 |
| Conditional compound / penetrate | !!{...}, !p{...} |
6.5.8, 6.5.9 | 4 |
| Margin of Success | ms{N} |
6.7.5 | 4 |
| Repeat | xN |
6.8.3 | 4 |
10.2 Level 1 – Core
Features supported by every major dice platform: standard dice, additional pools, arithmetic, and positional drop and keep. A Level 1 implementation handles the common 1d20+5 and 4d6L rolls.
10.3 Level 2 – VTT Baseline
Features supported by 5 or more of the 7 platforms. This level covers running games on any mainstream VTT: D&D 5e, World of Darkness, PbtA, and most published systems. Includes all Level 1 features plus the features marked Level 2 in Table 10.1.
10.4 Level 3 – Extended
Features supported by 2 to 4 platforms. Covers Savage Worlds (Compound), Hackmaster (Penetrate), Fate Core (dF), custom dice systems, and advanced pool mechanics. Includes all Level 2 features plus the features marked Level 3 in Table 10.1.
10.5 Level 4 – Full
RANDSUM extensions and features with 0 or 1 platform precedent. Includes all Level 3 features plus the features marked Level 4 in Table 10.1. The reference implementation (Section 11.5) conforms at Level 4.
10.6 Claiming Conformance
An implementation conforms at a level when it implements every feature of that level and of every lower level as specified, and passes every conformance vector required for that level (Appendix G.15), including every error vector.
A conformance claim MUST name the specification version and the level, in this form:
RDN 0.9.0 Level 2 (VTT Baseline) conformantAn implementation MAY support individual features from a higher level without claiming that level, provided all features of the claimed level are fully supported. It MUST NOT claim the higher level until it supports all of that level’s features. A feature it does support from a higher level MUST behave as specified.
10.7 Conformance Badges (Informative)
This section is non-normative.
The RANDSUM project publishes a badge for each level, to place beside a conformance claim in a README or on a product page. Badges are served at:
https://notation.randsum.dev/badges/v0.9.0/level-1.svg -- Corehttps://notation.randsum.dev/badges/v0.9.0/level-2.svg -- VTT Baselinehttps://notation.randsum.dev/badges/v0.9.0/level-3.svg -- Extendedhttps://notation.randsum.dev/badges/v0.9.0/level-4.svg -- FullLink a badge to this specification so readers can check what it promises:
[](https://notation.randsum.dev/#10-conformance-levels)Display only the badge for the level the implementation conforms at (Section 10.6). Copy-paste snippets for every badge are at https://notation.randsum.dev/conformance/.
11. Implementing This Specification
11.1 Overview
This section provides guidance for developers implementing an RDN-compliant parser in any programming language. The reference implementation is the @randsum/roller TypeScript package (source).
11.2 Recommended Implementation Order
Implementations SHOULD follow this order to incrementally pass conformance levels:
- Lexer/tokenizer — split notation into tokens: quantity, separator, sides, modifier suffixes
- Core dice expression (NdS) — handle quantity, sides, and the
dseparator - Stage 3 modifiers — arithmetic operations (+, -, *, //) are the simplest transformations
- Stage 2 modifiers — pool manipulation (drop, keep, reroll, explode) requires tracking individual dice
- Stage 1 modifiers — value remapping (cap, replace) runs before pool manipulation
- Special dice — percentile (d%), Fate (dF), custom faces (d{…}), geometric (gN), draw (DDN)
- Aliases and sugar — K, kl, S{}, F{}, ms{}, ro{}, ** as sugar over primitives
11.3 Conformance Test Suite
A machine-readable test suite is available for download:
Download conformance vectors (JSON)
The JSON file contains every test vector from Appendix G with structured fields:
id,notation,category— the vector’s number, input notation string and groupseedRolls— the dice values the initial pool rolls (replace your RNG). For a notation of several pools, the values feed the pools in notation order. On a Custom Faces die a value is the 1-based position of a face in the listrerollRolls,explodeRolls,compoundRolls,penetrateRolls,sequenceRolls— further values, consumed in that order afterseedRolls; a sequence roll is the value on its own sequence die. Unique’s re-rolls are inrerollRollsand Wild Die’s added rolls incompoundRollsexpectedPool— the dice pool after all modifiers; for a notation of several pools, the pools one after another in notation orderexpectedTotal— the final scalar result, ornullwhere there is none (string faces)expectedResults— on a repeated notation (xN), in place ofexpectedPoolandexpectedTotal: onepoolandtotalfor each evaluation, in order.seedRollsfeeds the evaluations one after anotherexpectedError,errorDescription— present on vectors the implementation MUST rejectsection— the spec section that defines the behaviorconformanceLevel— on a result vector, the lowest level that requires it; on an error vector, the level of the feature it exercises (every level requires every error vector)note— an explanation where the result is not obviousunseeded— on vectors whose result depends on how an implementation maps random numbers to faces and shuffles: thefacesevery pool value MUST be one of, and whether the values aredistinct
The top-level conformanceLevels object lists the vector ids each level requires. The file’s JSON Schema is at notation.randsum.dev/conformance/conformance.schema.json.
To use: configure your implementation to accept a deterministic random function, feed each vector’s rolls as the RNG output, and compare your pool and total against the expected values. Vectors with string faces (31) or draw dice (33, 51) depend on how an implementation maps random numbers to faces and shuffles. Where an implementation cannot replay their rolls, it passes them when its pool has the expected size, every value is one of the vector’s unseeded.faces, no value repeats when unseeded.distinct is true, and its total is the pool’s sum, or absent where the vector has none. Such a pass shows the die works; it does not test a modifier on that die, so vector 51 checks that 3DD6L is accepted and returns two dice, not which die Drop removed.
An implementation rejects an error vector by signaling an error and returning no result (Section 9.5). A repeated notation yields one result per evaluation (Section 6.8.3), and each MUST match its entry in expectedResults; a single combined pool or total does not pass.
11.3.1 Conformance Runner (Informative)
This section is non-normative.
The rdn-conformance runner, published in the @randsum/notation-spec npm package and at github.com/RANDSUM/notation-spec, runs every vector against an implementation in any language and reports the highest level it reaches, with that level’s badge (Section 10.7):
npx @randsum/notation-spec --level 2 -- python3 my_adapter.pyThe implementation is wrapped in a small adapter program. The runner writes one JSON object per line to the adapter’s standard input, holding the vector’s id, notation and roll fields, and reads one JSON object per line from its standard output: {"id": 3, "pool": [3, 5, 2], "total": 10} for a result, {"id": 28, "error": "..."}, a message and nothing else, when the implementation rejects the notation, {"id": 106, "results": [{"pool": [6, 3, 2], "total": 11}, {"pool": [4, 4, 5], "total": 13}]} for a repeated notation, and "seeded": false added to a result rolled without replaying the vector’s rolls. The repository’s README defines the protocol in full and includes the reference adapter for @randsum/roller and a skeleton to start from.
11.4 Claiming Conformance
Section 10.6 defines a conformance claim and its wording. Appendix G.15 lists the vectors each level requires, the error vectors among them. Section 10.7 describes the badges for each level.
11.5 Reference Implementation
The canonical reference implementation is @randsum/roller:
- Source: github.com/RANDSUM/randsum/tree/main/packages/roller
- npm:
@randsum/roller - Subpath exports:
@randsum/roller/roll(roll function),@randsum/roller/validate(validation),@randsum/roller/tokenize(tokenizer),@randsum/roller/random(createQueueRandom, a random function that replays fixed die values) - Conformance: RDN 0.9.0 Level 4 (Full). Its test suite replays every vector; for 31, 33 and 51, which depend on the shuffle, it checks the pool’s size and values
Where an implementation offers a canonical form of a notation string, as the reference implementation’s validator does, that form MUST re-parse to the same roll: the same die type, faces, modifiers and annotation. z6 MUST NOT be given back as 1d6.
The roller accepts a custom random function via RollConfig.randomFn, enabling deterministic testing with the conformance vectors.
12. IANA Considerations
This document has no IANA actions. A later version might register a media type for RDN notation strings if protocol-level identification becomes necessary.
13. References
13.1 Normative References
- [BCP14] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, March 1997; Leiba, B., “Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words”, BCP 14, RFC 8174, May 2017.
- [RFC5234] Crocker, D., Ed. and P. Overell, “Augmented BNF for Syntax Specifications: ABNF”, STD 68, RFC 5234, January 2008.
- [RFC7405] Kyzivat, P., “Case-Sensitive String Support in ABNF”, RFC 7405, December 2014.
- [RFC3629] Yergeau, F., “UTF-8, a transformation format of ISO 10646”, STD 63, RFC 3629, November 2003.
13.2 Informative References
- [ROLL20] Roll20 Virtual Tabletop, “Dice Reference”, https://wiki.roll20.net/Dice_Reference
- [FOUNDRYVTT] Foundry Virtual Tabletop, “Dice”, https://foundryvtt.com/article/dice/
- [AVRAE] Avrae Discord Bot, “Dice Syntax”, https://avrae.readthedocs.io/en/latest/cheatsheets/dice_reference.html
- [RPGDICEROLLER] rpg-dice-roller, https://dice-roller.github.io/documentation/
- [SOPHIESDICE] Sophie Houlden, “Dice Notation”, https://sophiehoulden.com/dice/documentation/notation.html
- [GNOLL] GNOLL Dice Notation, https://github.com/ianfhunter/GNOLL
- [DICEMAIDEN] Dice Maiden Discord Bot, https://github.com/Humblemonk/DiceMaiden
Appendix A Priority Table
Complete modifier priority ordering. Modifiers execute in ascending priority order.
| Priority | Name | Stage | Verb | Channel | Status |
|---|---|---|---|---|---|
| 10 | Cap | 1 | Clamp | Pool | Primitive |
| 30 | Replace | 1 | Map | Pool | Primitive |
| 40 | Reroll | 2 | Substitute | Pool | Primitive |
| 50 | Explode | 2 | Generate | Pool | Primitive |
| 51 | Compound | 2 | Accumulate | Pool | Primitive |
| 52 | Penetrate | 2 | Accumulate | Pool | Primitive |
| 53 | Explode Sequence | 2 | Generate | Pool | Primitive |
| 55 | Wild Die | 2 | Dispatch | Pool | Macro |
| 60 | Unique | 2 | Substitute | Pool | Primitive |
| 65 | Drop | 2 | Filter | Pool | Primitive |
| 66 | Keep | 2 | Filter | Pool | Alias |
| 80 | Count | 3 | Reinterpret | Total | Primitive |
| 85 | Multiply | 3 | Scale | Total | Primitive |
| 90 | Plus | 3 | Scale | Total | Primitive |
| 91 | Minus | 3 | Scale | Total | Alias |
| 93 | Integer Divide | 3 | Scale | Total | Primitive |
| 94 | Modulo | 3 | Scale | Total | Primitive |
| 95 | Sort | 3 | – | Pool | Directive |
| 100 | Multiply Total | 3 | Scale | Total | Alias |
Appendix B Alias De-Aliasing Table
| Alias | Notation | Primitive | De-Aliasing Rule |
|---|---|---|---|
| Keep | KN |
Drop | KN on Q dice = Drop lowest (Q - N) |
| Keep (lowest) | klN |
Drop | klN on Q dice = Drop highest (Q - N) |
| Keep Middle | KMn |
Drop | Drop lowest n + Drop highest n (n defaults to 1) |
| Reroll Once | ro{...} |
Reroll | Reroll with once: true (each die once) |
| Minus | -N |
Plus | Plus with negated operand: +(-N) |
| Margin of Success | ms{N} |
Plus | Minus N -> Plus (-N). Transitive chain. |
| Multiply Total | **N |
Multiply | Multiply at priority 100 (post-arithmetic) |
| Count Successes | S{N}, S{N,B} |
Count | Count dice at or above N; with B, less the dice at or below B |
| Count Failures | F{N} |
Count | Count with lessThanOrEqual: N |
| Inflation | !i |
Explode Sequence | Standard sizes above S, ascending |
| Reduction | !r |
Explode Sequence | Standard sizes below S, descending |
Appendix C Full Faceted Records
Complete faceted classification for every modifier, alias, macro, and directive in RDN.
| Modifier | Notation | Status | Stage | Verb | Channel | Priority | Pool Size | Options | Group |
|---|---|---|---|---|---|---|---|---|---|
| Cap | C{...} |
Primitive | 1 | Clamp | Pool | 10 | Unchanged | ComparisonOptions | Value Transformers (E.1) |
| Replace | V{...} |
Primitive | 1 | Map | Pool | 30 | Unchanged | ReplaceOptions | Value Transformers (E.1) |
| Reroll | R{...} |
Primitive | 2 | Substitute | Pool | 40 | Unchanged | RerollOptions | Pool Shapers (E.2) |
| Reroll Once | ro{...} |
Alias -> Reroll | 2 | Substitute | Pool | 40 | Unchanged | RerollOptions (once: true) | Pool Shapers (E.2) |
| Explode | ! |
Primitive | 2 | Generate | Pool | 50 | Grows | boolean | ComparisonOptions | Explosion Variants (E.3) |
| Compound | !! |
Primitive | 2 | Accumulate | Pool | 51 | Preserved | boolean | number | ComparisonOptions | Explosion Variants (E.3) |
| Penetrate | !p |
Primitive | 2 | Accumulate | Pool | 52 | Preserved | boolean | number | ComparisonOptions | Explosion Variants (E.3) |
| Explode Sequence | !s{...} |
Primitive | 2 | Generate | Pool | 53 | Grows | number[] | Explosion Variants (E.3) |
| Inflation | !i |
Alias -> Explode Sequence | 2 | Generate | Pool | 53 | Grows | number[] (standard sizes above S) | Explosion Variants (E.3) |
| Reduction | !r |
Alias -> Explode Sequence | 2 | Generate | Pool | 53 | Grows | number[] (standard sizes below S) | Explosion Variants (E.3) |
| Wild Die | W |
Macro | 2 | Dispatch | Pool | 55 | Varies | boolean | Explosion Variants (E.3) |
| Unique | U, U{...} |
Primitive | 2 | Substitute | Pool | 60 | Unchanged | boolean | UniqueOptions | Pool Shapers (E.2) |
| Drop | L, H, D{...} |
Primitive | 2 | Filter | Pool | 65 | Shrinks | DropOptions | Pool Shapers (E.2) |
| Keep | K, kl |
Alias -> Drop | 2 | Filter | Pool | 66 | Shrinks | KeepOptions | Pool Shapers (E.2) |
| Keep Middle | KM, KMn |
Alias -> Drop | 2 | Filter | Pool | 65 | Shrinks | DropOptions (lowest: n, highest: n) | Pool Shapers (E.2) |
| Count | #{...} |
Primitive | 3 | Reinterpret | Total | 80 | N/A | CountOptions | Counting (E.5) |
| Count Successes | S{N} |
Alias -> Count | 3 | Reinterpret | Total | 80 | N/A | CountOptions (greaterThanOrEqual: N) | Counting (E.5) |
| Count Failures | F{N} |
Alias -> Count | 3 | Reinterpret | Total | 80 | N/A | CountOptions (lessThanOrEqual: N) | Counting (E.5) |
| Multiply | *N |
Primitive | 3 | Scale | Total | 85 | N/A | number | Arithmetic (E.4) |
| Plus | +N |
Primitive | 3 | Scale | Total | 90 | N/A | number | Arithmetic (E.4) |
| Minus | -N |
Alias -> Plus | 3 | Scale | Total | 91 | N/A | number | Arithmetic (E.4) |
| Margin of Success | ms{N} |
Alias -> Plus (via Minus) | 3 | Scale | Total | 91 | N/A | number | Arithmetic (E.4) |
| Integer Divide | //N |
Primitive | 3 | Scale | Total | 93 | N/A | number | Arithmetic (E.4) |
| Modulo | %N |
Primitive | 3 | Scale | Total | 94 | N/A | number | Arithmetic (E.4) |
| Sort | sa/sd |
Presentation Directive | 3 | – | Pool (display only) | 95 | Unchanged | ‘asc’ | ‘desc’ | Display (E.6) |
| Multiply Total | **N |
Alias -> Multiply | 3 | Scale | Total | 100 | N/A | number | Arithmetic (E.4) |
Appendix D Four-Gate Test for Extensions
Any proposed addition to the RANDSUM Dice Notation MUST pass all four gates:
Gate 1: Mechanical
The feature MUST operate on dice values, the dice pool, or the total. Features that do not interact with the dice pipeline are out of scope for RDN. (They may belong in game-specific specifications.)
Gate 2: Game-Agnostic Describable
The feature MUST be explainable without naming a specific game system. “Reroll dice below 3” passes. “Roll Blades in the Dark resistance” fails. Game-specific mechanics belong in game packages, not in the notation.
Gate 3: Precedented
The feature MUST be supported by at least 2 other dice platforms (Roll20, FoundryVTT, Avrae, rpg-dice-roller, etc.) OR be used by at least 3 published tabletop game systems.
Gate 4: Composable
The feature MUST work with existing modifiers without introducing a new return type, channel, or pipeline stage. It MUST be assignable to an existing verb and stage, or the proposal MUST include a justification for extending the taxonomy.
All four gates MUST pass. A feature that fails any single gate is rejected. The proposer MAY revise the feature to address the failing gate and resubmit.
Appendix E Operational Groups (Informative)
This section is non-normative.
This appendix provides a player-facing view of modifiers organized by what they do, rather than by pipeline stage. This grouping is informative and does not override the normative definitions in Section 6.
E.1 Value Transformers
Modifiers that change individual die values without adding or removing dice.
| Modifier | Notation | Effect |
|---|---|---|
| Cap | C{...} |
Clamp values to boundaries |
| Replace | V{...} |
Substitute specific values |
E.2 Pool Shapers
Modifiers that change which dice remain in the pool or re-randomize their values.
| Modifier | Notation | Type | Effect |
|---|---|---|---|
| Drop | L, H, D{...} |
Primitive | Remove dice from pool |
| Keep | K, kl |
Alias (Drop) | Keep N dice, drop the rest |
| Keep Middle | KM |
Alias (Drop) | Drop lowest and highest |
| Reroll | R{...} |
Primitive | Re-roll matching dice |
| Reroll Once | ro{...} |
Alias (Reroll) | Re-roll matching dice at most once |
| Unique | U |
Primitive | Enforce no duplicate values |
E.3 Explosion Variants
Modifiers that generate additional dice or accumulate values on trigger conditions.
| Modifier | Notation | Type | Effect |
|---|---|---|---|
| Explode | ! |
Primitive | Add new die on max |
| Compound | !! |
Primitive | Fold extra rolls into existing die |
| Penetrate | !p |
Primitive | Fold extra rolls minus 1 |
| Explode Sequence | !s{...} |
Primitive | Step through die sizes |
| Inflation | !i |
Alias (Explode Sequence) | Ascending standard set |
| Reduction | !r |
Alias (Explode Sequence) | Descending standard set |
| Wild Die | W |
Macro | D6 System wild die dispatch |
E.4 Arithmetic
Modifiers that perform arithmetic on the total.
| Modifier | Notation | Type | Effect |
|---|---|---|---|
| Plus | +N |
Primitive | Add N to total |
| Minus | -N |
Alias (Plus) | Subtract N from total |
| Margin of Success | ms{N} |
Alias (Plus) | Subtract target N from total |
| Multiply | *N |
Primitive | Multiply total (pre-arithmetic) |
| Multiply Total | **N |
Alias (Multiply) | Multiply total (post-arithmetic) |
| Integer Divide | //N |
Primitive | Truncating division |
| Modulo | %N |
Primitive | Remainder |
E.5 Counting
Modifiers that replace the summation model with a count.
| Modifier | Notation | Type | Effect |
|---|---|---|---|
| Count | #{...} |
Primitive | Count dice matching conditions |
| Count Successes | S{N} |
Alias (Count) | Count dice >= N |
| Count Failures | F{N} |
Alias (Count) | Count dice <= N |
E.6 Display
Notation features that affect presentation without altering the total.
| Feature | Notation | Effect |
|---|---|---|
| Sort | sa, sd |
Reorder pool ascending/descending |
Appendix F Formal Grammar (ABNF)
This appendix provides a formal grammar for RDN notation per RFC 5234 (ABNF, [RFC5234]) with the case-sensitive string extension from RFC 7405 ([RFC7405]). Its terminals are Unicode scalar values, not octets. All alphabetic literals use %i (case-insensitive). This grammar describes input with leading and trailing whitespace removed (Section 8.2).
The following prose constraints supplement the grammar where ABNF cannot express negative lookahead, ordered alternation, or counting. ABNF alternation is unordered; these constraints settle every overlap.
- P1:
S/sfollowed by{ismod-count-successes; followed byaordit ismod-sort. - P2: When input contains
**followed by digits, implementations MUST matchmod-multiply-total, notmod-multiplyfollowed by stray*. - P3: When input begins with
!, implementations MUST attempt matches in order:!!(compound),!p(penetrate),!s{(explode sequence),!i(inflation),!r(reduction), then bare!(explode). The choice is committed: after!!matches, the parser MUST NOT go back and read the first!as a bare Explode, so4d6!!!is Compound then Explode and4d6!!pMUST be rejected.!!immediately followed bys{MUST be rejected.mod-reductionMUST NOT match whenr/Ris immediately followed by{oro{: there the!is a bare Explode and the rest is Reroll or Reroll Once, so4d6!R{<3}is Explode then Reroll, while1d20!RR{<3}is Reduction then Reroll. - P4: A sign followed by a
die-corestarts a newpool; a sign followed by digits that do not begin adie-coreismod-plusormod-minus.+3d6is a pool and+3is Plus. - P5: A conforming parser MUST reject any
poolcontaining more than one Count-family modifier (#{},S{},F{}). - P6: Within one
pool, a modifier MUST NOT appear twice unless it ismod-plus,mod-minus,mod-margin-of-success,mod-drop-lowestormod-drop-highest, or both occurrences are the same operand-free flag (Section 6.9).mod-explode-seq,mod-inflationandmod-reductioncount as one modifier, as domod-explodewith and without a condition block. Apooltakes at most oneannotation, and MUST NOT hold bothmod-keepandmod-keep-lowest. - P7: Whitespace MUST NOT appear between tokens. It is part of the token only inside an
annotationand inside aface-value, where whitespace around the face is trimmed. - P8: Some strings the grammar derives are errors for reasons the grammar does not carry, and MUST be rejected all the same: a modifier other than a Scale modifier on a geometric die (Section 4.3); an unconditioned
!,!!,!p,!s{},!i,!rorWon a Fate, Zero-Bias or Custom Faces die (Section 4.6); a depth and a condition on one Compound or Penetrate (Sections 6.5.8, 6.5.9); and the quantity checks of Drop, Keep, Unique and Reroll (Sections 6.5.2 to 6.5.5).
;; ===================================================================;; RANDSUM Dice Notation (RDN) v0.9.0;; Augmented Backus-Naur Form (ABNF) per RFC 5234 / RFC 7405;; ===================================================================
;; Top-Levelrdn-input = expression *repeatexpression = [sign] pool *( sign pool )pool = die-core *( modifier / annotation )sign = "+" / "-"
;; Core Die Typesdie-core = draw-die / geometric-die / fate-die / zero-bias-die / custom-faces-die / percentile-die / standard-diestandard-die = [quantity] %i"d" positive-integercustom-faces-die = [quantity] %i"d" "{" face-list "}"face-list = face-value *( "," face-value )face-value = 1*face-char ; not whitespace only (P7)face-char = %x09 / %x20-2B / %x2D-7C / %x7E / non-ascii ; any text but "," and "}"geometric-die = [quantity] %i"g" positive-integerdraw-die = [quantity] %i"dd" positive-integerpercentile-die = [quantity] %i"d" "%"fate-die = [quantity] %i"dF" ["." ("1" / "2")]zero-bias-die = [quantity] %i"z" positive-integerquantity = positive-integer
;; Condition Expressionscondition-block = "{" condition-list "}"condition-list = condition *( "," condition )condition = [comparison-op] non-neg-integercomparison-op = ">=" / "<=" / ">" / "<" / "="
;; Modifiers (alternation is unordered; P1 to P8 settle overlaps)modifier = mod-cap / mod-replace / mod-reroll-once / mod-reroll / mod-explode-seq / mod-inflation / mod-reduction / mod-compound / mod-penetrate / mod-explode / mod-wild-die / mod-unique / mod-drop-conditional / mod-drop-highest / mod-drop-lowest / mod-keep-middle / mod-keep-lowest / mod-keep / mod-count-successes / mod-count-failures / mod-count / mod-multiply-total / mod-multiply / mod-integer-divide / mod-modulo / mod-margin-of-success / mod-minus / mod-plus / mod-sort
;; Stage 1: Deterministic Value Shapingmod-cap = %i"C" condition-blockmod-replace = %i"V" "{" replace-list "}"replace-list = replace-pair *( "," replace-pair )replace-pair = [replace-op] non-neg-integer "=" non-neg-integerreplace-op = ">=" / "<=" / ">" / "<"
;; Stage 2: Pool Dynamicsmod-reroll = %i"R" condition-block [positive-integer]mod-reroll-once = %i"ro" condition-blockmod-explode = "!" [condition-block]mod-compound = "!!" [non-neg-integer / condition-block]mod-penetrate = "!" %i"p" [non-neg-integer / condition-block]mod-explode-seq = "!" %i"s" "{" integer-list "}"mod-inflation = "!" %i"i"mod-reduction = "!" %i"r"mod-wild-die = %i"W"mod-unique = %i"U" ["{" non-neg-integer *("," non-neg-integer) "}"]mod-drop-lowest = %i"L" [non-neg-integer]mod-drop-highest = %i"H" [non-neg-integer]mod-drop-conditional = %i"D" condition-blockmod-keep = %i"K" [positive-integer]mod-keep-lowest = %i"kl" [positive-integer]mod-keep-middle = %i"km" [positive-integer]
;; Stage 3: Total Derivationmod-count = "#" condition-blockmod-count-successes = %i"S" "{" non-neg-integer ["," non-neg-integer] "}"mod-count-failures = %i"F" "{" non-neg-integer "}"mod-multiply = "*" non-neg-integermod-plus = "+" non-neg-integermod-minus = "-" non-neg-integermod-integer-divide = "//" positive-integermod-modulo = "%" positive-integermod-sort = %i"sa" / %i"sd"mod-multiply-total = "**" non-neg-integermod-margin-of-success = %i"ms" "{" non-neg-integer "}"
;; Non-Modifier Featuresrepeat = %i"x" positive-integerannotation = "[" 1*( %x09 / %x20-5C / %x5E-7E / non-ascii ) "]";; Unicode scalar values above ASCII, excluding surrogatesnon-ascii = %x80-D7FF / %xE000-10FFFF
;; Numeric Primitivespositive-integer = %x31-39 *DIGITnon-neg-integer = 1*DIGITinteger-list = positive-integer *( "," positive-integer )DIGIT = %x30-39Appendix G Conformance Test Vectors
The following test vectors enable independent implementors to verify conformance with RDN v0.9.0. The vectors file (Section 11.3) is the normative form of these tables. Each vector specifies a notation input, fixed dice values (the raw values the RNG would produce, in order), the expected pool after all modifiers, and the expected total.
Conventions:
- “Seed/Rolls” lists the raw die values produced by the RNG, in order consumed
- “Expected Pool” is the pool array after all modifiers have executed
- “Expected Total” is the scalar result after total derivation
- “ERROR” means the implementation MUST reject the notation
G.1 Dice Expressions
| # | Notation | Seed/Rolls | Expected Pool | Expected Total | Section |
|---|---|---|---|---|---|
| 1 | 1d20 |
[14] | [14] | 14 | 4.1 |
| 2 | d20 |
[14] | [14] | 14 | 4.1 |
| 3 | 3d6 |
[3, 5, 2] | [3, 5, 2] | 10 | 4.1 |
| 4 | d% |
[73] | [73] | 73 | 4.5.1 |
| 5 | 4dF |
[-1, 0, 1, 1] | [-1, 0, 1, 1] | 1 | 4.5.2 |
| 6 | 1dF.2 |
[-2] | [-2] | -2 | 4.5.2 |
G.2 Stage 1 Modifiers
| # | Notation | Seed/Rolls | Expected Pool | Expected Total | Section |
|---|---|---|---|---|---|
| 7 | 4d6C{5} |
[6, 3, 5, 6] | [5, 3, 5, 5] | 18 | 6.4.2 |
| 8 | 4d6V{1=6,3=5} |
[1, 3, 4, 1] | [6, 5, 4, 6] | 21 | 6.4.3 |
G.3 Stage 2 Modifiers
| # | Notation | Seed/Rolls | Expected Pool | Expected Total | Section |
|---|---|---|---|---|---|
| 9 | 4d6R{1} |
[1, 3, 5, 2] reroll: [4] | [4, 3, 5, 2] | 14 | 6.5.2 |
| 10 | 4d6L |
[3, 5, 2, 6] | [3, 5, 6] | 14 | 6.5.4 |
| 11 | 4d6H |
[3, 5, 2, 6] | [3, 5, 2] | 10 | 6.5.4 |
| 12 | 4d6! |
[6, 3, 5, 2] explode: [4] | [6, 3, 5, 2, 4] | 20 | 6.5.6 |
| 13 | 4d6! |
[3, 4, 2, 5] | [3, 4, 2, 5] | 14 | 6.5.6 |
G.4 Stage 3 Modifiers
| # | Notation | Seed/Rolls | Expected Pool | Expected Total | Section |
|---|---|---|---|---|---|
| 14 | 2d6+5 |
[3, 4] | [3, 4] | 12 | 6.6.4 |
| 15 | 2d6-3 |
[4, 5] | [4, 5] | 6 | 6.7.4 |
| 16 | 2d6*3 |
[2, 4] | [2, 4] | 18 | 6.6.3 |
| 17 | 2d6//3 |
[4, 5] | [4, 5] | 3 | 6.6.5 |
| 18 | 5d10#{>=7} |
[8, 3, 10, 7, 2] | [8, 3, 10, 7, 2] | 3 | 6.6.2 |
G.5 Aliases
| # | Notation | Seed/Rolls | Expected Pool | Expected Total | Section |
|---|---|---|---|---|---|
| 19 | 4d6K3 |
[2, 5, 3, 6] | [5, 3, 6] | 14 | 6.7.1 |
| 20 | 4d6kl |
[2, 5, 3, 6] | [2] | 2 | 6.7.1 |
| 21 | 5d10S{7} |
[8, 3, 10, 7, 2] | [8, 3, 10, 7, 2] | 3 | 6.7.7 |
| 22 | 5d10F{3} |
[8, 3, 10, 1, 2] | [8, 3, 10, 1, 2] | 3 | 6.7.8 |
| 23 | 1d20ms{15} |
[18] | [18] | 3 | 6.7.5 |
G.6 Non-Modifier Features
| # | Notation | Seed/Rolls | Expected Pool | Expected Total | Section |
|---|---|---|---|---|---|
| 24 | 4d6sa |
[3, 1, 5, 2] | [1, 2, 3, 5] | 11 | 6.8.1 |
| 25 | 2d6+3[fire] |
[4, 5] | [4, 5] | 12 | 6.8.2 |
G.7 Case Insensitivity
| # | Notation | Seed/Rolls | Expected Pool | Expected Total | Section |
|---|---|---|---|---|---|
| 26 | 2D6 |
[3, 4] | [3, 4] | 7 | 8.1 |
| 27 | 4D6l |
[3, 5, 2, 6] | [3, 5, 6] | 14 | 8.1 |
G.8 Error Cases
| # | Notation | Expected | Section |
|---|---|---|---|
| 28 | 4d |
ERROR | 9.5 |
| 29 | d |
ERROR | 9.5 |
| 30 | d0 |
ERROR | 9.5 |
G.9 Extended Coverage
| # | Notation | Seed/Rolls | Expected Pool | Expected Total | Section |
|---|---|---|---|---|---|
| 31 | 2d{fire,ice,lightning} |
[face2=ice, face1=fire] | [ice, fire] | N/A (string faces) | 4.2 |
| 32 | g6 |
[6, 6, 3] | [6, 6, 3] | 15 | 4.3 |
| 33 | 3DD6 |
[4, 1, 6] | [4, 1, 6] | 11 | 4.4 |
| 34 | z6 |
[0] | [0] | 0 | 4.5.3 |
| 35 | 3d6U |
[3, 3, 5] reroll: [4] | [3, 4, 5] | 12 | 6.5.3 |
| 36 | 2d6!! |
[6, 3] compound: [4] | [10, 3] | 13 | 6.5.8 |
| 37 | 2d6!p |
[6, 3] penetrate: [3] | [8, 3] | 11 | 6.5.9 |
| 38 | 5d6W |
[6, 3, 4, 2, 5] | [6, 3, 4, 2, 5] | 20 | 6.5.10 |
| 39 | 3d6!s{4,6,8} |
[6, 2, 5] sequence: [3] (on the d4) | [6, 2, 5, 3] | 16 | 6.5.7 |
| 40 | 2d6%4 |
[3, 5] | [3, 5] | 0 | 6.6.6 |
| 41 | 2d6**2 |
[3, 4] | [3, 4] | 14 | 6.7.6 |
| 42 | 4d6C{5}L!+2 |
[6, 1, 5, 6] cap: [5, 1, 5, 5], no 6 left to explode, drop lowest | [5, 5, 5] | 17 | 6.9 |
| 43 | 4d6ro{1} |
[1, 3, 5, 4] reroll: [2] | [2, 3, 5, 4] | 14 | 6.7.3 |
| 44 | 6d6KM |
[1, 4, 3, 5, 2, 6] | [4, 3, 5, 2] | 14 | 6.7.2 |
| 45 | 5d10#{>=7,<=2} |
[8, 1, 10, 7, 2] | [8, 1, 10, 7, 2] | 1 | 6.6.2 |
G.10 Additional Error Cases
| # | Notation | Expected | Section |
|---|---|---|---|
| 46 | 0d6 |
ERROR | 9.5 |
| 47 | 5d10S{7}F{3} |
ERROR (multiple Count modifiers) | 6.9 |
| 48 | 4d6 L |
ERROR (whitespace between tokens) | 8.2 |
G.11 Modifiers on Special Dice
| # | Notation | Seed/Rolls | Expected Pool | Expected Total | Section |
|---|---|---|---|---|---|
| 49 | 4dF+1 |
[-1, 0, 1, 1] | [-1, 0, 1, 1] | 2 | 4.5.2 |
| 50 | d%+5 |
[73] | [73] | 78 | 4.5.1 |
| 51 | 3DD6L |
[4, 1, 6] | [4, 6] | 10 | 4.4 |
G.12 Divisor and Face Error Cases
| # | Notation | Expected | Section |
|---|---|---|---|
| 52 | 2d6//0 |
ERROR (zero divisor) | 6.6.5 |
| 53 | 2d6%0 |
ERROR (zero divisor) | 6.6.6 |
| 54 | 4dF! |
ERROR (max-face explosion on dF) | 4.6 |
| 60 | g6L |
ERROR (pool modifier on a geometric die) | 4.3 |
| 61 | 3g6#{>6} |
ERROR (pool modifier on a geometric die) | 4.3 |
G.13 Lexical Disambiguation
| # | Notation | Seed/Rolls | Expected Pool | Expected Total | Section |
|---|---|---|---|---|---|
| 55 | 4d6!R{1} |
[1, 3, 6, 2] reroll: [4] explode: [5] | [4, 3, 6, 2, 5] | 20 | 8.3 |
G.14 Chaining and Reroll Once
| # | Notation | Seed/Rolls | Expected Pool | Expected Total | Section |
|---|---|---|---|---|---|
| 56 | 3d6! |
[6, 4, 6] explode: [6, 2, 3] | [6, 4, 6, 6, 2, 3] | 27 | 6.5.6 |
| 57 | 2d6!! |
[6, 1] compound: [6, 6, 2] | [20, 1] | 21 | 6.5.8 |
| 58 | 2d6!p |
[6, 1] penetrate: [6, 6, 1] | [16, 1] | 17 | 6.5.9 |
| 59 | 4d6ro{1} |
[1, 1, 3, 4] reroll: [1, 2] | [1, 2, 3, 4] | 10 | 6.7.3 |
G.15 Conformance Level Cross-Index
Each vector’s level is the highest level among the features it uses (the table in Section 10.1). A level requires its own vectors and those of every lower level.
| Level | Required Vectors | Features Covered |
|---|---|---|
| Level 1 (Core) | 1-3, 10-11, 14-16, 19-20, 26-27, 62-70 | NdS, +, -, *, L, H, K, kl, case, pools, whitespace |
| Level 2 (VTT Baseline) | All Level 1 + 9, 12-13, 18, 21-22, 43, 45, 55-56, 59, 71-78 | R, ro, !, !{}, D{}, #, S{}, F{}, conditions |
| Level 3 (Extended) | All Level 2 + 4-8, 17, 24-25, 31, 35-37, 40-42, 44, 49-50, 57-58, 79-90 | d%, dF, C, V, //, sa, sd, [text], d{}, U, !!, !p, %, **, KM |
| Level 4 (Full) | All Level 3 + 23, 32-34, 38-39, 51, 91-97, 106-107 | ms{}, gN, DDN, zN, W, !s{}, !i, !r, !!{}, !p{}, xN |
| Error Cases | 28-30, 46-48, 52-54, 60-61, 98-105 (required at every level) | Invalid notation rejection |
G.16 Pool Order, Pools and Whitespace
| # | Notation | Seed/Rolls | Expected Pool | Expected Total | Section |
|---|---|---|---|---|---|
| 62 | 4d6L |
[6, 1, 3, 2] | [6, 3, 2] | 11 | 6.5.4 |
| 63 | 3d6L |
[1, 5, 1] | [5, 1] | 6 | 6.5.4 |
| 64 | 4d6L2 |
[3, 5, 2, 6] | [5, 6] | 11 | 6.5.4 |
| 65 | 4d6kl2 |
[5, 1, 5, 3] | [1, 3] | 4 | 6.7.1 |
| 66 | 2d6+1d8 |
[3, 4, 8] | [3, 4, 8] | 15 | 8.7 |
| 67 | 1d20-1d6+3 |
[10, 1] | [10, 1] | 6 | 8.7 |
| 68 | 2d6 |
[3, 4] | [3, 4] | 7 | 8.2 |
| 69 | 1d6-7 |
[1] | [1] | -6 | 6.7.4 |
Vector 68 has one space before and one after the notation. In 66 and 67 the seed values feed the pools in notation order, and the expected pool is the pools one after another.
G.17 Execution Order
Each of these gives a different answer when modifiers run in the order written.
| # | Notation | Seed/Rolls | Expected Pool | Expected Total | Section |
|---|---|---|---|---|---|
| 70 | 2d6+3*2 |
[3, 4] | [3, 4] | 17 | 6.9 |
| 74 | 3d6H! |
[6, 2, 3] explode: [4] | [2, 3, 4] | 9 | 6.9 |
| 83 | 2d6**2+3 |
[3, 4] | [3, 4] | 20 | 6.9 |
G.18 Conditions, Counts and Depths
| # | Notation | Seed/Rolls | Expected Pool | Expected Total | Section |
|---|---|---|---|---|---|
| 71 | 4d6D{<3} |
[1, 5, 2, 6] | [5, 6] | 11 | 6.5.4 |
| 72 | 4d6D{>4,>2} |
[1, 2, 5, 6] | [1, 2] | 3 | 5.2 |
| 73 | 3d6!{>4} |
[5, 2, 3] explode: [6, 1] | [5, 2, 3, 6, 1] | 17 | 6.5.6 |
| 75 | 4d6R{<3}1 |
[1, 2, 5, 6] reroll: [4] | [4, 2, 5, 6] | 17 | 6.5.2 |
| 76 | 4d6R{<2,>5} |
[1, 6, 3, 4] reroll: [3, 2] | [3, 2, 3, 4] | 12 | 5.2 |
| 77 | 3d6R{1} |
[1, 1, 3] reroll: [1, 4, 5] | [4, 5, 3] | 12 | 6.5.1 |
| 78 | 5d10S{7,2} |
[8, 1, 10, 7, 2] | [8, 1, 10, 7, 2] | 1 | 6.7.7 |
| 79 | 4d6C{>5,<2} |
[6, 1, 3, 2] | [5, 2, 3, 2] | 12 | 6.4.2 |
| 80 | 2d6//2 |
[3, 4] | [3, 4] | 3 | 6.6.5 |
| 81 | 1d6-7//2 |
[1] | [1] | -3 | 6.6.5 |
| 82 | 1d6-8%3 |
[1] | [1] | -1 | 6.6.6 |
| 84 | 4d6sd |
[3, 1, 5, 2] | [5, 3, 2, 1] | 11 | 6.8.1 |
| 85 | 2d6!!1 |
[6, 1] compound: [6] | [12, 1] | 13 | 6.5.8 |
| 86 | 2d6!! |
[6, 6] compound: [6, 2, 3] | [14, 9] | 23 | 6.5.1 |
| 87 | 3d6U |
[3, 3, 5] reroll: [5, 4] | [3, 5, 4] | 12 | 6.5.3 |
| 88 | 4d6U{1} |
[1, 1, 3, 3] reroll: [2] | [1, 1, 3, 2] | 7 | 6.5.3 |
| 89 | 6d6KM2 |
[1, 4, 3, 5, 2, 6] | [4, 3] | 7 | 6.7.2 |
| 90 | 2dF.1 |
[-1, 1] | [-1, 1] | 0 | 4.5.2 |
G.19 Wild Die, Conditional Accumulation and Sequences
| # | Notation | Seed/Rolls | Expected Pool | Expected Total | Section |
|---|---|---|---|---|---|
| 91 | 3d6W |
[3, 4, 6] compound: [6, 2] | [3, 4, 14] | 21 | 6.5.10 |
| 92 | 3d6W |
[3, 5, 1] | [3] | 3 | 6.5.10 |
| 93 | 2d6!!{>4} |
[5, 1] compound: [6, 2] | [13, 1] | 14 | 6.5.8 |
| 94 | 2d6!p{>4} |
[5, 1] penetrate: [6, 2] | [11, 1] | 12 | 6.5.9 |
| 95 | g6ms{3} |
[6, 2] | [6, 2] | 5 | 4.3 |
| 96 | 1d6!i |
[6] sequence: [8] (d8), [3] (d10) | [6, 8, 3] | 17 | 6.7.9 |
| 97 | 1d6!r |
[6] sequence: [2] (d4) | [6, 2] | 8 | 6.7.10 |
G.20 Further Error Cases
| # | Notation | Expected | Section |
|---|---|---|---|
| 98 | 4d6Q |
ERROR (Q is not a modifier) |
9.5 |
| 99 | 2d6+ |
ERROR (a sign with nothing after it) | 9.5 |
| 100 | 2d6*2*3 |
ERROR (a modifier that sets one value, written twice) | 6.9 |
| 101 | 4d6K2kl |
ERROR (Keep highest with Keep lowest) | 6.9 |
| 102 | 4d6ro{1}2 |
ERROR (Reroll Once takes no count) | 6.7.3 |
| 103 | 4d6!!p |
ERROR (Compound, then a stray p) |
8.3 |
| 104 | z0 |
ERROR (a die with no sides) | 9.5 |
| 105 | 4d6!s{0} |
ERROR (a sequence die with no sides) | 6.5.7 |
G.21 Repeat
A repeated notation has one result per evaluation. The seed feeds the evaluations in order.
| # | Notation | Seed Rolls | Expected Results (pool, total) | Section |
|---|---|---|---|---|
| 106 | 4d6Lx2 |
[6, 1, 3, 2, 4, 4, 2, 5] | [6, 3, 2] = 11; [4, 4, 5] = 13 | 6.8.3 |
| 107 | 2d6+3x3 |
[1, 2, 3, 4, 5, 6] | [1, 2] = 6; [3, 4] = 10; [5, 6] = 14 | 6.8.3 |
Appendix HNotation Quick Reference (Informative)
This section is non-normative.
Generated from the reference implementation's @randsum/roller/docs, so it lists every form the roller accepts today. Where it and the normative sections differ, the normative sections govern.
Core
| Notation | Name | Description | Forms |
|---|---|---|---|
xDN | Core Roll | Roll x dice with N sides each. The foundation of every notation string. | xDNRoll x dice, N sides each |
Examples
| Notation | Description |
|---|---|
1d20 | Roll one d20 |
4d6 | Roll four d6 |
2d8 | Roll two d8 |
Special
| Notation | Name | Description | Forms |
|---|---|---|---|
d% | Percentile Die | Shorthand for a 100-sided die. Equivalent to 1d100. | d%Roll 1-100 |
dF | Fate / Fudge Die | Fate dice show -1, 0, or +1. dF.2 is the extended Fudge variant (-2 to +2). | dFFate Core die: -1, 0, or +1dF.2Extended Fudge die: -2 to +2 |
zN | Zero-Bias Die | A zero-indexed die that rolls 0 through N-1 instead of 1 through N. | zNRoll 0 to N-1 |
gN | Geometric Die | Roll an N-sided die, and roll it again each time it shows N. Total is the sum of every roll. Takes total modifiers only (+, -, *, //, %). | gNRoll again on the maximum; sum every roll |
DDN | Draw Die | Draw dice from a pool without replacement — each value can only appear once. | xDDNDraw x unique values from 1-N |
d{...} | Custom Faces Die | A die with custom face values. Faces can be any values. | d{a,b,c,...}Comma-separated list of face values |
Examples
| Notation | Description |
|---|---|
d% | Roll 1-100 |
4dF | Fate Core: four Fate dice (-4 to +4) |
dF.2 | Extended Fudge die (-2 to +2) |
z6 | Roll 0-5 instead of 1-6 |
g6 | Geometric d6: roll again on each 6 |
3DD6 | Draw 3 unique values from 1-6 |
d{1,2,2,3,3,4} | Weighted custom die |
d{H,T} | Coin flip (heads/tails) |
Clamp
| Notation | Name | Description | Forms |
|---|---|---|---|
C{..} | Cap | Clamp individual die values to a range — dice outside the boundary are moved to it. | C{...}Comma-separate multiple conditions |
Examples
| Notation | Description |
|---|---|
4d6C{>5} | Cap rolls: nothing exceeds 5 |
4d20C{<3,>18} | Clamp rolls to [3, 18] |
Map
| Notation | Name | Description | Forms |
|---|---|---|---|
V{..} | Replace | Replace dice showing specific values with a new value. | V{...}Comma-separate multiple rules |
Examples
| Notation | Description |
|---|---|
4d6V{1=2} | Replace 1s with 2 |
4d20V{>18=20} | Cap 19s and 20s to 20 |
4d6V{1=2,6=5} | Replace multiple |
Substitute
| Notation | Name | Description | Forms |
|---|---|---|---|
R{..} | Reroll | Reroll dice that match a condition. The new result stands (may reroll again if still matching). | R{...}Reroll until result no longer matchesR{...}(d)Reroll at most d dice |
ro{..} | Reroll Once | Reroll each die matching a condition once and keep the new result, even if it matches again. | ro{...}Reroll each matching die once |
U | Unique | Force all dice in the pool to show different values by rerolling duplicates. | U({..})All unique; optional exceptions list |
Examples
| Notation | Description |
|---|---|
4d6R{1} | Reroll any 1s |
2d10R{<3} | Reroll results under 3 |
4d6R{<3}2 | Reroll under 3, at most 2 dice |
4d6ro{1} | Reroll 1s once |
2d10ro{<3} | Reroll under 3 once |
4d20U | Roll 4d20, no duplicate results |
4d6U{1} | Unique except 1s may repeat |
Generate
| Notation | Name | Description | Forms |
|---|---|---|---|
! | Explode | Each die showing its maximum value adds another die, and each new die that also explodes adds another (up to 1000 per die). | !Explode on max value!{condition}Explode on condition match |
!s{..} | Explode Sequence | On max, re-roll with the next die size in a custom sequence rather than reusing the same die. | !s{N1,N2,...}Step through die sizes on each explosion |
!i | Inflation | Explode upward through the standard dice larger than this one (4, 6, 8, 10, 12, 20, 100). Sugar for Explode Sequence going up. | !iInflate through standard dice sizes |
!r | Reduction | Explode downward through the standard dice smaller than this one (100, 20, 12, 10, 8, 6, 4). Sugar for Explode Sequence going down. | !rReduce through standard dice sizes |
Examples
| Notation | Description |
|---|---|
3d6! | Roll 3d6; any 6 adds another d6 |
4d6L! | Roll 4d6, explode, then drop lowest |
3d10!{>=8} | Roll 3d10; explode on 8 or higher |
5d10!{=10} | Roll 5d10; explode only on 10 |
1d4!s{4,6,8,10} | Explode through d4, d6, d8, d10 |
1d6!s{8,12} | Explode to d8, then d12 |
1d4!i | Explode d4 through d6, d8, d10, d12, d20, d100 |
1d20!r | Explode d20 through d12, d10, d8, d6, d4 |
Accumulate
| Notation | Name | Description | Forms |
|---|---|---|---|
!! | Compound Explode | Like explode, but extra rolls add to the triggering die rather than creating new dice. | !!(n)Compound up to n times (default: until a roll misses)!!0Unlimited depth (capped at 1000)!!{condition}Compound on condition match |
!p | Penetrating Explode | Like explode, but each subsequent explosion subtracts 1 from the result (Hackmaster-style). | !p(n)Penetrate up to n times (default: until a roll misses)!p0Unlimited depth (capped at 1000)!p{condition}Penetrate on condition match |
Examples
| Notation | Description |
|---|---|
3d6!! | Roll 3d6; 6s add to themselves |
1d8!!5 | Roll 1d8, compound up to 5 times |
5d10!!{>=8} | Roll 5d10; compound on 8 or higher |
1d6!p | Roll 1d6; max penetrates with -1 per chain |
2d6!pL | Penetrate, then drop lowest |
5d10!p{>=8} | Roll 5d10; penetrate on 8 or higher |
Dispatch
| Notation | Name | Description | Forms |
|---|---|---|---|
W | Wild Die | D6 System wild die: compound-explode on max, drop wild die and highest on 1, no effect otherwise. A macro that dispatches to multiple primitives based on runtime state. | WApply wild die rule |
Examples
| Notation | Description |
|---|---|
5d6W | D6 System with wild die |
Filter
| Notation | Name | Description | Forms |
|---|---|---|---|
L | Drop Lowest | Remove the lowest-valued dice from the pool before summing. | L(n)Drop n lowest (default: 1) |
H | Drop Highest | Remove the highest-valued dice from the pool before summing. | H(n)Drop n highest (default: 1) |
D{..} | Drop by Condition | Drop any dice matching a condition — more flexible than L/H for arbitrary thresholds. | D{...}Comma-separate multiple conditions |
K | Keep Highest | Keep only the n highest-valued dice; discard the rest. | K(n)Keep n highest (default: 1) |
KL | Keep Lowest | Keep only the n lowest-valued dice; discard the rest. | KL(n)Keep n lowest (default: 1) |
KM | Keep Middle | Keep N dice closest to the middle of the pool by dropping equal numbers from both ends. Sugar for Drop lowest + Drop highest. | KM(n)Drop n from each end (default: 1) |
Examples
| Notation | Description |
|---|---|
4d6L | Roll 4d6, drop lowest (ability scores) |
5d6L2 | Roll 5d6, drop 2 lowest |
2d20H | Roll 2d20, drop highest (disadvantage) |
4d6H | Roll 4d6, drop highest |
4d6D{1} | Drop all 1s |
4d6D{>=5} | Drop all 5s and above |
4d6D{<=2} | Drop any result of 2 or lower |
4d6D{1,6} | Drop multiple |
2d20K | Roll 2d20, keep highest (advantage) |
4d6K3 | Roll 4d6, keep highest 3 |
2d20KL | Roll 2d20, keep lowest (disadvantage) |
4d6KL2 | Roll 4d6, keep 2 lowest |
7d6KM2 | Keep the middle 3 of 7 dice |
4d6KM | Keep middle 2 |
Reinterpret
| Notation | Name | Description | Forms |
|---|---|---|---|
#{..} | Count | Count dice matching comparison conditions instead of summing values. More powerful than S{}/F{} sugar. | #{...}Comma-separate multiple conditions |
S{..} | Count Successes | Count dice that meet a threshold instead of summing values — used in dice pool systems. | S{n}Single success thresholdS{n,b}Threshold + botch threshold |
F{..} | Count Failures | Count dice at or below a threshold instead of summing values. Sugar for Count with lessThanOrEqual. | F{N}Count failures <= N |
Examples
| Notation | Description |
|---|---|
5d10#{>=7} | Count dice >= 7 |
5d10#{>3,<1} | Count >3, deduct <1 |
5d10S{7} | Count dice that rolled 7 or higher |
5d10S{7,1} | Successes ≥ 7, subtract botches ≤ 1 |
5d10F{3} | Count dice <= 3 |
Scale
| Notation | Name | Description | Forms |
|---|---|---|---|
ms{..} | Margin of Success | Subtract a target number from the total to get the margin of success or failure. Sugar for Minus N. | ms{N}Subtract N from total |
* | Multiply Dice | Multiply the dice sum before applying +/− arithmetic modifiers. | *nMultiply dice sum by n (pre-arithmetic) |
+ | Add | Add a fixed number to the total after all dice are rolled. | +nAdd n to total |
− | Subtract | Subtract a fixed number from the total after all dice are rolled. | -nSubtract n from total |
// | Integer Divide | Divide the total by a number and drop the remainder (rounds toward zero). | //nDivide total by n, drop the remainder |
% | Modulo | Take the remainder after dividing the total by a number. | %nTotal modulo n |
** | Multiply Total | Multiply the entire final total after all other modifiers have been applied. | **nMultiply final total by n |
Examples
| Notation | Description |
|---|---|
1d20ms{15} | Margin of success vs DC 15 |
2d6*2+3 | (roll × 2) + 3 |
4d6*3 | Triple the dice sum |
1d20+5 | Roll 1d20, add 5 |
2d6+3 | Roll 2d6, add 3 |
1d20-2 | Roll 1d20, subtract 2 |
4d6L-1 | Drop lowest, subtract 1 |
2d6//2 | Roll 2d6, halve (drop the remainder) |
4d6L//3 | Drop lowest, then divide by 3 |
1d20%5 | Roll 1d20, result mod 5 |
2d6%3 | Roll 2d6, remainder after dividing by 3 |
2d6+3**2 | (roll + 3) × 2 |
4d6L**3 | (drop-lowest sum) × 3 |
Order
| Notation | Name | Description | Forms |
|---|---|---|---|
sa | Sort | Sort the dice pool in ascending or descending order. Does not affect the total — only the presentation order of dice. | saSort ascendingsdSort descending |
Examples
| Notation | Description |
|---|---|
4d6sa | Roll 4d6, display sorted low to high |
4d6sd | Roll 4d6, display sorted high to low |
Authors’ Addresses
Alex Jarvis
RANDSUM
Email: alxjrvs@gmail.com
URI: https://github.com/alxjrvs
End of RANDSUM Dice Notation Specification v0.9.0