Disambiguating Operators
Modifiers vs. Expressions
A crucial aspect of the syntax is distinguishing between operators that are part of a dice modifier (acting on individual dice or the rolling process itself) and operators that initiate standard mathematical or comparison expressions (acting on the numeric result of the preceding component).
The Core Rule: Spaces or Parentheses Matter
The parser uses spaces and parentheses to resolve ambiguity:
No Space: An operator immediately following a roll or modifier component is typically treated as part of that modifier if the syntax allows (e.g., `k`, `!`, `r`, `cs`, `>`, `<`, `=`, etc.).
Space(s): An operator separated by one or more spaces from the preceding component is treated as initiating a standard mathematical or comparison expression that operates on the result of the preceding component.
Parentheses: Placing parentheses around a roll expression, like `(2d6)`, forces the subsequent operator to be treated as a mathematical or comparison operator acting on the group's result, even without spaces (though spaces are still recommended for readability).
Examples of Ambiguity and Resolution
This distinction is most critical for operators like `>`, `<`, and `=` which can function as both success/target conditions within modifiers AND as standard comparison operators:
Success Modifier: `5d10>7`
Meaning: Roll 5d10, count dice showing 7 or higher. `>` is part of the success modifier.
Example: Roll `[8, 3, 10, 7, 4]` -> `3` successes.
Comparison Expression: `5d10 > 7` or `(5d10)>7`
Meaning: Roll 5d10, sum the results, then check if the total is greater than 7. Returns `1` (true) or `0` (false).
Example: Roll `[4, 2, 1, 5, 3]` -> Total `15`. `15 > 7` is true. -> Result `1`.
The same principle applies when these operators follow other modifiers:
Explode Target: `3d6!>5`
Meaning: Roll 3d6, explode dice showing 5 or 6. `>5` sets the explode target.
Example: Roll `[5, 2, 6]` -> Explode 5 (roll 3), Explode 6 (roll 1) -> Pool `[5, 2, 6, 3, 1]`, Total `17`.
Explode + Comparison: `3d6! > 5` or `(3d6!) > 5`
Meaning: Roll 3d6, explode only dice showing 6 (default `!` target), sum the result, then check if the total is greater than 5.
Example: Roll `[5, 2, 6]` -> Explode 6 (roll 1) -> Pool `[5, 2, 6, 1]`, Total `14`. `14 > 5` is true. -> Result `1`.
Reroll Target: `4d6r=1`
Meaning: Roll 4d6, reroll any dice showing exactly 1. `=1` sets the reroll target.
Example: Roll `[1, 4, 1, 6]` -> Reroll 1 (gets 3), Reroll 1 (gets 5) -> Pool `[3, 4, 5, 6]`, Total `18`.
Reroll + Comparison: `4d6r = 1` or `(4d6r) = 1`
Meaning: Roll 4d6, reroll any dice showing exactly 1 (default `r` target), sum the result, then check if the total equals 1.
Example: Roll `[1, 4, 1, 6]` -> Pool `[3, 4, 5, 6]`, Total `18`. `18 = 1` is false. -> Result `0`.
Standard Math Operators (`+`, `-`, `*`, `/`, etc.)
For operators like `+`, `-`, `*`, `/`, the presence or absence of spaces is crucial for meaning, especially when they follow modifiers that can take numeric arguments.
Modifier Argument: `3d6k+1`
Meaning: Keep highest `+1` dice. The `+1` is interpreted as a signed integer argument for the `k` modifier because it immediately follows `k` without a space.
Example: Roll `[5, 2, 6]` -> Keep highest 1 -> Result `6`.
Mathematical Operation: `3d6k + 1`
Meaning: Keep highest 1 (default for `k`), then add 1 to the result. The space separates the `k` modifier (which takes its default argument) from the `+` mathematical operator.
Example: Roll `[5, 2, 6]` -> Keep highest 1 -> `6`. Then `6 + 1` -> Result `7`.
Similarly
Modifier Argument: `3d6k-1`
Meaning: Keep highest `-1` dice. The `-1` is the argument for `k`. The implementation ensures at least 0 dice are kept, so this results in keeping 0 dice.
Example: Roll `[5, 2, 6]` -> Keep highest -1 -> All dice dropped -> Result `0`.
This is a good example of potentially unexpected behavior: because "keep -1 dice" is semantically nonsensical, one might intuitively assume the `-` must be a mathematical operation. However, the parser strictly follows the grammar, interpreting the signed number `-1` as the modifier's argument due to the lack of space.
Mathematical Operation: `3d6k - 1`
Meaning: Keep highest 1, then subtract 1 from the result.
Example: Roll `[5, 2, 6]` -> Keep highest 1 -> `6`. Then `6 - 1` -> Result `5`.
While `1d6+1` vs `1d6 + 1` might parse identically (as the `+` cannot be part of the `d6` roll itself), ambiguity arises with modifiers like `k` or `d`.
Therefore, always using spaces around mathematical and comparison operators is strongly recommended to make the formula's intent clear and prevent misinterpretation.
Conclusion: Use spaces or parentheses deliberately to separate mathematical/comparison expressions from dice rolls and modifiers. When an operator should be part of a modifier (like setting a target), do not use spaces.