Macro Commands

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 Hotbar

The 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. The macro hotbar has four macro pages that users can switch between, giving them up to four different pages of macro layouts for convenience. These can be cycled by using the up and down indicators on the right of the macro bar ( and ).

Macro Directory

The Macro Directory ( ) provides access to all macros that have been created which you have permission to view, use, or edit. From inside this directory you can create new macros by clicking the Create Macro button, which will open the macro creation dialog, allowing you to set a name and select the type of macro you want to create.

You can also use the Create Folder button to create a folder in this directory. Macros can be dragged to and from folders to organize macros as desired. Clicking the Create Macro icon ( ) on the folder itself will open the macro creation dialog, allowing you to create a new macro that will automatically be placed into that folder.

Folders can be edited by right clicking them and selecting "Edit Folder," the resulting dialog allows you to set the name and color of the folder as you see fit. You can also configure the permissions of the folder to decide what level of user can see and use the macros within. This uses the same permission guidelines found in the Users and Permissions article. You can also export all the macros in a folder to an unlocked compendium, create a new rolltable with the macros in the folder as the possible results, remove the folder (this places the macros back into the directory itself), or delete the folder and all items within it.

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 a document in chat@Document["Document 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 = await new Roll(`8d10+100`).roll();

let results_html = `<h2>Cave In!</h2>
The cave collapses from above, dealing <a class="inline-result"><i class="fas fa-dice-d20"></i>${}</a> damage to <strong>${targets}</strong>.`

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: