In this post, I’ll describe how to use a rolltemplate. Later posts describe how to design one.
Normally, you can just type text into chat, or type a roll, and it is displayed, exactly as you typed it.
That looks okay (well, honestly, it looks pretty ugly), but if you want a specific look or style for rolls or text, you need a rolltemplate.
A character sheet author can create one or more rolltemplaters, but they exist only for that sheet. If you change character sheet, you’ll lose those styles.
There is one exception: the Default Rolltemplate. Roll20 provides this for everyone to use. It’s not linked to a character sheet. It works exactly the same as all other rolletmplates, so makes a good demonstration example.
Table of Contents
Template Declaration
The text of a rolltemplate creates the porper output however you deliver it to chat. You might type it into chat, create a macro containing the output, or the sheet author might create roll buttons using the template. They are all formatted the same way.
First, start with a template declaration like this:
&{template:TEMPLATE-NAME}
&{template:default}Code language: Markdown (markdown)The &{template:name-of-template-here} is an declaration that starts the template. Everything following on the same line is considered part of that output. If you start a new line, that’s a new statement, and needs its own template declaration (or can be left alone to print as chat).
Keys and Values
When creating rolletemplate output, you need to use key and value pairs. Each {{ }} marks a new section of the output (usually a new line), the key before the = sign is label for section, and the value after the = is, well, the value.
{{KEY=VALUE}}{{ANOTHER KEY=ANOTHER VALUE}}
{{str=[[4d6kh1]]}}{{dex=[[4d6kh1]]}}{{con=[[4d6kh1]]}}{{int=[[4d6kh1]]}}{{wis=[[4d6kh1]]}}{{cha=[[4d6kh1]]}}Code language: Markdown (markdown)You can see what that looks like using the default rolltemplate.
Rolltemplate Variations
Different rolltemplates might have special effects on certain keys. For example, in the default reolltemplate, you can use the key name and that will be formatted differently.
You can often place such text anywhere in the output. It’s common to place it at the start, immediately after the template declaration, but it can be placed anywhere, like in this example.
Any ordinary output will be shown in the order it is typed, but special output like this usually appears at a specific place in the output.
Also notice how the “ordinary” keys are exach capitalised, but the special output (name=) is not. Different rolltemplates have their own rules on how keys and values are handled, including whether they are displayed at all. You often need to check what output a specific rolltemplate is expecting.
Inline Rolls
There are two ways of showing rolls in roll20 chat.
/roll 1d20+6
This is an inline roll for the same amount: [[1d20+6]]Code language: Markdown (markdown)Normal rolls and inline rolls are presented different. You might need to read the roll20 dice reference to understand the difference, but in brief, inline rolls must start a line, and that line begins /roll or /r, followieed by the roll. Inline rolls are different – they can appear anywhere in a row (inline with text) and are surrounded by square brackets [[ ]].
Normal rolls cannot be used in a rolltemplate. You must use inline rolls. Repeat: normal rolls cannot be used in a rolltemplate.
Outside the Brackets
In the above example, you’ll notice that all text is inside double curly brackets: {{something=something-else}}. Rolltemplates will drop all text not inside those curly brackets.
See how, in the picture, there is some text after the template declaration and the first key-value pair? But they don’t show in the output. That text is dropped.
But it is not ignored – it is still processed. That can be exploited…
Reusing Rolls
There is a special type of roll the community calls Reusing Rolls. They are not officially documented and may be the result of a bug, but as long as they keep working we can take advantage of them. I wont go into detail on them here – that deserves a dedicated article, but already has a comprehensive post at the wiki.
The main feature here is that you can put the reusing roll text outside of the curley brackets so it isn’t shown in the output. See how in this output the roll is placed outside the curley brackets, but the actual results of the rolls are placed in each key-value pair using $[[n]] syntax.
It’s crucial that they are placed in the same line. If the line was split, the reusing rolls method wouldn’t work.
Aside: some of the macro text in these examples uses kh1 instead of kh3 (take the best single die instead of sum of best 3 dice). Oops, but that doesn’t change how the templates work.
Rollable Tables and Images
It’s possible to create rollable tables which have a text outout and an image output. I’ve commented before on the problems with rollable tables, but there are things they are good for.
One problem with them is that when placed in an inline roll, it is assumed the user wants the text. The image is ignored, and the text is treated as if it were a number. So when calling a table multiple times (like [[3t[table] ]]), it is treated as a sum roll. There is no way to get the image out of a rollable table this way.
Any images used in a rolltemplate must already be included by the sheet author. That’s something to watch out for.
Conclusion
There you have it – a quick guide to using rolltemplates. In the next posts, we’ll look at how to create a rolltemplate.
