RPG Dice Roller Integration

This plugin allows you to create dice macros in any entry, and potentially transclude them into other pages (or even sidebars!). Dice rolling logic is handled by the RPG Dice Roller library – please follow the link for instructions and examples of syntax and available features.

Overview

• Creates an input field where you can specify a detailed dice roll macro. The dice notation can be entered and changed on the fly, or preset and optionally locked. Press Enter or click the Roll button to see the result.
• A short animation plays before showing your result. This avoids confusion when you roll the same result consecutively and ask yourself whether you correctly clicked the button =)
• Only your total is displayed, but you can hover it to open a tooltip that details each die rolled and which ones were kept, dropped, exploded, etc. based on the parameters of your macro.
  

Creating macros

1. Create an entry in any category to hold a single macro and give it a recognizable name (e.g. "d20 with advantage" or "Cate’s Cone of Cold Damage"). You may want to create a custom category to keep things tidy if you plan to make several.
2. Apply this character sheet to the entry and fill in the properties:
   • Macro Name: Optional field. Will be displayed as a title above the dice roller if specified.
     
   • Dice Notation: Optional field. Will pre-fill the dice roller notation field if provided. Otherwise the field will be blank, which works well for an all-purpose instance of the dice roller.
   • Disable Input: If ticked, this checkbox will prevent editing the notation field, effectively allowing only your specified macro to be rolled in this dice roller instance. Note that this option is ignored if Dice Notation is empty.
     
3. Your macro is now ready to be used in the entry’s Properties page (or you can create an article set to show properties to have it available on the overview). See further instructions below for ways to transclude it into other entries.

Transcluding a macro into other entries

Transcluding a macro is very easy. Simply create a mention to the macro’s entry using advanced mention syntax (which you can enable in your profile settings under Appearance), then add the field:attributes property like so: [note:12345|field:attributes]. Instead of linking to the entry, the actual dice roller will be rendered in an iframe.

I recommend adding the following CSS rule to your campaign styles to keep the dice roller iframe only as big as needed. This will apply to any entry tagged "Dice Macro" and transcluded with the field:attributes syntax. Unfortunately, I cannot include this with the plugin out of the box since its CSS is only loaded inside the iframe, and therefore cannot affect the iframe’s outer dimensions.

/* Dice Macro transclusion iframe */
.entity-attributes-render[data-entity-tags~="dicemacro"] {
  height: 120px;
  max-width: 300px;
}

If you use different kinds of macros and tag them accordingly, you can even create different rules to have custom dimensions based on other tags as well.

Transcluding a macro into a Pins sidebar

Transclusion also works in property values, so you can pin a dice roller to any entry’s sidebar using the same method! Simply create a standard property, put in the mention with the same syntax as above and click the pin icon to pin the property. To account for the much smaller area, you may want to use macros specifically made for this purpose, without a title (the property’s name can fulfill that role) and with Disable Input checked to keep only the button and result visible.

Customizing the dice roller

The dice roller’s main container includes the data-entity-tags attribute, allowing you to style various rollers based on their entry’s tags. For example, you could have "Attack Macro" and "Damage Macro" tags on various macros and style rollers differently for each category. These tags are given in slug form, as in other parts of Kanka. For example, to give a much bigger title to those Attack Macros:

.rpg-dice-roller[data-entity-tags~="attackmacro"] h4 { font-size: 20px }

RPG Dice Roller is shared under the MIT license.

Want to show appreciation for my plugins or request one-on-one CSS help? I accept tips on Ko-fi (no account needed):