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.

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 | 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
emphasis
footnoteReference
footnote
heading
html
imageReference
image
inlineCode
linkReference
link
listItem
list
paragraph
root
strong
table
text
thematicBreak
toml
yaml
definition
footnoteDefinition

Headings

Headings can be further filtered down by the heading size by appending the size to the end of the type:

`dice: [[Note]]|heading-2`

Line Rollers

The Dice Roller can be told to return a random line from any note using the following syntax:

`dice: [[Note]]|line`

> Note: The plugin will filter out zero-length lines, but depending on note content, you may still get "blank" lines.

Tag Rollers

The Dice Roller can also be told to return results from a tag if the Dataview plugin is installed.

By default, this will return 1 result from every file that has the tag. You can change this behavior in settings, or by using the following optional + and - parameters as shown below.

If results from multiple files are returned, the result from that file can be re-rolled by clicking on the block. Clicking on the container or the dice icon will re-roll all returned results.

Tag dice support the same block-type parameters as above.

Example	Result
`dice: #tag`	Return a single random block from notes with #tag, behavior depends on settings (default to every)
`dice: #tag|-`	Return a single random block from a single, random note with #tag
`dice: #tag|+`	Return a single random block from every note with #tag

Links

If the Always Return Links for Tags setting is on, or |link is appended to the end of the tag, a link to a random note will be returned instead of sections.

At the moment this will only return a single link regardless of the number of rolls specified. This may change in a later release.

Table Rollers

The Dice Roller may also be given a link to a table in a note, which it will read and return a random result from the table.

Usage:

In a note (such as Note.md), create a table & optionally give it a block id:

Header
A
B
C

^block-id

Then, in the dice formula, use a wikilink to the block reference of the table:

`dice: [[Note^block-id]]`

The plugin will read the table and return a random result.

To return multiple elements, use a dice formula before the wikilink:

• `dice: X[[Note^block-id]]`

• `dice: 1d4+1[[Note^block-id]]`

• `dice: Xd[[Note^block-id]]`

Note that, for backward compatibility reasons, d is interpreted as a d1 and not as a d100 like in regular dice formulas.

Once in preview mode, you may Ctrl - click on the result to open the block reference in a new pane.

Multiple Headers

If a table provided to the plugin has multiple headers, the plugin will return the entire row unless you specify the header to use:

Header	Header 2
A	D
B	E
C	F

^block-id

`dice: [[Note^block-id]]|Header 2`

Lookup Tables

The dice roller can also be used as a lookup table by passing a block-id to a table with the following format:

| dice: 1d20 | Heading  |
| ---------- | -------- |
| 1-2        | Option 1 |
| 3-4        | Option 2 |
| 5-10       | Option 3 |
| 11         | Option 4 |
| 13,14      | Option 5 |
| 15-20      | Option 6 |

Requirements:

1. The table must only be two columns.
2. The first column must be a valid dice roll syntax.

The Table roller will roll the supplied dice formula, and return the matching result.

The options can also be a roller (of any type). This allows you to nest rollers: for example, you could supply a reference to different treasure tables, and when the treasure table is returned, the roller will get a random result from that table.

Example:

| dice:1d% | Result                                 |
| -------- | -------------------------------------- |
| 01–50    | Nothing                                |
| 51–60    | `dice: [[Encounters^easy-encounters]]` |
| 61–100   | `dice: [[Encounters^hard-encounters]]` |

^encounter

`dice: [[ThisNote^encounter]]`

2d Table Rollers

Adding |xy to the end of a table roller will return a random table cell (not row) from the table, unless there is a column named xy.

List Rollers

The Dice Roller may also be given a link to a list in a note, which it will read and return a random result from the list.

Usage:

In a note (such as Note.md), create a list & optionally give it a block id:

-   a
-   b
-   c
-   d

^block-id

Then, in the dice formula, use a wikilink to the block reference of the table:

`dice: [[Note^block-id]]`

The plugin will read the list and return a random result.

To return multiple elements, use:

`dice: Xd[[Note^block-id]]`

Once in preview mode, you may Ctrl - click on the result to open the block reference in a new pane.

Tooltip

The result in preview mode has a tooltip that will appear when you hover over it.

It displays the formula used to calculate the result on the top line, and displays the calculated rolls on the bottom line.

Saving Results

Results can be saved for dice rolls as of version 6.1.0 using either the Globally Save Results setting or the following syntax:

