On a new Notepad++ installation, you can just copy and overwrite any existing shortcuts.xml file in the %APPDATA%\Notepad++ folder with this one. You’ll need to right-click that last hyperlink and select Save Link As… then paste %APPDATA%\Notepad++ into the folder field at the top and press Enter to save to the NotePad++ folder. This assumes that you installed Notepad++ in normal (non-portable) mode. Click Save and confirm the overwrite.
The new macros will be listed in Notepad++ under Macro on the main menu bar. A key for them will be shown here soon.
Get a load of this:
That is the Roll20 D&D 3.5 spell macro framework in a nutshell. So what does all this gobbledy-gook mean?
I’m glad you asked…
This section introduces a few concepts to make programming these macros at least a little easier. If you want to skip straight ahead to programming
In order to balance the quirks of what Notepad++ considers a hyperlink against the needs of speedy editing, the concept of “grace characters” is introduced here. A grace character aids in the editing or understanding of programming code, particularly when used in the Roll20 macros used for these spells.
Roll20 hyperlinks, like those in Discord, have brackets around the text to be hyperlinked followed immediately by the hyperlink in parentheses, like so: [Hyperlinked text](https://wherethisgoes). Certain punctuation will cause Notepad++ to extend the underlined portion to include the right parenthesis and characters beyond that, so that if the hyperlink is double-clicked in Notepad++ to test it, a 404 error results. A grace space (defined below) just after the underlined portion) prevents this.
Here are the grace characters defined so far:
A pilcrow, Also known as the paragraph mark, is this symbol: ¶. In this text, it is used whenever a carriage return/linefeed is to be used—basically, any place one would press the Enter key while typing text in.
The Hypertext Markup Language (HTML)—the very language used to display the very text you are reading—includes a variety of very useful characters for programming Roll20 macros (and writing web pages in general). All HTML entities begin with an ampersand (&) and end with a semicolon (;). The text inbetween can be a word, abbreviation, or a decimal or hexadecimal code as needed.
Using these entities in Roll20 macros requires a bit of convoluted thinking, as the macro itself will be displayed here in HTML, which means that without a bit of preprocessing, an HTML entity you put in the macro text will be used in displaying the page the macro is shown on and won’t then be available for copying and pasting that code into the macro field when it is added to a character sheet. However, if the ampersand characters are themselves converted to the HTML entity (&), they will show up in the macro instead of being used to display in the macro.
For example, a common way to fake a paragraph indent in these macros is to start the paragraph with four non-breaking spaces. The HTML entity for a non-breaking space is . If a string of those are typed at the beginning of a new paragraph in a {{notes}} field, they will appear in the textbox but won’t be available to actually copy into the macro itself. Converting each ampersand into its own HTML entity, however, allows the entity to display as the code in the textbox so it can be used in the macro itself.
Here is a table of more commonly used HTML entities, starting with the one mentioned in the previous paragraph. These have been “pre-escaped”—that is, the ampersand entities have been preinserted so one can just copy the code and paste it directly into a Roll20 macro. Remember that in Notepad++, Ctrl+E will convert a selected character (or characters) into their HTML entity.
| Entity | Description |
|---|---|
|   | Non-breaking space. Such a space will not be separated automatically by a web page from text coming after it when a web browser displays it. Four of these in a row can be used to fake a paragraph indent in a Roll20 macro, like so:      |
| & | Ampersand. This can be used to display a “&” character without a web browser treating it as the beginning of an HTML entity. In fact, that very code was used to display the ampersand between the quotes in the previous sentence. |
| × | Multiplication symbol. Don’t use an "x" when you mean “×”—it’s sloppy. |
First, copy the Roll20 Spell Macro Framework above into a new Notepad++ file.
In all following steps, change @{casterlevel} to @{arcanecasterlevel} or @{divinecasterlevel} as appropriate. If a spell can be cast by both arcane and divine spellcasters, two separate macros will be needed, one with @{arcanecasterlevel} in place of @{casterlevel} and the other with @{divinecasterlevel} instead. If the spells are of different levels for different classes, separate versions may be needed for those as well if the spells have saving throws. If all cases, replace the SPELL_LEVEL in all @{spelldcSPELL_LEVEL} to match the spell level, which is always 0–9. Delete the grace quote that was in front of SPELL_LEVEL.
Not all of the next three “TEA” lines, {{Target}}, {{Effect}}, or {{Area}} are used, except in rare cases like limited wish, wish, and miracle. A very few spells may combine two of the tags. Still, most of the time, you will delete the two lines not used. In cases where there are caster level dependent effects, see Caster Level Formulae for details on how to include these. Otherwise, paste the text verbatim after the appropriate tag and delete the others.
Remove ¶ from between tags when finished, but not from within {{notes}} tag. The easiest way to do this in Notepad++ is to select everything but {{notes}} and press Ctrl+J, then delete the ¶ between {{notes}} and the previous tag.
The {{notes}} tag is where the bulk of the work on a new Roll20 spell macro is done, and where the most mistakes creep in. It’s where one explains just what happens when the spell is cast. Often, one uses a summary of the descriptive text of the spell (“Omit needless words!”), inserting Roll20 dice calculations and the like as needed.
Have a basket full of {{notes}} notes:
The added attribute, clmod, is present in almost every Roll20 spell macro in Archive Three-Five. It is short for caster level modifier. In D&D 3.5, there are a great many feats, traits, and class abilities that can modify a spell’s caster level, which affects its range, damage (if any), and a host of other things. The clmod attribute is a placeholder for these variables. How it is used depends on the feats or other circumstances in play. Here follows a list of them and how they can be handled.
Granted Domain Powers: These cleric domains have a granted power that increases caster level for particular spells: Chaos, Craft, Creation, Envy, Evil, Good, Gnome, Healing, Illusion, Knowledge, Law, Oracle, Purification, and Summoner. The easiest way to handle them is to copy the spell macros to add a new attribute with a variant of clmod—say, clmod-gp (“gp” for “granted power”) and set that attribute to 1. After that, append “-gp” to any instance of clmod in macros that would be affected by that particular granted power. This can be done right in the text box of the A35 macro just before it is copied (it won’t be saved there), in the macro field of the spell on the Roll20 character sheet, or in a separate text editor.
Spellgifted Trait: The spellgifted trait grants +1 caster level to spells of a selected school of magic and the cost of –1 to the caster level of all other schools. This can be handled by adding another attribute like clmod-sg and setting it to 1, then setting clmod to -1. After that, change clmod to clmod-sg in the macros of spells belonging to the favored school.
Casting spells often mean making choices, because many spells can work in more than one way. In Roll20 macros, these choices are handled by the select function, works in two different ways:
Data Entry: This form of the select function displays a prompt followed by a field to enter a response, in this form:
?{ PROMPT | DEFAULT_VALUE }
PROMPT is the text that tells the user what is being entered. DEFAULT_VALUE is what displays in the following field as the default value.
An interesting behavior of at least this version of the select function is that if one repeats the exact same function with the same PROMPT and DEFAULT_VALUE in more than one place in a macro, it will only ask the question once. This is actually a feature, not a bug, as one can then use the same answer to that prompt in more than one place. See the macros in the water breathing spell as an example.
Dropdown: This form of the select function displays a dropdown box with the choices available to the player. It takes the following form:
?{ PROMPT | ITEM1, RESULT1 | ITEM2, RESULT2 | ITEM3, RESULT3, … }
PROMPT is the text that tells the user what they are choosing from the drop-down box. Each ITEM clause is a text that summarizes that choice in the list box when the select function executes. Each RESULT is the resulting text that is displayed.
It is in the RESULT text where things can go wrong, and quickly.
The select function will break if certain characters are used in the RESULT clauses because those characters are used to control the function. For example, you can’t put a comma directly in a RESULT clause because the select function uses that in the command to separate the ITEM and RESULT clauses. Likewise, you can’t use curly braces (“{}”) or bar characters (“|”) because the select function uses those as well.
There is, of course, a workaround.
You can convert those characters within RESULT clauses to HTML entities, and they will display as the proper characters when the ?{} function executes. For example, you can replace the comma (,) with the , entity. The examples below illustrate this.
Broken Example:
?{Right Choice, This is the right choice! | Wrong Choice, This choice is wrong, wrong, WRONG!}
When executed, the function will see the first comma in “This choice is wrong, wrong, WRONG!” and truncate the rest of the text. The correct version is this:
Corrected Example:
?{Right Choice, This is the right choice! | Wrong Choice, This choice is wrong, wrong, WRONG!}
Notepad++ uses Ctrl+E to convert a selected character or characters into the appropriate HTML entities so you don’t have to remember or type them.