Complete Guide to Macros & Rolls
From Roll20 Wiki
Guide is a WIP Andreas J. (talk) 14:29, 21 September 2020 (UTC) |
This is mean to serve as a comprehensive guide & starting point for figuring out how the q Text Chat, Dice Rolling, Macros and related things work and interact with each-other, and to list everything you can write/make appear in the q Text Chat.
This is both for Players/Gamemasters who are just writing their own custom rolls or macros to be used in their game, as well as those who build Character Sheets and are creating/editing Roll Buttons for their sheets.
Contents |
Basics
The q Text Chat page shows the basic commands that can be used in the chat, such as /roll
(or /r
) for making simple rolls, /em
for emoting text, /w
for whispering to someone, and /gmroll
(or /gr
) for sending simple rolls to the GM.
You can write in the q Text Chat normal text without using any commands like /r
.
Text Formatting
You can use common Markdown to format you text, and to create hyperlinks.
See also:
- How to use HTML Styles in chat - Oosh
- Using Images as Links - Oosh
- Hypertext Macro to Open a Linked Character Sheet Hypertext Macro to Open a Linked Character Sheet - Vince
Chat Commands
Beyond using the various Roll Commands shown on the q Text Chat-page, here are some other examples of what you can write in the q Text Chat:
- Macros - Start with
#
, and start typing the macro name, and a list of your macros will be displayed.- Example: writing
#testmacro
in the chat will roll the macro with that name
- Example: writing
- Roll Templates -
&{template:name-of-roll-template} {{sectionname(optional)=content of roll template}}
.- The Default Roll Template is available in any games, other templates are tied to specific Character Sheet Templates. (E.g. you can only access the specific
&{template:simple}
when you have D&D 5E by Roll20-sheet in the game). - Example:
&{template:default} {{name=Test Attack}} {{attack=[[1d20]]}} {{damage=[[2d6]]}}
- This will generate a roll template using the default template, displaying "Test Attack" in the purple title, then on a new row the result of
1d20
roll, and on the third row the2d6
roll
- The Default Roll Template is available in any games, other templates are tied to specific Character Sheet Templates. (E.g. you can only access the specific
- Character Abilities/Character Sheet Button -
%{character name|ability or roll button name}
- Example 1; writing
%{Sam Bobbins|initiative}
in the chat, will work if there exists a Character with that name, who have a Character Ability/Character Sheet Roll Button by that name - Example 2: selecting a [Token]] on the map, and then writing
%{selected|initiative}
in the chat, will work if the token is linked to a character sheet that has an Ability or Roll button with that name.
- Example 1; writing
- API commands(available in games hosted by a pro user), - Start with
!
to call the API command, and then write and parameters it can take- Example: writing
!MassInit
in the chat will trigger an API that usesMassInit
as a keyword.
- Example: writing
Dice Syntax
The Dice Reference page shows how the syntax for the Roll20 dice rolling works, and all the advanced alternatives you can use, such as rolling Fate Dice, or counting successes rather than the sum of the rolls. It also details when the green "Critical Success" and red "Critical Failure" highlights are shown.
Tricks:
- Fake Crits Using Math Instead of Dice - Noon
- Keep Crits/Fumbles from Display on Attack Rolls - Scott C.
Macros
The main Macros page lists all the the other kind of options for modifying rolls that isn't covered by the Dice Reference-page. Also check the Stupid Roll20 Tricks (and some clever ones)-thread for Advanced and clever tricks that might not be linked on this page yet.
Features include:
- Using target and selected with tokens
- Suppress error message: Example
/roll 1d20 + @{selected|nonexistent_attribute} &{noerror}
- Reusing Rolls
Roll Queries
Sometimes you may have a roll (or a macro) which you want to change every time it is rolled. For example, you may want to roll a variable number of dice, or add a different modifier onto the roll each time you perform the action. Roll Queries allow you to prompt whoever is performing the roll to fill in a value when the roll is made. The syntax for a roll query is:
?{Prompt Message} //Example: /roll ?{Number of Dice}d20 //You can also include a default value: /roll ?{Number of Dice|1}d20 // 1 would be the default
Drop-down Queries
You can specify a list of options which can be presented to the player, rather than only a free-form text field.
Syntax:
?{Name of Query|Option1|Option2|Option3|Option4|Option5}
You can also specify a different value for the result other than label like so:
?{Name of Query|Label 1, value1|Label 2, value2}
- Query Ordering Without Affecting Functionality how to borrow API command syntax(works for free users) - Ziechael
Nesting
To some degree, you can nest abilities, macros and queries.
If you start nesting queries too much, you need to star using HTML replacement keep the macros working. Once saved, these macros shouldn't be opened(if saved in the l Collections-tab's Macro section, as opening a macro that have HTML replacement will result in those being converted into regular things, breaking your macro.
- Drop down Nester google sheet that generates the HTML replacement code needed. Scott C.
Initiative
To send a roll result directly to the Turn Tracker, first, select the Token you wish to roll initiative for, and then make a roll that includes the
&{tracker}
option.
Examples:
-
/roll 1d20 + 5 &{tracker}
-
&{template:default} {{name=Initiative}} {{Roll=[[1d20+5]]}} &{tracker}
See also: Cards#Using_Cards_for_Initiative_Order
Tricks using the Turn Tracker:
- Storing and Reading Values for Macros using the Turn Tracker - Pat
- Using Values Stored in Initiative Tracker as Pointers - Michael L
- "Concatenate" tracker values to build complex dynamic Abilities - Barakka
Chat Buttons
There are two types of buttons you can create in the Text Chat to be included in a macro/dicerolling result.
Ability Command Buttons can be used to call Abilities (or sheet button rolls) from a clickable button in the Text Chat. They are very closely related to API Command Buttons.
Their syntax is as follows:
[Label](~<keyword>|<ability name>)
As with Attribute and Ability calls, the keyword is your choice of selected
, target
or a character_name. You can also use a character_id as a keyword.
If you have an Ability Command Button saved somewhere within one of the tabs of the Character Window, you can choose to omit a keyword:
[Label](~<ability name>)
API buttons
API buttons do not actually use the API—anyone can make and use them. The Chat Menus trick by Keith, uses utilizes them to great length.
Roll Table
If you have Roll Tables on your l Collections-tab, they can be used in rolls & macros.
Example1:
Let's assume there exist a roll table with the name fumble
.
You can roll a table directly in the chat input, or in a macro, simply as 1t[fumble]
.
Example 2:
To roll your "crit-failure" table two time, you would enter /roll 2t[crit-failure]
. You can change 2
to whatever number you would like. However, this currently does not work with inline rolls.
You can also roll a table inline in chat or a macro by wrapping it in double square brackets like this [[1t[table-name]]]
. Currently, any number beyond 1 does not display for the inline roll, the results are show on mouseover though.
- Nestable Rollable Tables (Free User Version) - Blue64
- Using Rollable Tables and Custom Handouts for Character Cards Using Rollable Tables and Custom Handouts for Character Cards - Drew
- Inline Rolls in Rollable Tables - Eric B (plus followup posts)
- Conditional Text - Mike deBoston
- Rollable Encounter Images - Blue64
Roll Templates
Main Page: Roll Templates
- default roll template
- sheet-specific
Use Images in the Default Template - trick
If you want to dress up your default template, you can stuff an image in the name portion instead of just text:
&{template:default}{{name=[x](YOUR_IMAGE_URL#.png)}}{{test=foo}}
Images
Various ways to use or show images in macros.
- Monster Images in Chat - Kirsty
- Using Images as Links - Oosh
Advanced
The Stupid Roll20 Tricks (and some clever ones) contains a large amount of tricks and examples of clever uses for macros etc. that is a must to check out.
Here under are mentioned a limited number of the list's tricks(more could be listed or copied entirely to the wiki):
- Reusing Rolls - clever trick to reuse rolls withing the same command. Was discovered in mid-2020.
- Chat Menus - how to create chat menu for your macros, by Keith
- Macro Character Sheet - keithcurtis — More info - gui8312 — Giving Players Limited Access - Kyle.G
- DM whispers without breaks
- Dynamic Multitarget Roll without API - Barakka
- Hypertext Macro to Open a Linked Character Sheet Hypertext Macro to Open a Linked Character Sheet - Vince
- Use a Macro to Report on Obscure Character Abilities and Rules - macro template for calculating/showing derivative stats that aren't listed on the sheet but can be known, such as how long a character can hold breath. by PapaWhiskey11
Token Actions
Token Actions are specially-designated macros and character abilities (with tokens representing a character) which appear whenever a token is selected on the screen. They appear in a bar along the top of your screen, and the contents of the bar are context-sensitive. When you select a token, all macro token actions will be shown, as well as ability token actions for the token's linked character (if applicable).
API
This is about a Roll20 feature exclusive to Pro-subscribers (and often to players in a Game created by a Pro-subscriber). If you'd like to use this feature, consider upgrading your account. |
API commands start with !
and then the name of the API command, and then write any other parameters for the API. The specific API script need to be installed in the game for this to work.
Example 1:
writing !wd [[4d6+2]]
in the chat will trigger the Script:Wild Dice script to make a custom roll output, rolling 3 normal d6 dice, and one Wild Die, presenting it in a table. If the Wild Die comes up as a "1", it, and the value of the highest dice is removed form the roll total. This is not something that can be done with macros alone, which is why this API was created.
Example 2:
writing !group-init
in the chat will trigger the GroupInitiative(must be installed) API that uses group-init
as a keyword. This particular API command would roll initiative order for all selected tokens, if the API is configured to know what stats to roll.
Example 3:
writing &{template:default} {{name=Cthulhu}} !modattr --silent --charid @{target|character\_id} --sanity|-{{Sanity damage=[[2d10+2]]}} --corruption|{{Corruption=Corruption increases by [[1]]}}!!! {{description=Text}}
in the chat, and selecting a Token on the map, will decrease sanity by 2d10+2 and increase corruption by 1 for the character selected.
This is the ChatSetAttr API, which can be used standalone with the !modattr
command, but more notably, can be incorporated into regular macros, resulting in you being able to both make rolls and have the result change the stats.
Character Sheet Creation
Info and links to things that are only relevant or usable for when you're Building/Editing Character Sheets. Consult the rest of the guide for general details.
- Select Attributes for Sheet Roll - An advanced technique for creating a dynamic roll button on your sheet
Roll Button
The rest of this guide will help in creating more complicated macros, but the main Button#Roll_Button-page have some concrete examples of how macros are implemented in character sheets.
Sheetworkers
With the info from Macros, fairly complex outputs to the q Text Chat can be made, but to be able to construct complex and dynamic results based on various factors on your character sheet, you will need to use JavaScript to write Sheet Worker Scripts that modify & construct your roll output dynamically.
Roll Template
When you create/edit a character sheet, you can make your own Roll Templates to make your roll output look like you want, and to do some conditional things such as only showing some sections in case of a critical roll in another sections.
See Roll_Templates#Creating_a_Roll_Template for more.
Roll_Templates#Helper_Functions describes what functions you can build into your sheets.
Related Pages
- Complete Guide to Macros & Rolls
- q Text Chat - where the roll results appear, & info on the common chat commands
- Dice Reference - Comprehensive list of how the Roll20 dice-rolling syntax works, and list the features available
- Macros - How to create macros, and other info on how the Roll20 qText Chat works, like referencing stats on character sheets, roll queries, nesting macros & initiative
- Roll Templates - a method of formatting roll results in the chat, with some extra functions
- API(Pro Only) - API commands can be used in the qText Chat
TODO
- add image examples of macros used, input + output
- at least one example for each mentioned concept
- Roll Template examples
- List rest of the examples from "Stupid Tricks" thread