Macros are an exciting part of any virtual tabletop.  In Foundry Virtual Tabletop, you will find that macros are as versatile, powerful, and simple as you want them to be.  With the right macros, you can speed up your game, automate the unwieldy, and even do things that would normally require modding.  And best of all, macros are easily shared among users, allowing you to pick and choose your own tailored experience in Foundry Virtual Tabletop!

What Are Macros?

Macros are pre-written commands in Foundry Virtual Tabletop that when used, execute their commands. Macros can be created and accessed through the macro toolbar located on the bottom of the Foundry window.

There are two types of macros in Foundry Virtual Tabletop: chat macros and script macros.

Chat macros are, as indicated by the name, macros that will utilize chat when executed. They are simpler to create, but do not have the wide range of capabilities that a script macro can execute. A chat macro can involve a simple dice command like /r d100 pinging an item card in chat, or displaying pre-written text or HTML content. For more details on chat syntax, see the Knowledge Base article on Chat Messages.

Script macros are more complicated, but powerful commands that can interact with the Foundry JavaScript API to do many things. For example, script macros could automatically consume character resources, roll dice checks, toggle conditions, or change Token appearance. Users can perform any task using a script macro that their User role and permissions settings allow for them to take. Script Macros are written in JavaScript and require some basic scripting knowledge to implement.

As script macros are more powerful than chat macros, a Gamemaster can choose to disable script macros for players via the permissions system, which is found in the Configure Settings menu under the Game Settings tab.


The Macros UI

The Macro Hotbar is located at the bottom of the game interface. See the legend below for explanations of each element.

Above is a labeled diagram for the macro bar. They are as follows:

  1. This is where macros are kept on the macro bar.  New macros can be created by clicking on an empty slot and typing them out, or by dragging an item from an actor sheet to an empty macro bar space.  

  2. This button allows the user to cycle through their various macros.  Users can have five macro bars, or 50 macros on quick-access.

  3. This arrow allows the user to toggle showing/hiding the macro bar.

  4. This folder contains the macro directory, showing all the macros that the user has permission to view.  For most players, it will only display their own macros, while it will display all macros currently in the game to the GM.


Creating, Using, and Sharing Macros

Macros can be created by clicking on an empty slot in the macro bar, and typing out the relevant information.  Chat macros work the same as typing a message in chat. For more information on chat syntax and the possible actions a user can do within chat, see here.

Chat macros can also be created by dragging and dropping an item from the actor sheet to the Hotbar. For the item chat macro to work, an actor who owns this item must be selected on the canvas.

Finally, if there exists a macro compendium accessible in the game, any user with access to the compendium can drag macros from the compendium to their macro bar, though they will need user permissions in the game in order to use script macros.

Executing Macros

Macros can be used by clicking on them in the macro bar, or by pressing the number they are labelled in the macro bar. You can also execute a macro from it's configuration sheet by pressing the Execute button at the bottom.

Sharing Macros

Macros can be shared in several different ways in Foundry Virtual Tabletop. The easiest method is to copy and paste the macro text. This is as simple as sharing it on Discord, hosting it on a text-pasting website, or putting it in a macro repository- the community wiki has one hosted here.

In the Macros Directory, a single Macro can be exported to a JSON file and re-imported in a different World. Lastly, Macros can also be stored in a compendium, which can be shared among users via a Module.