Syntax	Description
dice+: ...	Save result. Same as dice: ... if Globally Save Results is on.
dice-: ...	Do not save result. Same as dice: ... if Globally Save Results is off.

Replacing Note Content

It is possible to tell the plugin to replace the file contents of the note with the calculated dice roll using the dice-mod: syntax.

The plugin will replace the contents of the note with the syntax:

-> ->

Example:

dice-mod: 3d100 + 12 => 3d100 + 12 -> [75, 20, 75] + 12 -> 182

Displaying Formula

By default, the plugin will display the formula along with the result.

This can be turned off globally by turning off Add Formula When Modifying in settings, or by appending |noform to a dice-mod roll.

Replacing Blocks

If dice-mod is used on a section roller, the plugin will attempt to find a block id for the resulting section, so it can be embedded.

If a block id does not exist for that section, the plugin will attempt to create one for the section. This will modify the file being rolled.

Dice Flags

There are flags that can be appended to the dice formulas shown below that will modify how the dice behave.

|nodice

Don't want to see the dice button on results?

You can turn it off in settings, or by appending |nodice to any dice roll!

|form and |noform

These two flags can be used to control whether or not the dice formula is displayed with a dice-mod roll.

|render and |norender

Want to roll graphical dice from your notes?

Use the |render flag at the end of a dice roller formula, and the plugin will roll 3D dice to calculate the result.

See Graphical Dice for more information.

|form and |noform

These two flags can be used to control whether or not the dice formula is displayed with rolls.

They can be used for dice-mod and dice roller.

This can be turned on or off globally in settings, using Display Formula With Results for dice roller and Add Formula when Using Modify Dice for dice-mod.

|avg

Want the initial dice value to be the average instead of rolling it?

Use the |avg flag at the end of a dice roller formula, and the plugin will initialize the result using the average value of dice rolls. The tooltip will indicate that the result is an average and show the averages.

Example: dice: 2d6+3|avg gives 10as the result and displays average: [3.5,3.5]+3 in the tooltip.

Next rolls will not use the average anymore but normal random dice roll results. On the other hand, using Alt-click to reroll forces average to be (re)used.

|none

Want no value being displayed before clicking on the reroll icon?

Use the |none flag at the end of a dice roller formula, and the plugin will initialize the result with an empty value. The tooltip will indicate that the result is none.

Next rolls will display the normal result using random dice roll results. On the other hand, using Ctrl-click to reroll forces none to be (re)used.

|text(my text)

Want to roll dice without displaying the result in your note?

Use the |text(my text) flag at the end of a dice roller formula, and the plugin will display your 'my text' and let you click on it to trigger a roll.

The roll result is only visible in the tooltip.

Example for a DnD saving throw, use: dice: 1d20 + 2|nodice|text(Dexterity +2) When hovering on top of Dexterity +2, you'll see a random saving throw result (click to reroll as usual).

The Dice View

The plugin comes with a Dice View that can be added to the workspace.

If you have the Open Dice View on Startup setting off or have closed the Dice View, it can be re-opened using the "Open Dice View" command in the command palette.

The Dice View has buttons for common D20 dice set, can be set to roll with advantage or disadvantage, and modifiers can be added.

Formulas can also just be written directly in the Dice Formula textbox. These formulas can be saved using the plus button under the text box for quick re-rolling.

Graphical Dice

3D Dice can be rolled using the Dice View if Display Graphics for Dice View Rolls is turned on in settings, the or the |render flag is used in the dice formula.

> 📝 Only the basic D20 set (D4, D6, D8, D10, D12, and D20) can be rolled graphically.

See Graphical Dice for settings.

Usage in Other plugins

Plugins that have the ability to write JavaScript (such as DataView) can interface with the Dice Roller plugin in by accessing it on the Obsidian app object:

const diceRollerPlugin = app.plugins.getPlugin("obsidian-dice-roller");

Once you have an instance of the plugin, you can then generate the various types of rollers, such as a dice roller, tag roller, etc, using the getRoller method:

//definition
getRoller(diceString: string, sourceFile: string = ""): Promise;

//example
const diceRoller = await diceRollerPlugin.getRoller("1d3+3d8");

Array Roller

A special type of roller is available using the JavaScript interface, where you can directly pass in an array you want a result from.

//definition
getArrayRoller(options: any[], rolls: number = 1): Promise;

