Revision as of 21:43, 5 March 2023

Page Updated:   2023-03-05

Main Page: Macro Guide

This is Tips and tricks on formatting how messages in the q Text Chat appear.

Formatting

You can use common Markdown to format you text, and to even create hyperlinks in text shown in the chat.

If you hyperlink to to a i Compendium page, it will open up inside Roll20 when clicked.

Markdown

Markdown is available to let you bold, italic, bold-italic, create a hyperlinks, or include even an image in your macros and text as they appear in the q Text Chat. You can use basic Markdown syntax in your text chat messages. We don't support the entire breadth of everything Markdown can do (like headers), but rather just basic formatting. Here's a quick rundown:

Alternative to adding the markdown into the macros, you can sometimes add the markdown to your Character Attributes, so you can have a universal macro, and make individual adjustment to to how you want each output to look like.

Example:

/em his **@{bob|height}** tall, and can be described as: @{bob|description}.

Note on Code: The extra backtick at the start of the code snippet is required due to the backtick character also being the character used to escape commands.

Note on Images: Including an image is just putting in a link to an image. If the link ends in .png, .jpg, .jpeg, or .gif, we will automatically insert an image tag in addition to linking to the source image.

 {{attack= [[1d20]] vs **AC**}}

Styling with CSS

You can further style chat output and Chat Menus using CSS, which is a hack discovered by Oosh.

• How to use HTML Styles in chat^(Forum) - Oosh
  • CSS Styled Text(shorter)

