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 use of Add-on Modules. Best of all, macros are easily shared among users, allowing you to pick and choose your own tailored experience in Foundry Virtual Tabletop!

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. This article will introduce you to two types of macros:

Chat Macros
Simple and easy to use, chat macros post pre-defined chat messages to the chat log when executed. All users can execute chat macros by default.
Script Macros
Complex and powerful macros which leverage the FVTT API through plain JavaScript to perform functions as simple or as advanced as you can imagine.

The Macros UI

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

The sections of the macro bar are as follows:

Macro Directory
Provides access to all macros that have been created which you have permission to view, use, or edit.
Macro Hotbar
Gives instant keypress access to 10 quick Macros, which can be used to send chat messages or perform scripted API actions. Primarily used by advanced users. Some systems provide the ability to drop items or actors onto the macro bar to generate a macro for quick use.
Macro Pages
The macro pages control allows you to switch between up to four different pages of macro layouts for convenience.

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. If your Game System supports it, macros can also be created by dragging and dropping an item from an actor sheet to the Hotbar. In addition, existing macros stored in a compendium or in the Macros Directory can be dragged to the macro hotbar for convenience.

Executing Macros

Macros can be used by clicking on them in the macro bar, or by pressing the corresponding number key on your keyboard. You can also execute a macro from its configuration window 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.

Creating Chat 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 1d100 linking an entity in chat@Entity["Entity Name Here"], or displaying pre-written text or an image using HTML tags.

Chat macros work the same as typing a message in chat, and anything you can type into the chat entry field can be entered here.For more information on chat syntax and the possible actions a user can do within the chat entry field, see Chat Messages

Example Chat Macros

/r 1d6#which of my players is the next victim?
/roll {4d6kh3, 4d6kh3, 4d6kh3, 4d6kh3, 4d6kh3, 4d6kh3}#Rolling for DND5e Ability Scores. Don't forget to click to expand the message!
There once was a ship that put to sea,
and the name of the ship was the <b>Billy o' Tea!</b>
The winds blew hard, her bow dipped down
Blow, me bully boys, blow!</em>
<h2>Foundry VTT is AWESOME!</h2>
<img src="" width="100%"/>

What Are Macros?

Script macros are more complicated, but powerful commands that can interact with the Foundry JavaScript API. Script macros are limited only by your imagination and the functions available to JavaScript. Users can perform any task using a script macro that their User role and permissions settings allow for them to take. For example, script macros could automatically consume character resources, roll dice checks, toggle conditions, or change Token appearance.

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.

Example script macros

Scene Wall and Light Duplicator

const source = game.scenes.getName("BASEMAP NAME HERE");

Emergency Campaign Resolver

//Rocks Fall, everyone dies.

let targets = []
game.user.targets.forEach(i => {
let name =;

if(targets.length === 0) {targets = "no one, this time"}

let roll = new Roll(`8d10+100`).roll();

let results_html = `<h2>Cave In!</h2>
The cave collapses from above, dealing ${} damage to ${targets}.`

user: game.user._id,
speaker: ChatMessage.getSpeaker({token: actor}),
content: results_html

API References

While anything within the Foundry VTT API can be used within a Macro, to interact with Macros themselves, you will primarily use the following API concepts: