Dice Roller

Warning: We are beginning a Readme transition to Javalent's Plugins Documentation in all Javalent repositories. Please bookmark this link and check it first before referring to this readme.

Inline dice rolling for Obsidian.md.

Usage

Simply place a code block with your formula in your note (such as `dice: XdX`) and in preview mode it will be replaced with the result of the dice rolls. The result can then be re-rolled by clicking on it.

Formulas

Dice formulas can be added in settings, allowing you to define aliases for commonly used rolls. This works for all dice types define below.

Dice Rollers

The parser supports addition, subtraction, multiplication, division, and exponents of an arbitrary number of dice or static numbers. Spaces are removed before the formula is parsed.

There is full order-of-operations support, so it can even nested into parentheses!

Examples
`dice: 1d2`
`dice: 3d4 + 3`
`dice: 1d12 + 1d10 + 5`
`dice: 3d4+3d4-(3d4 * 1d4) - 2^1d7`

Dataview Integration

The plugin has basic support for Dataview inline fields in number dice.

Please note that if you have multiple inline fields of the same name, the plugin will only use one, and it is not possible to control the one it uses - it will be the last field indexed by Dataview.

Example:

field:: 3
field2:: 5

`dice: field` `dice: 1d6 + field` `dice: 1d6*field2 + field`

Faces

The faces can be supplied as either a raw number or as a [min, max] array.

Example: `dice: 1d[3,5]` will roll 1 die between 3 and 5.

Omitting Values

Both the number of rolls and the faces can be omitted.

Roll will default to 1.

Faces will default to 100.

These defaults can be changed in settings.

Percentile Dice

The parser supports percentile dice. `dice: Xd%` will roll X d100 dice.

For a custom percent (such as those used for Traveller's 1d66), you can use XdX% - see the percent modifier.

Fudge/Fate Dice

Use `dice: XdF` to roll a fudge/fate dice. See here for more info on this type of dice.

Fantasy AGE Stunt Dice

Use `dice: 1dS` to roll a Fantasy AGE stunt dice. The result will show the total roll and also the stunt points if successful.

Genesys/SWRPG Narrative Dice

Use `dice: GgPpYyRrBbSsWw` to roll Narrative dice. The result will show the total roll in net symbols (Success, Advantage etc.). Total individual results displayed in the tooltip, and results display can be toggled between words and symbols in the settings.

Dice	Syntax Options
Ability	Gg Aa
Proficiency	Yy Pp pro
Difficulty	Pp Dd diff
Challenge	Rr Cc
Boost	Bb boo
Setback	Ss sb blk
Force	Ww Ff

Specifying quantities of dice with a digit will also work. E.g. `dice: 3g4d`

Note: If any abbreviation exclusive letters are used (A,C,D), P will preference Proficiency.

Dice Modifiers

The parser supports several modifiers. If a die has been modified, it will display how it has been modified in the tooltip.

Modifiers are only supported on basic number dice.

If a modifier has a parameter, it will default to 1 if not provided.

Modifier	Syntax	Description
Min/Max	Xd[Y, Z]	Roll a dice with minimum Y, maximum Z.
Keep Highest	k{n}/kh{n}	Keep highest {n} dice.
Keep Lowest	kl{n}	Keep lowest {n} dice.
Drop Lowest	dl{n}	Drop lowest {n} dice.
Drop Highest	dh{n}	Drop highest {n} dice.
Explode	!{n}, !i	Explode dice {n} times. If i is provided, will explode "infinitely" (capped at 100).
Explode & Combine	!!{n}, !!i	Same as explode, but exploded dice are summed in the display instead of being shown individually.
Re-roll	r{n}, ri	Re-roll a minimum dice {n} times. If i is provided, will re-roll "infinitely" (capped at 100).
Sort	s(a), sd	Sort results ascending or descending.
Make Unique	u	Dice will be rerolled until all results are unique.

Min/Max

Syntax: Xd[Y, Z]

Create a custom die, with a minimum of Y and a maximum of Z.

Example

Formula	Result
dice: 4d[7, 8]	[7, 7, 8, 7]
dice: 1d[20, 20]	[20]

Keep Highest

Syntax: XdXk{n} / XdXkh{n}

Keeps highest {n} rolls. {n} is optional, and will default to 1. Dropped dice will display as Nd.

Example

Formula	Result
dice: 2d20k / dice: 2d20kh	[7d, 18] = 18
dice: 4d20k2 / dice: 4d20kh2	[4d, 12, 15, 3d = 27

Keep Lowest

Syntax: XdXkl{n}

Keeps lowest {n} rolls. {n} is optional, and will default to 1. Dropped dice will display as Nd.

Example

Formula	Result
dice: 2d20kl	[7, 18d] = 7
dice: 4d20kl2	[4, 12d, 15d, 3] = 7

Drop Lowest

Syntax: XdXdl{n}

Drops lowest {n} rolls. {n} is optional, and will default to 1. Dropped dice will display as Nd.

Example

Formula	Result
dice: 2d20dl	[7d, 18] = 18
dice: 4d20dl2	[4d, 12, 15, 3d = 27

Drop Highest

Syntax: XdXdh{n}

Keeps lowest {n} rolls. {n} is optional, and will default to 1. Dropped dice will display as Nd.

Example

Formula	Result
dice: 2d20dh	[7, 18d] = 7
dice: 4d20dh2	[4, 12d, 15d, 3 = 7

Explode

Syntax: XdX!{n|i}

Explode will roll an additional die for each maximum die roll. If {n} or {i} is provided, it will continue exploding until a number less than the maximum is rolled, or {n} attempts have been made. {i} is capped at 100 rolls to prevent abuse.

Exploded dice will display as N!.

Examples

Formula	Result
dice: 2d20!	[7, 20!, 8] = 35
dice: 2d4!3	[3, 4!, 4!, 2] = 13
dice: 1d1!i	[1!, 1!, 1!, ... , 1!, 1!, 1] = 100

Explode & Combine

Syntax: XdX!!{n|i}

Equivalent to explode, but exploded dice are combined in the tooltip display.

Examples

Formula	Result
dice: 2d20!!	[7, 28!] = 34
dice: 2d4!!3	[3, 10!] = 13
dice: 1d1!!i	[100!] = 100

Re-roll

Syntax: XdXr{n|i}

Re-roll a minimum dice. If {n} or {i} is provided, it will continue re-rolling until a number greater than the minimum is rolled, or {n} attempts have been made.

Re-rolled dice replace their original roll, unlike explode, which add new rolls.

Re-rolled dice will display as Xr in the tooltip.

Examples

Formula	Result
dice: 2d20r	[7r, 18] = 15
dice: 2d4r3	[3, 3r] = 6
dice: 1d2ri	[2r] = 2

Custom Percent Dice

Syntax: XdX%

Customize the type of percent dice rolled. It will roll a dice for each face digit provided and combine them into a result.

Examples

Formula	Result
dice: 1d66%	[6, 3] = 6,3
dice: 1d7367%	[4, 2, 4, 1] = 4,2,4,1

Conditions

Dice Conditions

Dice rolls support conditional parameters as of version 6.0.0. This allows you to specify a set of requirements, one of which the dice must meet to be included in the roll. If the dice meets this requirement, it will be considered a 1 (pass), and if it does not, it will be considered a 0 (failure).

Additionally, a negative equals condition may be supplied; if the dice meet this requirement, it will be considered a -1.

The following conditions are supported:

Condition	Effect
={n}	Only rolls that are equal to {n} are successful.
=!{n}*	Only rolls that are not equal to {n} are successful.
>{n}	Only rolls that are greater than {n} are successful.
<{n}	Only rolls that are less than {n} are successful.
>={n}	Only rolls that are greater than or equal to {n} are successful.
<={n}	Only rolls that are less than or equal to {n} are successful.
-={n} or =-{n}	Rolls equal to {n} will be considered -1.

*Note that !={n} is supported as a dice condition due to a collision with Explode. If necessary, use =!{n}.

Modifier Conditions

The Explode, Explode and Combine and Re-roll modifiers each support an optional condition operator. If provided, the condition operator changes the die rolls that the modifier is applied to.

Supported Conditions:

Condition	Effect
={n}	Only rolls that are equal to {n} are modified.
=!{n}	Only rolls that are not equal to {n} are modified.
>{n}	Only rolls that are greater than {n} are modified.
<{n}	Only rolls that are less than {n} are modified.
>={n}	Only rolls that are greater than or equal to {n} are modified.
<={n}	Only rolls that are less than or equal to {n} are modified.

These conditions are fully chainable.

Examples

Formula	Description	Result
dice: 1d4!=3	Explode rolls equal to 3	[4, 2, 3!, 2] = 11
dice: 1d4!i=!3	Explode rolls not equal to 3 infinitely	[4!, 2!, 3, 2!, 3, 2!, 1!, 4!, 3] = 24
dice: 1d4r<3	Re-roll rolls less than 3	[4, 1, 2, 4] -> [4, 4r, 3r, 4] = 15
dice: 1d4r<2>3	Re-roll rolls less than 2, greater than 3	[4, 1, 2, 4] -> [3r, 2r, 2, 2r] = 9

Section Rollers

The Dice Roller can be given a link to a note or a tag, and it will return a random block from the note/notes.

This feature is still under development and may not work as expected.

Ctrl / Command - clicking a result will open the associated note.

Usage: | Example | Result | | --- | --- | | `dice: [[Note]]` | Returns a single random block from Note | | `dice: 3d[[Note]]` | Returns 3 random blocks from Note |

Block Types

Obsidian has several "types" of blocks. Currently, the default behavior of the plugin is to filter out thematicBreak and yaml from the returned results.

To return a specific block type, you may append |<type> to the end of any block roller. These can be chained by separating them with a comma.

Usage:

Example	Result
`dice: [[Note]]\|paragraph`	Return paragraph blocks
`dice: #tag\|paragraph,heading,yaml`	Return paragraph, heading, and yaml blocks
`dice: #tag\|-\|paragraph,heading-3,yaml`	Return paragraph, level 3 headings, and yaml blocks from a single, random note

I do not have any control over what Obsidian consider's each block (for instance, images may be returned as paragraph).

I believe that this is a list of block types defined in Obsidian, but use this with a grain of salt.

Type
blockquote
break
callout
code
delete
`emphas