Here is how you can modify a basic chat menu with colors etc. Take [Macro1](~Macro1) and turn it into: [Macro1](~Macro1" style="border:none;background-color:transparent;padding:0px;color:#3452eb;font-weight:bold;)

1. border can be used to create a border around your button. If you are turning the button transparent just leave it set to "none" (without quotes). If you do want a border this short explanation may help: CSS border shorthand

2. background-color removes the pink box by turning it transparent. You can also turn the pink box into another color by substituting a color word such as "aqua" (without quotes). You can find color names here: https://htmlcolorcodes.com/color-names/

3. padding controls how big the clickable space is around your button-name. A px of 0 is no extra clickable space. A px of 5 is a lot of extra clickable space. You will want to play with this to get a space around your button-name that looks good.

4. color sets the color of the name using a hex color code (such as #3452eb). Here is a source of hex color codes: https://htmlcolorcodes.com/

5. font-weight sets how thick the letters look (such as bold). If you want something other than bold you can use a word (such as lighter) or a number (such as 300). Here is a short guide on font weights: https://www.w3schools.com/cssref/pr_font_weight.php

In the end it will look something like this:

/w gm &{template:npcaction} &{noerror} {{rname=@{selected|character_name}}} {{name=@{selected|npc_type}}} {{description=[Macro1](~Macro1" style="border:none;background-color:transparent;padding:0px;color:#3452eb;font-weight:bold;) }}

A note regarding Light/Dark mode: the color(s) you set up here will not change depending on mode, so make sure you select colors that will display well in the mode of your choice.

Other advanced

• Tooltips in Text Chat^(Forum)
  • Tooltip Styling^(Forum)
• Making links
  • Using Images as Links^(Forum) - Oosh
  • Hypertext Macro to Open a Linked Character Sheet Hypertext Macro to Open a Linked Character Sheet^(Forum) - Vince
  • link to open a Compendium page from chat^(Forum)
• %NEWLINE% trick + misc.^(Forum) - Andreas J.
• Multiline Chat messages using Triple Brackets^(Forum) - Keith

HTML replacement

Main Page: HTML Entities

When creating some complicated macros, usually involving nesting, you will need to use HTML entities in parts of the code to trick the Roll20 system to make it behave like you want, or some advanced tricks won't work.

Here are some HTML Entities/Escape Characters that are commonly useful to escape when creating advanced Roll20 macros. See HTML Entities or special character for more:

|, }, and , are the most common character that need to be replaced in nested macros.

Character	Replacement
| (pipe)	|, (|)
,	,, (,)
{	{, ({)
}	}, (})
&	&, (&)
space	 , ( )
=	=, (=)
_	_, (_)
(	(, (()
)	), ())
[	[, ([)
]	], (])
<	&#60;, (&lt;)
>	&#62;, (&gt;)
`(backtick, grave accent)	&#96;, (&grave;)
*(asterisk)	&#42;, (&ast;)
!	&#33;, (&excl;)
"(doublequote)	&#34;, (&quot;)
#	&#35;, (&num;)
-(hyphen)	&#45;, (&dash;)
@	&#64;, (&commat;)
%	&#37;, (&percnt;)

Example:

Here is a macro that will not work, because the "Choose a Roll"-query thinks it stops at the first } it encounters, which is on the second row:

?{Choose a Roll|
  STR,/roll 1d20 + 3 + (?{Modifier})|
  DEX,/roll 1d20 + 2 + (?{Modifier})|
  CON,/roll 1d20 + 1 + (?{Modifier})}

Fixed version:

By using HTML entities to replace all } inside "Choose a Roll", it will now correctly process where the query ends.

?{Choose a Roll|
  STR,/roll 1d20 + 3 + (?{Modifier}) |
  DEX,/roll 1d20 + 2 + (?{Modifier}) |
  CON,/roll 1d20 + 1 + (?{Modifier}) }

If you want to change the ?{Modifier}-query to have a default value like ?{Modifier|0}, you will need to replace the |, so the query won't mistakenly think it's the closing | for that option.

?{Choose a Roll|
  STR,/roll 1d20 + 3 + (?{Modifier|0}) |
  DEX,/roll 1d20 + 2 + (?{Modifier|0}) |
  CON,/roll 1d20 + 1 + (?{Modifier|0}) }

Advanced Nesting example:

Here you can make choices, where each choice might have suboptions to choose between, which in turn might have their own suboptions.

?{Name of Query|
   Option 1, ?{value1|
      Option 1A, ?{value1A|
         Option 1A1, value1A1 |
         Option 1A2, value1A2
      } |
      
      Option 1B, ?{value1B|
         Option 1B1, value1B1 |
         Option 1B2, value1B2 |
         Option 1B3, value1B3
      }
   } |
   Option 2, ?{value2|value2} 
}

The descision tree goes:

Option1

Option1A

Option1A1

Option1A2

Option1B

Option1B1

Option1B2

Option1B3

Option2

See Advanced Usage for Roll Queries for more examples.

Tooltip

• Tooltips in Text Chat^(Forum)
  • Tooltip Styling^(Forum)

Images

Various ways to use or show images in macros or the chat.

• Pictures and GIFs in Chat and Abilities^(Forum) - Blue64
• Monster Images in Chat^(Forum) - Kirsty
• Using Images as Links^(Forum) - Oosh
• Inserting Images into Macros^(Forum)
• Make gif loop infinitely - Oosh
• Displaying Images Based On Roll Results - Fnux

Hyperlinks

You can have hyperlinks in chat messages, linking to character sheets, handouts, i Compendium, as well as pages outside Roll20.net

• Using Images as Links^(Forum) - Oosh
• Hypertext Macro to Open a Linked Character Sheet Hypertext Macro to Open a Linked Character Sheet^(Forum) - Vince
• link to open a Compendium page from chat^(Forum)

You can also create links to roll other macros, see Chat Menus for more examples

Multi-line

• %NEWLINE% trick + misc.^(Forum) - Andreas J.
• Multiline Chat messages using Triple Brackets^(Forum) - Keith

API

This section 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.

• ScriptCards powerful API to output things to the chat
• PowerCards predecessor to ScriptCards

Stylus

You can use Stylus to change how things look for you, without affecting others. Here are some of the tricks:

• Talk To Myself banner - keithcurtis Install
• Hide Error Messages in Chat - Mike deBoston - install
• Default Roll Template Enhancement - keithcurtis - install
• Blue Dice on /r Rolls and Inline Tooltips - Oosh