Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "Roll Templates"

From Roll20 Wiki

Jump to: navigation, search
m (See Also)
m (D&D 5E by Roll20)
 
(30 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<div style="background:#f0e2a1; border: 3px solid #dbc870; padding: 10px;">
+
{{revdate}}
<big>'''''Attention:'''''
+
''Roll20 is no longer maintaining this document on the community wiki. For the most up-to-date information please visit this page on our help center for assistance: [https://roll20.zendesk.com/hc/en-us/articles/360037257334-How-to-Make-Roll-Templates Here].''</big>
+
</div>
+
 
Roll Templates are a special facet of the [[Character Sheets]] system which provide additional layout and styling options for the display of roll results.
 
Roll Templates are a special facet of the [[Character Sheets]] system which provide additional layout and styling options for the display of roll results.
 
[[File:Roll template default example2.JPG|right|thumb|350px|The output of a '''default template''' used in {{Text Chat}}]]
 
[[File:Roll template default example2.JPG|right|thumb|350px|The output of a '''default template''' used in {{Text Chat}}]]
==Using Roll Templates==
+
=Using Roll Templates=
 
+
{{NavMacroDocs}}
 
If you're using a Character Sheet, there's a really good chance you'll use a Roll Template just by clicking the roll button on the sheet, or by calling a sheet roll in a macro or ability. '''You don't have to do anything extra to do this, it's already set up for you in advance by the sheet author.'''
 
If you're using a Character Sheet, there's a really good chance you'll use a Roll Template just by clicking the roll button on the sheet, or by calling a sheet roll in a macro or ability. '''You don't have to do anything extra to do this, it's already set up for you in advance by the sheet author.'''
  
 
If you're interested in using Roll Templates in your own custom macros or creating your own custom templates, read on further.
 
If you're interested in using Roll Templates in your own custom macros or creating your own custom templates, read on further.
  
Using a roll template is very easy. Just include a special flag in your chat message which tells Roll20 that you want to use a Roll Template, and then provide all of the data that you want to include. Here's an example that uses the "default" template (which all games have access to, regardless of the game system or character sheet you are using):
+
Using a roll template is pretty easy. Just include a special flag in your chat message which tells Roll20 that you want to use a Roll Template, and then provide all of the data for the rolls and info that you want to include inside <code><nowiki>{{ }}</nowiki></code>-sections . Here's an example that uses the "default" template (which all games have access to, regardless of the game system or character sheet you are using):
  
 
<pre style="overflow:hidden;white-space:pre-wrap">
 
<pre style="overflow:hidden;white-space:pre-wrap">
Line 17: Line 14:
 
</pre>
 
</pre>
  
[[File:Roll template default example.JPG||right]]
+
[[File:Roll template default example.JPG||left]]
The <code>&{template:<template_name>}</code> is the part that tells the system to use a Roll Template, and specifies the name of the template you want to use. Then you just provide all the data for the template in the format {{<propertyname>= <value>}}. The "propertyname" that you should use depends on the template -- the Character Sheet documentation should let you know what's available, and we've provided documentation on all of the built-in templates below. "Value" can be either text or an inline roll, including macros, abilities, etc. Note that if you use a macro or ability, it must be an inline roll, not a "/roll" command.
+
The <code>&{template:<template_name>}</code> is the part that tells the system to use a Roll Template, and specifies the name of the template you want to use. Then you just provide all the data for the template in the format <code><nowiki>{{<propertyname>= <value>}}</nowiki></code>. The <code>propertyname</code> that you should use depends on the template, and sometimes can be whatever you want -- the Character Sheet documentation should let you know what's available(or you can take a look at existing macros and see how they are structured), and we've provided documentation on all of the built-in templates below. <code>Value</code> can be either text or an [[Inline Roll|inline roll]], including macros, abilities, etc. Note that if you use a macro or ability, it must be an inline roll, and not a <code>/roll</code> command.
 +
 
 +
{{orange| Macros for roll templates are sensitive to leading spaces, so '''<code><nowiki>{{name=Dexterity}}</nowiki></code>''' will work, but  '''<code><nowiki>{{ name=Dexterity}}</nowiki></code>''' won't. }}
  
 
Here's an example that uses a <code>%{Character|attack}</code> ability:
 
Here's an example that uses a <code>%{Character|attack}</code> ability:
Line 26: Line 25:
 
</pre>
 
</pre>
  
====When Can I Use Roll Templates?====
+
==When Can I Use Roll Templates?==
 +
Which rolltemplates that are available in your game, is dependent on what [[CS|character sheet]] template is used in your game, as rolltemplates are coded into character sheets.
  
You can use a Roll Template in general messages (without a command like "/desc" or "/emote") and whispers. You can't use roll templates with the "/roll" command; instead, Roll Templates are meant to be used with inline rolls. As long as they use inline rolls, you can use Roll Templates with macros, Character Abilities, and sheet authors can use them inside of their Roll Buttons on sheets.
+
For example, to use the <code>&{template:simple}</code> template that is used on the [[D&D 5E by Roll20]] sheet for Ability & Skill rolls, you need to have that sheet template in your game, or it won't work. See [[D%26D_5e_by_Roll20_Roll_Templates#Simple|D&D 5E simple template]] for more.
  
==Built-In Roll Templates==
+
You can use a Roll Template in general messages (without a command like <code>/desc</code> or <code>/emote</code>) and whispers. You can't use roll templates with the <code>/roll</code> command; instead, Roll Templates are meant to be used with inline rolls. As long as they use [[Inline Rolls|inline rolls]], you can use Roll Templates with macros, Character Abilities, and [[Sheet Author|sheet authors]] can use them inside of their [[Button#Roll Button|Roll Buttons on character sheets]].
  
The following roll templates are built-in to Roll20 and can be used in any game.
+
==Examples of Roll Templates==
 +
Here are some examples of roll different templates. Only the '''default''' template is available in any game, the others can be used if the corresponding sheet is used in your [[campaign]].  
  
====Default====
+
===Default===
 +
{{main|Default Roll Template}}
 +
{{:Roll Templates/Default}}
  
To use the default template, use "&{template:default}".
+
===D&D 5E by Roll20===
 +
{{main|D&D 5e by Roll20 Roll Templates}}
  
{| class="wikitable"
+
The [[D&D 5E by Roll20]]-character sheet has 10 built in roll templates.
|-
+
! Property !! Expected Value
+
|-
+
| name || The name of the roll, shown in the header of the roll listing
+
|-
+
|}
+
  
'''The default template is special''', and will list out whatever argument you give it in a table. So for example, you could do the following:
+
{{ex}}
 +
[[File:5e-rolltemplate-ex1-2021.png|200px|right|none]]
 +
Rolls stealth for selected npc token, using its stealth proficiency. Using the <code>&{template:npcatk}</code> template from it.
 +
<pre>/w gm &{template:npcatk} {{attack=1}} {{name=Shadow}} {{rname=Shadow Stealth}} {{rnamec=Hide}} {{r1=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{always=1}} {{r2=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{description=While in dim light or darkness, the shadow can take the Hide action as a bonus action. Its stealth bonus is **also** improved to +6 }}</pre>
  
<pre style="overflow:hidden;white-space:pre-wrap">
+
===Pathfinder by Roll20===
&{template:default} {{name=Test Attack}} {{attack=[[1d20]]}} {{note= This is some note content}} {{Saving Throw= vs Will}}
+
{{main|Pathfinder by Roll20/Roll Templates}}
</pre>
+
[[File:Roll template default example2.JPG]]
+
<br />
+
  
<big>[https://jsfiddle.net/8w3qm3zL/41/ Here] is a fairly exact example of the default template with it's dependent CSS classes.</big>
+
The [[Pathfinder by Roll20]] character sheet has two different templates, one for PC (<code>&{template:pc}</code>) and one for NPC (<code>&{template:npc}</code>), that individually handles every types of roll.
  
==Creating a Roll Template==
+
They share mostly the same fields but are styled differently, and the NPC template handles attacks slightly differently. Otherwise, they generally can be used indifferently for macro purpose.
''Main Article:'' '''[[Building Character Sheets]]'''
+
  
If you are a '''Sheet Author''', you can include as many roll templates as you want in your Character Sheet HTML and CSS. We'll let you know how below.  
+
[[File:PF wiki Template.jpeg|framed|right]]
 +
Example with PC template:
 +
<pre style="overflow:auto;white-space:pre-wrap;">&{template:pc} {{showchar=[[1]]}} {{charname=charname}} {{name=name}} {{type=ability}} {{roll=roll}} {{descflag=1}} {{desc=desc}} {{shownotes=[[1]]}} {{notes=notes}}</pre>
  
If you are a '''Pro''' subscriber, you can create your own Roll Templates if you are using the "Custom" character sheet option with your game. Follow the instructions below.
+
=Creating a Roll Template=
 +
''Main Page:'' '''[[Building Character Sheets/Roll_Templates]]'''
  
===Defining the Layout of the Roll Template===
+
You can create & use custom Roll Templates by [[Building Character Sheets|Editing/Building Character Sheets]], as they are a part of the Character Sheet's code.
{{mbox | text = '''Note: '''
+
* '''1.''' Code defined in roll templates needs to use double quotes, as using single quotes to enclose attributes in roll templates makes Roll20 completly ignore the rolltemplate
+
* '''2.''' The html sections must contain the "sheet-" prefix for their classes, unlike how classes are defined in other parts of the sheet}}
+
  
The first step in creating a Roll Template is defining the layout, including what properties you are going to make available to be filled in by player. Roll Templates are just HTML, and you have access to all the same HTML as any other part of a Character Sheet (including <code>div</code> and <code>table</code>). Here's an example of the layout of a Roll Table:
+
The main page details what parts & features goes into creating a roll template, along with showing the code for a number of existing Roll Templates.
<pre data-language="html" style="overflow:hidden;white-space:pre-wrap">
+
<rolltemplate class="sheet-rolltemplate-test">
+
    <div class="sheet-template-container">
+
<div class="sheet-template-header">{{rollname}}</div>
+
{{#attack}}<div class="sheet-template-row">Attack: {{attack}} {{attackadvantage}} vs AC</div>{{/attack}}
+
        {{#damage}}
+
<div class="sheet-template-row"><span>Damage: </span>{{damage}}
+
        <span>Crit: </span>{{dmgcrit}}</div>
+
<div class="sheet-template-row"><span>Type: </span>{{dmgtype}}</div>
+
      {{/damage}}
+
      {{#atteffect}}
+
<div class="sheet-template-row">
+
<span class="sheet-template-desc">Effect: </span>{{atteffect}}
+
        </div>
+
      {{/atteffect}}
+
</rolltemplate>
+
</pre>
+
 
+
Your template should have a <code>rolltemplate</code> tag with a class of "sheet-rolltemplate-<template_name>". "template_name" is the same name that will be used in the &{template:<template_name>} portion of the command, and should not contain spaces.  You can put the roll template anywhere you want in your Character Sheet's HTML, but we recommend putting it at the very end. It will automatically be "removed' from your template so it isn't shown as part of the sheet in the Character view. Note that you cannot nest rolltemplates inside of each other.
+
 
+
After that, it's up to you to decide how to structure your roll. We recommend a table layout, but it's up to you.
+
 
+
'''Note:''' that the roll template parser currently does not accept HTML using single quotes to enclose attributes. Use double quotes instead:
+
 
+
<pre data-language="html" >
+
<!-- This won't work. -->
+
<rolltemplate class='sheet-rolltemplate-fails'>...</rolltemplate>
+
 
+
<!-- This will. -->
+
<rolltemplate class="sheet-rolltemplate-works">...</rolltemplate>
+
</pre>
+
 
+
Inside of the template, you have access to following:
+
 
+
====Properties====
+
 
+
You can include any property you'd like by using the double-curly-braces. So <code>{<nowiki />{myproperty}}</code> would output whatever (inline roll, text. etc.) is given to the template via <code>{{myproperty=<value>}}</code> in the roll. To create a new property, just add it to your template and give it a unique name. Again, avoid the use of spaces to ensure maximum compatibility with all helper functions.
+
 
+
====Logic====
+
 
+
If you do <code>{{#<property>}}</code> followed by <code>{<nowiki />{/<property>}}</code>, all of the parts between those two tags will only be shown if the property contains a value. This can be useful for providing several different parts to a template which may only be used some of the time. For example, the "Effect" part of a roll may only apply to spells, so if the roll doesn't provide an effect, that section will not be shown.
+
 
+
You can also do <code>{<nowiki />{#^<property>}}</code> followed by <code>{<nowiki />{/^<property>}}</code> to mean the opposite -- that is, only show the section if the given property does not exist.
+
 
+
====Helper Functions====
+
 
+
There are several helper functions dealing with rolls provided as well. You use these just like the normal Logic pattern above, but you are calling a function and providing a property. The section contained between the tags will only be shown if the function evaluates to true.
+
 
+
{| class="wikitable"
+
|-
+
! Helper Function !! Shows Section If
+
|-
+
| <code>{{#rollWasCrit() <rollname>}}</code> || If the provided roll contains any crits, the section will be shown. For example, <code>{<nowiki />{#rollWasCrit() attack}}</code> would check the "attack" property for an inline roll that has at least one critical roll.
+
|-
+
| <code>{{#rollWasFumble() <rollname>}}</code> || Same as #rollWasCrit(), but checks for any fumbles (rolls of 1).
+
|-
+
| <code>{{#rollTotal() <rollname>}}</code> || Checks the total of an inline roll for the value. If they match, the section is shown. For example, <code>{<nowiki />{#rollTotal() attack 10}}</code> would check the "attack" property for an inline roll that totaled 10.
+
|-
+
| <code>{{#rollGreater() <rollname>}}</code> || Checks the total of an inline roll for the value. If the roll result is greater, the section is shown. For example, <code>{<nowiki />{#rollGreater() AC 16}}</code> would check the "AC" property for an inline roll that resulted in 17 or higher.
+
|-
+
| <code>{{#rollLess() <rollname>}}</code> || Checks the total of an inline roll for the value. If the roll result is less, the section is shown. For example, <code>{<nowiki />{#rollLess() deathsave 10}}</code> would check the "deathsave" property for an inline roll that resulted in 9 or less.
+
|-
+
| <code>{{#rollBetween() <rollname>}}</code> || Checks the total of an inline roll for the value. The rollBetween() function accepts two numbers. If the roll result is equal to or between, the section is shown. For example, <code>{<nowiki />{#rollBetween() strength 7 9}}</code> would check the "strength" property for an inline roll that resulted in a seven, eight, or nine.
+
|}
+
 
+
Note: All helper functions will only check the first inline roll found in a property.
+
 
+
'''Important:''' When you "close" the section of a helper function, you must put the entire function call including all arguments. For example, <code>{<nowiki />{#rollWasCrit() attack}}</code> would be closed by <code>{<nowiki />{/rollWasCrit() attack}}</code>.
+
 
+
Here's an example roll template that would only show its Critical Damage section if the Attack roll is a crit:
+
 
+
<pre data-language="html"  style="overflow:hidden;white-space:pre-wrap">
+
    <div class="sheet-template-container">
+
<div class="sheet-template-header">{{rollname}}</div>
+
{{#attack}}<div class="sheet-template-row"><span>Attack: </span>{{attack}}</div>{{/attack}}
+
<div class="sheet-template-row">
+
<span>Damage: </span>{{damage}}
+
{{#rollWasCrit() attack}}
+
<span>Crit: </span>{{dmgcrit}}
+
{{/rollWasCrit() attack}}
+
</div>
+
<div class="sheet-template-row"><span>Type: </span>{{dmgtype}}</div>
+
  </div>
+
</pre>
+
 
+
'''Inverting The Logic:''' It's also useful to be able to test when something does not match the logic. If you want to know when a roll is Equal to OR Greater than a total, you cant do that directly. But you can test if a roll is NOT Less than a total, which is the same thing.
+
 
+
You do this starting with <code>#^</code> and ending with <code>/^</code>.  Here's how that test could look look:
+
 
+
<pre data-language="html"  style="overflow:hidden;white-space:pre-wrap">
+
{{#rollLess() attackroll }}
+
    <span>Roll Less Than attackroll! </span>
+
{{/rollLess() attackroll }}
+
{{#^rollLess() attackroll }}
+
    <span>Roll NOT Less than attackroll!</span>
+
    <span>In other words, Roll is greater than or equal to attackroll.</span>
+
{{/^rollLess() attackroll }}
+
</pre>
+
 
+
====Helper Function Variables====
+
 
+
All of the helper functions that accept a number, such as rollTotal() or rollBetween(), can use the result of another inline roll in the same Roll Template in place of the number. For example <code>{<nowiki />{#rollGreater() save poison}}</code> would compare the result of the save inline roll and the poison inline roll and show the section if the save result was greater.
+
 
+
====Special Helper Function: allProps()====
+
 
+
There is a special helper function called allProps() that can be used to dynamically list all of the properties that were passed to a roll, even if you don't explicitly include them. You can also specify properties to ignore. For example, the following would show a table with a table row for each property included in the roll, except for the "attack" property:
+
 
+
<pre data-language="html"  style="overflow:hidden;white-space:pre-wrap">
+
<div>
+
    <caption>{{name}}</caption>
+
    {{#allprops() attack}}
+
      <div>{{key}}</div><div>{{value}}</div>
+
    {{/allprops() attack}}
+
</div>
+
</pre>
+
 
+
Capitalization matters! While the function is called allProps() in these documents, it needs to be allprops() with a lowercase "p" to work correctly.
+
 
+
===Styling Roll Templates===
+
 
+
To style a Roll Template, just include CSS for it in the CSS for your Character Sheet. Here's a quick example that should give you a good idea of how to do it (in this example, the roll template's name is "test"):
+
 
+
<pre data-language="css"  style="overflow:hidden;white-space:pre-wrap">
+
.sheet-rolltemplate-test div.sheet-template-container {
+
border: 2px solid #000 !important;
+
border-radius: 3px 3px 3px 3px;
+
}
+
 
+
.sheet-rolltemplate-test .sheet-template-header {
+
background-color: rgba(112, 32, 130,1);
+
color: #000;
+
padding: 2px;
+
border-bottom: 1px solid black;
+
line-height: 1.6em;
+
font-size: 1.2em;
+
}
+
 
+
.sheet-rolltemplate-test div {
+
padding: 5px;
+
border-bottom: 1px solid black;
+
}
+
 
+
.sheet-rolltemplate-test div:nth-child(odd) {
+
background-color: rgba(217, 217, 214,1);
+
}
+
 
+
.sheet-rolltemplate-test div:nth-child(even) {
+
background-color: rgba(233, 233, 233,1);
+
}
+
 
+
.sheet-rolltemplate-test .inlinerollresult  {
+
display: inline-block;
+
min-width: 1.5em;
+
text-align: center;
+
border: 2px solid rgba(167, 168, 170,1);
+
}
+
 
+
.sheet-rolltemplate-test .inlinerollresult.fullcrit {
+
border: 2px solid #3FB315;
+
}
+
 
+
.sheet-rolltemplate-test .inlinerollresult.fullfail {
+
border: 2px solid #B31515;
+
}
+
 
+
.sheet-rolltemplate-test .inlinerollresult.importantroll {
+
border: 2px solid #4A57ED;
+
}
+
</pre>
+
 
+
Notice that all of the styles begin with ".sheet-rolltemplate-<templatename>". You can then style your own custom HTML (such as the tables, divs, and classes that you used). Note that any classes you include in your roll template layout (such as "tcat" in the above example) will have ".userscript-" added to the beginning of them for security reasons. The easiest thing to do is to create your layout, then perform a roll in-game and inspect the resulting HTML so you can make sure you are accounting for any security filtering that is taking place.
+
 
+
==Roll Template Examples==
+
Listed below are a handful of system specific examples of the Roll Template functionality.
+
 
+
===Jakob's Better Default Rolltemplate===
+
In this [https://app.roll20.net/forum/permalink/6792597/ forum post], Jakob created a better rolltemplate that could be used in place of the default one. You can add this to your sheet by simply adding the HTML & CSS to the end of your character sheet, and you're able to use the macro examples to call it.
+
 
+
By default it looks and behaves similarly, but have extra features and is an easy starting point for creating your own.
+
 
+
* Support for title and subtitle (e.g. roll name and character name, <code><nowiki>{{title= roll name}}</nowiki></code> and <code><nowiki>{{subtitle= character name}}</nowiki></code>)
+
* Easy support for adding extra colors via <code><nowiki>{{color=foo}}</nowiki></code> (colors red and green included as a demonstration - colors need to be hardcoded into the CSS, it doesn't seem possible to color the title dynamically)
+
* Full-width description field at the bottom, (<code><nowiki>{{desc= Full-width description here}}</nowiki></code>)
+
* Customizable column widths [[File:Jakob-better-default-template-ex.png|thumbnail|Macro(Example 1)|right|500px]]
+
 
+
 
+
Macro, Example 1:
+
 
+
(uses the title , subtitle, and two generic fields)
+
<pre style="overflow:hidden;white-space:pre-wrap">
+
&{template:custom} {{title=Energy Claws}} {{subtitle=Razor Claw(Hero)}} {{Attack = [[1d20+5]]}} {{Notes = +2 to hit vs. anyone surprised}}
+
</pre>
+
 
+
[[File:Jakob-better-default-template-ex2.png|thumbnail|Macro(Example 2)|right|500px]]
+
Macro, Example 2:
+
 
+
(uses the title, one generic, and the description field)
+
<pre style="overflow:hidden;white-space:pre-wrap">
+
&{template:custom} {{title=Energy Claws}} {{Attack = [[1d20+5]]}} {{desc=**Special:** +2 to hit vs. anyone surprised. If you make a leap as part of the attack or have the high ground, this bonus is instead +3}}
+
</pre>
+
 
+
[[File:Jakob-better-default-template-ex3.png|thumbnail|Macro(Example 3)|right|500px]]
+
Macro, Example 3:
+
 
+
(uses the color selector(green), and title, subtitle, one generic, and the description field)
+
<pre style="overflow:hidden;white-space:pre-wrap">
+
&{template:custom} {{color=green}} {{title=Energy Claws(Attack)}} {{subtitle=Razor Claw(Hero)}} {{Fighting = [[{1d8!, 1d6!}k1]] }} {{Damage = [[3d6!]] }} {{desc=Energy Claws is an Innate Attack, Superpower. Requires conscious activation.}}
+
</pre>
+
 
+
HTML:
+
<pre data-language="html" style="overflow:hidden;white-space:pre-wrap">
+
<rolltemplate class="sheet-rolltemplate-custom">
+
  <div class="sheet-container sheet-color-{{color}}">
+
    <div class="sheet-header">
+
      {{#title}}<div class="sheet-title">{{title}}</div>{{/title}}
+
      {{#subtitle}}<div class="sheet-subtitle">{{subtitle}}</div>{{/subtitle}}
+
    </div>
+
    <div class="sheet-content">
+
      {{#allprops() title subtitle desc color}}
+
      <div class="sheet-key">{{key}}</div>
+
      <div class="sheet-value">{{value}}</div>
+
      {{/allprops() title subtitle desc color}}
+
      {{#desc}}<div class="sheet-desc">{{desc}}</div>{{/desc}}
+
    </div>
+
  </div>
+
</rolltemplate>
+
</pre>
+
CSS:
+
<pre data-language="css" style="overflow:hidden;white-space:pre-wrap">
+
/* Smaller margins - remove these if you want the huge default left margin */
+
.sheet-rolltemplate-custom {
+
  margin-left: -37px;
+
}
+
.withoutavatars .sheet-rolltemplate-custom {
+
  margin-left: -7px;
+
}
+
 
+
.sheet-rolltemplate-custom .sheet-container {
+
  border: 1px solid;
+
  /* by default, the border is the same color as the header. You can change this here, e.g. to black */
+
  border-color: var(--header-bg-color);
+
}
+
 
+
/* Header formatting - title and subtitle */
+
.sheet-rolltemplate-custom .sheet-header {
+
  background-color: var(--header-bg-color);
+
  /* change text-align to center to center the header text */
+
  text-align: left;
+
  color: var(--header-text-color);
+
  padding: 5px;
+
}
+
.sheet-rolltemplate-custom .sheet-title {
+
  font-size:1.1em;
+
}
+
.sheet-rolltemplate-custom .sheet-subtitle {
+
  font-size:.9em;
+
}
+
 
+
/* example colors */
+
.sheet-rolltemplate-custom .sheet-container {
+
  /* this is the default color */
+
  --header-bg-color: rgba(112,32,130,1);
+
  --header-text-color: #FFF;
+
}
+
.sheet-rolltemplate-custom .sheet-container.sheet-color-red {
+
  --header-bg-color: #F00;
+
}
+
.sheet-rolltemplate-custom .sheet-container.sheet-color-green {
+
  --header-bg-color: #0F0;
+
  --header-text-color: #000;
+
}
+
 
+
/* Allprops part */
+
.sheet-rolltemplate-custom .sheet-content {
+
  display: grid;
+
  background: #FFF;
+
  /* Header formatting - modify the column layout below */
+
  grid-template-columns: auto auto;
+
  /* Line height to match default roll template */
+
  line-height:1.4em;
+
}
+
.sheet-rolltemplate-custom .sheet-content > div {
+
  padding: 5px;
+
}
+
 
+
/* Left column */
+
.sheet-rolltemplate-custom .sheet-content .sheet-key {
+
  font-weight: bold;
+
  padding-right: 10px;
+
  text-align: right;
+
}
+
 
+
/* Empty rule, use this if you want to change the right column
+
.sheet-rolltemplate-custom .sheet-value {
+
}
+
*/
+
 
+
/* Make even-numbered rows grey */
+
.sheet-rolltemplate-custom .sheet-content :nth-child(4n+3),
+
.sheet-rolltemplate-custom .sheet-content :nth-child(4n) {
+
  background:#EEE;
+
}
+
 
+
/* Description field */
+
.sheet-rolltemplate-custom .sheet-desc {
+
  grid-column: span 2;
+
  padding: 5px;
+
  text-align: center;
+
}
+
</pre>
+
 
+
====Migrate from Default Rolltemplate to Jakob's====
+
[[File:Def-rolltemplate-vs-jakob-template.png|thumbnail|right|Default roll template(top) vs. Jakob's improved version(bottom)|400px]]
+
If you previously used the default roll template on your sheet and want to edit the macros to work with the new one, there are two spots you must to edit to make it work.
+
 
+
This macro using the default roll template:
+
 
+
<code>
+
&{template:'''default'''} <nowiki>{{</nowiki>'''name'''=Sword Attack<nowiki>}}</nowiki> <nowiki>{{attack=[[1d20]]}} {{damage=[[2d6]]}} {{Notes=Sword shouts "Gnome" repeatedly when you're within 20ft of any halfling or dwarf.}}</nowiki>
+
</code>
+
 
+
Needs at the very least change the template name and swap the header name from '''name''' to '''title''', to keep things working the same:
+
 
+
<code>
+
&{template:'''custom'''} <nowiki>{{</nowiki>'''title'''=Sword Attack<nowiki>}}</nowiki> <nowiki>{{attack=[[1d20]]}} {{damage=[[2d6]]}} {{Notes=Sword shouts "Gnome" repeatedly when you're within 20ft of any halfling or dwarf.}}</nowiki>
+
</code>
+
 
+
Furthermore, the macro can be improved by switching the last generic field to use the full-width '''desc'''-field, and adding the subtitle field to show the name of the character to avoid confusion about who made the roll.
+
 
+
<code>
+
&{template:'''custom'''} <nowiki>{{</nowiki>'''title'''=Sword Attack<nowiki>}}</nowiki> '''<nowiki>{{</nowiki>subtitle= Average Ruffian<nowiki>}}</nowiki>''' <nowiki>{{attack=[[1d20]]}} {{damage=[[2d6]]}} {{</nowiki>'''desc'''=Sword shouts "Gnome" repeatedly when you're within 20ft of any halfling or dwarf.<nowiki>}}</nowiki>
+
</code>
+
 
+
 
+
===Dungeons and Dragons 5th Edition===
+
[[File:Rolltemplate 5e.png|right]]
+
Macro:
+
<pre style="overflow:hidden;white-space:pre-wrap">
+
&{template:5eAttack} {{name=@{meleeweaponname1}}} {{subtags=Main Hand, Finess, @{meleedmgtype1}}} {{attack=[[1d20+@{meleetohit1}]]}} {{attackadv=[[1d20+@{meleetohit1}]]}} {{damage=[[@{meleedmg1}+@{meleedmgbonus1}]]}} {{dmgcrit=[[@{meleedmg1}]]}}
+
</pre>
+
HTML:
+
<pre data-language="html" style="overflow:hidden;white-space:pre-wrap">
+
<rolltemplate class="sheet-rolltemplate-5eAttack">
+
    <div class="container">
+
        <div><h1>{{name}}</h1></div>
+
        <div><span class="subheader">{{subtags}}</span></div>
+
        <div class="arrow-container"><div class="arrow-right"></div></div>
+
        <div class="rowcolor"><span class="tcat">Attack: </span>{{attack}} | {{attackadv}} vs AC</div>
+
        {{#damage}}
+
            <div>
+
                <span class="tcat">Damage: </span>{{damage}}
+
                <span class="tcat">Crit: </span>{{dmgcrit}}
+
            </div>
+
        {{/damage}}
+
        {{#snkattk}}
+
            <div>
+
                <span class="tcat">Sneak Attack: </span>{{snkattk}}
+
                <span class="tcat">Crit: </span>{{snkcrit}}
+
            </div>
+
        {{/snkattk}}
+
    </div>
+
</rolltemplate>
+
</pre>
+
CSS:
+
<pre data-language="css" style="overflow:hidden;white-space:pre-wrap">
+
.sheet-rolltemplate-5eAttack .sheet-container {
+
    background-color: #ffffff;
+
    border: 1px solid;
+
    padding: 2px;
+
    width: 189px;
+
}
+
 
+
.sheet-rolltemplate-5eAttack .sheet-container h1 {
+
    color: rgb(126, 45, 64);
+
    font-size: 1.2em;
+
    font-variant: small-caps;
+
    line-height: 20px;
+
}
+
 
+
.sheet-rolltemplate-5eAttack div {
+
    padding: 2px;
+
};
+
+
.sheet-rolltemplate-5eAttack span {
+
    color: rgb(126, 45, 64);
+
    font-family: "Times New Roman", Times, serif;
+
    font-size: 1.2em;
+
    font-variant: small-caps;
+
    line-height: 1.6em;
+
    padding-left: 5px;
+
    text-align: left;
+
}
+
+
.sheet-rolltemplate-5eAttack .sheet-subheader {
+
    color: #000;
+
    font-size: 1em;
+
    font-style: italic;
+
}
+
+
.sheet-rolltemplate-5eAttack .sheet-arrow-right {
+
    border-bottom: 2px solid transparent;
+
    border-left: 180px solid rgb(126, 45, 64);
+
    border-top: 2px solid transparent;
+
}
+
+
.sheet-rolltemplate-5eAttack .sheet-tcat {
+
    font-style: italic;
+
}
+
+
.sheet-rolltemplate-5eAttack .inlinerollresult  {
+
    background-color: #ffffff;
+
    border: none;
+
}
+
+
.sheet-rolltemplate-5eAttack .inlinerollresult.fullcrit {
+
    color: #3FB315;
+
    border: none;
+
}
+
+
.sheet-rolltemplate-5eAttack .inlinerollresult.fullfail {
+
    color: #B31515;
+
    border: none;
+
}
+
+
.sheet-rolltemplate-5eAttack .inlinerollresult.importandivoll {
+
    color: #4A57ED;
+
    border: none;
+
}
+
</pre>
+
 
+
===Dungeons and Dragons 3.5 / Pathfinder===
+
[[File:Rolltemplate pf.png|right]]
+
Macro:
+
<pre style="overflow:hidden;white-space:pre-wrap">
+
&{template:pf_spell} {{name=@{repeating_lvl-0-spells_0_name}}}{{school=@{repeating_lvl-0-spells_0_school}}} {{level=sorcerer/wizard 0}} {{casting_time=@{repeating_lvl-0-spells_0_cast-time}}} {{components=@{repeating_lvl-0-spells_0_components}}} {{range=@{repeating_lvl-0-spells_0_range}}} {{target=@{repeating_lvl-0-spells_0_targets}}} {{duration=@{repeating_lvl-0-spells_0_duration}}} {{saving_throw=@{repeating_lvl-0-spells_0_save}}} {{sr=@{repeating_lvl-0-spells_0_sr}}} {{rng_attack=[[1d20 + @{attk-ranged}]]}} {{damage=1d3([[1d3]])}} {{spell_description=@{repeating_lvl-0-spells_0_description}}}
+
</pre>
+
HTML:
+
<pre data-language="html" style="overflow:hidden;white-space:pre-wrap">
+
<rolltemplate class="sheet-rolltemplate-pf_spell">
+
    <table>
+
        <tr><th>{{name}}</th></tr>
+
        <tr>
+
            <td><span class="tcat">School </span>{{school}}; <span class="tcat">Level </span>{{level}}</td>       
+
        </tr>
+
        <tr>
+
            <td><span class="tcat">Casting Time </span>{{casting_time}}</td>       
+
        </tr>
+
        <tr>
+
            <td><span class="tcat">Components </span>{{components}}</td>       
+
        </tr>
+
        <tr>
+
            <td><span class="tcat">Range </span>{{range}}</td>       
+
        </tr>
+
        <tr>
+
            <td><span class="tcat">Effect/Target </span>{{target}}</td>       
+
        </tr>
+
        <tr>
+
            <td><span class="tcat">Duration </span>{{duration}}</td>       
+
        </tr>
+
        <tr>
+
            <td><span class="tcat">Saving Throw </span>{{saving_throw}}; <span class="tcat">Spell Resistance </span>{{sr}}</td>       
+
        </tr>
+
        {{#rng_attack}}
+
            <tr><td><span class="tcat">Ranged Attack </span>{{rng_attack}}</td></tr>
+
        {{/rng_attack}}
+
        {{#mel_attack}}
+
            <tr><td><span class="tcat">Melee Attack </span>{{mel_attack}}</td></tr>
+
        {{/mel_attack}}
+
{{#damage}}
+
<tr><td><span class="tcat">Damage: </span>{{damage}}</td></tr>
+
{{/damage}}
+
        <tr>
+
            <td>{{spell_description}}</td>       
+
        </tr>
+
    </table>
+
</rolltemplate>
+
</pre>
+
CSS:
+
<pre data-language="css" style="overflow:hidden;white-space:pre-wrap">
+
.sheet-rolltemplate-pf_spell table {
+
    width: 100%;
+
    padding: 2px;
+
    background:url(http://i.imgur.com/BLb0XMU.jpg) top left repeat;
+
}
+
+
.sheet-rolltemplate-pf_spell th {
+
color: rgb(233, 223, 151);
+
    background-color: rgb(63, 32, 33);
+
    padding-left: 5px;
+
line-height: 1.1em;
+
font-size: 1em;
+
    text-align: left;
+
font-family: "Arial", Helvetica, sans-serif;
+
    text-transform: uppercase;
+
}
+
+
.sheet-rolltemplate-pf_spell .sheet-arrow-right {
+
    border-top: 3px solid transparent;
+
    border-bottom: 3px solid transparent;
+
border-left: 180px solid rgb(126, 45, 64);
+
}
+
+
.sheet-rolltemplate-pf_spell .sheet-tcat {
+
    font-weight: bold;
+
}
+
+
.sheet-rolltemplate-pf_spell td {
+
    padding-left: 5px;
+
    font-size: 0.9em;
+
}
+
+
.sheet-rolltemplate-pf_spell .inlinerollresult  {
+
    background-color: transparent;
+
    border: none;
+
}
+
+
.sheet-rolltemplate-pf_spell .inlinerollresult.fullcrit {
+
color: #3FB315;
+
    border: none;
+
}
+
+
.sheet-rolltemplate-pf_spell .inlinerollresult.fullfail {
+
color: #B31515;
+
    border: none;
+
}
+
+
.sheet-rolltemplate-pf_spell .inlinerollresult.importantroll {
+
color: #4A57ED;
+
    border: none;
+
}
+
</pre>
+
 
+
===World of Darkness===
+
[[File:Rolltemplate wod.png|right]]
+
Macro:
+
<pre style="overflow:hidden;white-space:pre-wrap">
+
&{template:wod} {{name=@{character_name}}} {{roll_name=Command}} {{attr=Intelligence}} {{attr_num=@{intelligence}}} {{skill=Intimidation}} {{skill_num=@{intimidation}}} {{pwr=Dominate}} {{pwr_num=@{dominate}}} {{mod_num=?{Modifiers|0}}} {{result=[[{(@{intelligence}+@{intimidation}+@{dominate}+?{Modifiers|0})d10!}>8]]}}
+
</pre>
+
HTML:
+
<pre data-language="html" style="overflow:hidden;white-space:pre-wrap">
+
<rolltemplate class="sheet-rolltemplate-wod">
+
    <table>
+
        <tr><th>{{name}} rolls{{#roll_name}} {{roll_name}}{{/roll_name}}</th></tr>
+
        <tr><td class="attr">
+
            {{#attr}}
+
                {{attr}}({{attr_num}})
+
            {{/attr}}
+
            {{#skill}}
+
                + {{skill}}({{skill_num}})
+
            {{/skill}}
+
    {{#pwr}}
+
    + {{pwr}}({{pwr_num}})
+
    {{/pwr}}
+
            {{#mod_num}}
+
                + Modifiers({{mod_num}})
+
            {{/mod_num}}
+
        </td></tr>
+
        <tr>
+
            <td class="result">{{result}} Successes</td>       
+
        </tr>
+
    </table>
+
</rolltemplate>
+
</pre>
+
CSS:
+
<pre data-language="css" style="overflow:hidden;white-space:pre-wrap">
+
.sheet-rolltemplate-wod table {
+
    width: 189px;
+
    height: 189px;
+
    padding: 2px;
+
    background: url(http://i.imgur.com/xBk4U1p.jpg) top left;
+
    background-size: 189px 189px;
+
    background-repeat: no-repeat;
+
    font-family: "Courier New", Courier, monospace;
+
    font-weight: bold;
+
    border-spacing: 0;
+
}
+
+
.sheet-rolltemplate-wod th {
+
color: rgb(112, 0, 0);
+
    padding: 15px 2px 2px 20px;
+
line-height: 1.2em;
+
font-size: 1.2em;
+
    text-align: left;
+
}
+
+
+
.sheet-rolltemplate-wod td {
+
    padding-left: 20px;
+
    font-size: 1.0em;
+
    vertical-align: top;
+
}
+
+
.sheet-rolltemplate-wod .sheet-result {
+
    font-size: 1.2em;
+
    text-align: center;
+
    color: rgb(112, 0, 0);
+
    padding-bottom: 20px;
+
}
+
+
.sheet-rolltemplate-wod .inlinerollresult  {
+
    background-color: transparent;
+
    color: #000000;
+
    border: none;
+
}
+
+
.sheet-rolltemplate-wod .inlinerollresult.fullcrit {
+
  color: #3FB315;
+
    border: none;
+
}
+
+
.sheet-rolltemplate-wod .inlinerollresult.fullfail {
+
    color: #000000;
+
    border: none;
+
}
+
+
.sheet-rolltemplate-wod .inlinerollresult.importantroll {
+
color: #3FB315;
+
    border: none;
+
}
+
</pre>
+
  
 
= See Also =
 
= See Also =
* [[Dice Reference]]
+
* '''[[Complete Guide to Macros & Rolls‎]]'''
* [[Macros]]
+
** {{Text Chat}} - where the roll results appear, & info on the common chat commands
* [[Building Character Sheets]]
+
** [[Dice Reference]] - Comprehensive list of how the Roll20 dice-rolling syntax works, and list the features available
* [[Reusing_Rolls#Rolltemplate_Helper_functions|Reusing Rolls in Roll Templates]]
+
** [[Macros]] - How to create macros, and other info on how the Roll20 <span style="font-family:Pictos;">q</span>Text Chat works, like referencing stats on character sheets, roll queries, nesting macros & initiative
 +
*** [[Reusing_Rolls#Rolltemplate_Helper_functions|Reusing Rolls in Roll Templates]]
 +
** [[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 <span style="font-family:Pictos;">q</span>Text Chat
 +
* [[BCS|Building Character Sheets]]
 +
** [[Building Character Sheets/Roll Templates|Creating Roll Templates]]
 +
** [[Sheet Author Tips]] More advanced tips for creating/maintaining sheets, workflow, & useful tools
 +
** [[Custom Sheet Sandbox|Sheet Sandbox]] – the better editor to use when you code your character sheets
 +
* {{hc|articles/360037257334-How-to-Make-Roll-Templates Official version of this page}} - Often lacking compared to any pages on sheet development on the community wiki
 
<br>
 
<br>
 
<br>
 
<br>
  
 
[[Category:Docs]]
 
[[Category:Docs]]
[[Category:Character Sheet Creation]]
+
[[Category:Macros]]
 +
[[Category:Roll Templates]]
 +
[[Category:Character Sheets]]

Latest revision as of 00:08, 11 January 2023

Roll Templates are a special facet of the Character Sheets system which provide additional layout and styling options for the display of roll results.

The output of a default template used in q Text Chat

Contents

[edit] Using Roll Templates

If you're using a Character Sheet, there's a really good chance you'll use a Roll Template just by clicking the roll button on the sheet, or by calling a sheet roll in a macro or ability. You don't have to do anything extra to do this, it's already set up for you in advance by the sheet author.

If you're interested in using Roll Templates in your own custom macros or creating your own custom templates, read on further.

Using a roll template is pretty easy. Just include a special flag in your chat message which tells Roll20 that you want to use a Roll Template, and then provide all of the data for the rolls and info that you want to include inside {{ }}-sections . Here's an example that uses the "default" template (which all games have access to, regardless of the game system or character sheet you are using):

&{template:default} {{name=Test Attack}} {{attack=[[1d20]]}} {{damage=[[2d6]]}}
Roll template default example.JPG

The &{template:<template_name>} is the part that tells the system to use a Roll Template, and specifies the name of the template you want to use. Then you just provide all the data for the template in the format {{<propertyname>= <value>}}. The propertyname that you should use depends on the template, and sometimes can be whatever you want -- the Character Sheet documentation should let you know what's available(or you can take a look at existing macros and see how they are structured), and we've provided documentation on all of the built-in templates below. Value can be either text or an inline roll, including macros, abilities, etc. Note that if you use a macro or ability, it must be an inline roll, and not a /roll command.


Here's an example that uses a %{Character|attack} ability:

&{template:default} {{name=Test With Ability}} {{attack= %{Character_Name|attack} }} {{damage= #damagemacro }}

[edit] When Can I Use Roll Templates?

Which rolltemplates that are available in your game, is dependent on what character sheet template is used in your game, as rolltemplates are coded into character sheets.

For example, to use the &{template:simple} template that is used on the D&D 5E by Roll20 sheet for Ability & Skill rolls, you need to have that sheet template in your game, or it won't work. See D&D 5E simple template for more.

You can use a Roll Template in general messages (without a command like /desc or /emote) and whispers. You can't use roll templates with the /roll command; instead, Roll Templates are meant to be used with inline rolls. As long as they use inline rolls, you can use Roll Templates with macros, Character Abilities, and sheet authors can use them inside of their Roll Buttons on character sheets.

[edit] Examples of Roll Templates

Here are some examples of roll different templates. Only the default template is available in any game, the others can be used if the corresponding sheet is used in your campaign.

[edit] Default

Main Page: Default Roll Template


The Default Roll Template is available in all Roll20. You don't have to even have a character sheet template selected for your game to use it.


Property Expected Value
name The name of the roll, shown in the header of the roll listing. (If not used in a roll, the header will appear at the top of the roll template as a purple bar with no text.)
(anything) You can have any number of rows with any name you want, making the template somewhat flexible. The "property" name will be bold.

The default template is special, and will list out whatever argument you give it in a table. It will put in the middle of the purple header anything you define in the {{name= }} section, and then with every subsequent {{ }} segment, it will alternate with white & gray background.

If a = is used in the {{ }} rows, the roll template will align the = in the middle, and all rows will have the = in the same spot. If any row have lots of more text/content on either side of the =, it will be pressed to the side of the template for all rolls.


Example:

&{template:default} {{name=Test Attack}} {{attack=[[1d20+3]]}} {{note= This is some note content}} {{Saving Throw= vs Will}}

Roll template default example2.JPG

Notice that the content of the roll template is pressed to the left side, due the text segment on the Note-row. If that segment is removed, the content of the remaining rows will be closer to the center.

Here is a fairly close example of the default template's HTML& CSS with it's dependent CSS classes. If you intend to make your own roll template, or want to start from the default template, the best idea is to start with the code from Jakob's Better Default Template.

[edit] Examples

Some more examples using the default roll template. These should give more examples on how they can be used.


Roll template rolls that has inline labels, which will make it easier to look at the roll breakdown(when you hover your mouse over the result).

&{template:default} {{name=Mage Bolt}} {{attack=[[1d20+3[int]+2[proficiency] ]]}} {{Damage= [[3d6[base dmg]+3[int mod]+1d8[Elder Wand bonus] force dmg]]}} {{DC [[14]] Will Save= The enemy must make the save, or take an extra [[1d8]] fire dmg. }}

You can have rolls on both sides of the =

&{template:default} {{name=Greatsword of the Nomads}} {{attack= has advantage, pick higher result}} {{[[1d20+4]]=[[1d20+4]]}} {{Damage= [[2d6+2]]}} {{If critical= Apply only if attack is critical}} {{Crit damage= deals [[2d6]] more on crit}} {{Special Crit= The Greatsword of the Nomads deals on crit an extra [[1d8]] radiant damage, and the defender needs to make a DC [[14]] Con save or gain a level of exhaustion}}

Several attacks at a time

&{template:default} {{name=Fist of Fury}} {{Attack1= [[1d20+5]]}} {{Damage1= [[1d6+3]]}} {{Attack2= [[1d20+5]]}} {{Damage2= [[1d6+3]]}} {{Offhand= [[1d20+4]]}} {{Damage1= [[1d4+3]]}}

Short Rest Macro

It asks you how many to spend & what hit dice to use, and displays how much was recovered as well as how many where spent(using the Reusing Rolls-trick).

&{template:default} {{name=Short Rest}} {{Recover=  You heal [[ [[?{How many hit dice do you spend?|1}]]?{What's your Hit dice?|d4|d6|d8|d10|d12} ]] hit points, having spent $[[0]] of their hit dice.}}

Show Token info

Select a token on the map, and call this macro to get info on the token. If the token represents a character, it will show it's character_id & character_name, otherwise just show "selected|character_id" & "selected|character_name" if they are missing.

&{template:default} {{name=Token Info }} {{TokenID=@{selected|token_id} }} {{CharacterID=@{selected|character_id} }} {{TokenName=@{selected|token_name} }} {{characterName=@{selected|character_name} }} {{Bar1=@{selected|bar1} / @{selected|bar1|max} }} {{Bar2=@{selected|bar2} / @{selected|bar2|max} }} {{Bar3=@{selected|bar3} / @{selected|bar3|max} }} &{error}


[edit] D&D 5E by Roll20

Main Page: D&D 5e by Roll20 Roll Templates

The D&D 5E by Roll20-character sheet has 10 built in roll templates.


Example:

5e-rolltemplate-ex1-2021.png

Rolls stealth for selected npc token, using its stealth proficiency. Using the &{template:npcatk} template from it.

/w gm &{template:npcatk} {{attack=1}} {{name=Shadow}} {{rname=Shadow Stealth}} {{rnamec=Hide}} {{r1=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{always=1}} {{r2=[[@{selected|d20}+@{selected|npc_stealth} + 6]]}} {{description=While in dim light or darkness, the shadow can take the Hide action as a bonus action. Its stealth bonus is **also** improved to +6 }}

[edit] Pathfinder by Roll20

Main Page: Pathfinder by Roll20/Roll Templates

The Pathfinder by Roll20 character sheet has two different templates, one for PC (&{template:pc}) and one for NPC (&{template:npc}), that individually handles every types of roll.

They share mostly the same fields but are styled differently, and the NPC template handles attacks slightly differently. Otherwise, they generally can be used indifferently for macro purpose.

PF wiki Template.jpeg

Example with PC template:

&{template:pc} {{showchar=[[1]]}} {{charname=charname}} {{name=name}} {{type=ability}} {{roll=roll}} {{descflag=1}} {{desc=desc}} {{shownotes=[[1]]}} {{notes=notes}}

[edit] Creating a Roll Template

Main Page: Building Character Sheets/Roll_Templates

You can create & use custom Roll Templates by Editing/Building Character Sheets, as they are a part of the Character Sheet's code.

The main page details what parts & features goes into creating a roll template, along with showing the code for a number of existing Roll Templates.

[edit] See Also