ArrayRoller {
    /** Roll the array roller and generate a new set of results. */
    roll(): Promise

    /** Property containing the container element of the array roller. Use this to attach it to the note's DOM */
    containerEl: HTMLElement;

    /** Property containing the array of randomly-generated results. This will change every time the array roller is rolled. */
    results: any[]
}

//example
const diceRoller = await diceRollerPlugin.getArrayRoller([1, 2, 3, 4, 5], 2);

Settings

Generic Settings

Globally Save Results

The plugin will attempt to save and reload the results for all dice rollers. Overridable using a - in the dice formula, like this: `dice-: ...`.

Please note that the plugin will attempt to save. Saving results of inline code blocks is tricky and difficult - the plugin has to remember where in the note each dice roll was in order to properly save and reload the result. Any changes made to the note outside of Obsidian will cause the plugin to lose this state and the next time the note is re-opened, it will be rerolled.

If you have to have a permanent result, it is more reliable to use a dice-mod roll instead, which will actually modify the underlying note, making the result permanent. See Replacing Note Content for more information.

Dice Display

Settings to control how dice results are displayed.

Display Formula with Results

The formula used to calculate the result will be displayed along with the result.

Display Dice Button with Results

A dice button will appear next to the results, making it obvious this is a dice roller.

Add Formula when Using Modify Dice

A dice-mod roll will append the formula used to calculate the result when writing the result to the note.

Dice Rollers

Settings to control how Dice Rollers behave.

Default Face

The plugin will use this number as the default face if it is omitted - see Faces for more information.

Round Results

Determine the rounding behavior when decimal numbers are returned.

Always Render Dice

Dice rolls in notes will always be rendered. Use the |norender flag to prevent this behavior.

Table Rollers

Settings to control how Table Rollers behave.

Display Lookup Table Roll

Lookup table rolls will also display the number rolled along with the result from the table.

Section Rollers

Settings to control how Section Rollers behave.

Add Copy Button to Section Results

Section roller results will have a "Copy Content" button added, allowing you to copy the note contents for that section to your clipboard.

Tag Rollers

Settings to control how Tag Rollers behave.

Roll All Files for Tags

A result from each file with the specified tag will be returned. If this setting is off, a result from a random file with the tag will be returned. Overrideable with `dice: #tag|-`

Always Return Links for Tags

Tag rollers will behave like Link Rollers by default. This option is the same as specifying `dice: #tag|link`.

Dice View

Open Dice View on Startup

The Dice View will automatically open on startup. Otherwise it may be opened with the command "Open Dice View".

Graphical Dice

Settings to control how graphical dice behave.

Display Graphics for Dice View Rolls

Rolls made in the Dice View will use graphics.

Display Time for Dice Graphics

Controls how long dice graphics are displayed before fading away. This should be a number of milliseconds. If blank, a click is required to clear dice.

Dice Base Color

This is the color of the actual dice bodies.

Dice Text Color

This is the color of the numbers on the dice.

Dice Formulas

Dice formulas can be created in settings. Formulas must be given an alias; when the plugin detects the formula alias, it will use the defined formula for the roll. This works for all roller types.

Installation

From within Obsidian

From Obsidian v0.9.8, you can activate this plugin within Obsidian by doing the following:

• Open Settings > Third-party plugin
• Make sure Safe mode is off
• Click Browse community plugins
• Search for this plugin
• Click Install
• Once installed, close the community plugins window and activate the newly installed plugin

From GitHub

• Download the Latest Release from the Releases section of the GitHub Repository
• Extract the plugin folder from the zip to your vault's plugins folder: /.obsidian/plugins/ Note: On some machines the .obsidian folder may be hidden. On MacOS you should be able to press Command+Shift+Dot to show the folder in Finder.
• Reload Obsidian
• If prompted about Safe Mode, you can disable safe mode and enable the plugin. Otherwise head to Settings, third-party plugins, make sure safe mode is off and enable the plugin from there.

Updates

You can follow the same procedure to update the plugin

Warning

This plugin comes with no guarantee of stability and bugs may delete data. Please ensure you have automated backups.

TTRPG plugins

If you're using Obsidian to run/plan a TTRPG, you may find my other plugin useful:

• Obsidian Leaflet - Add interactive maps to Obsidian.md notes
• 5e Statblocks - Create 5e-styled statblocks inside notes
• Initiative Tracker - Track TTRPG Initiative in Obsidian