Foundry modules / Documentation

Handouts macros and API

Last checked 2026-10-12

The Handouts API

Handouts puts a small API on its module object. In a script macro, reach it with game.modules.get('handout-forge').api. The module's id is handout-forge, because every saved handout is stored under that name. The object exists from the moment the world starts to load, and it needs the free ShawnsVTTs Library to do anything useful.

FunctionWho can run itWhat it does
openEditor(entryId, actor)GMOpens the editor. Pass null for a new handout, or a Journal entry id to open that handout. The optional second argument is an actor, which attaches the editor to that actor's card.
cards.cardFor(actorId)AnyoneReturns { entryId } for the actor's card, or null if the actor has none.
cards.throwCard(actorId, to)AnyoneThrows the actor's card. to is 'all' or an array of character ids. A GM throws it straight away. A player's call is passed to the GM's client, which allows only their own character's card or a contact's.
cards.replayCard(actorId)AnyoneShows the actor's card to the person who ran it, and nobody else.

Macro: new handout

game.modules.get('handout-forge').api.openEditor(null);

Macro: throw an NPC's card to everyone

game.modules.get('handout-forge').api.cards.throwCard(game.actors.getName('Ines Varga').id, 'all');

The name must match the actor exactly. The card spins onto each player's screen and prints the actor's details.

Macro: show a card to yourself

game.modules.get('handout-forge').api.cards.replayCard(game.actors.getName('Ines Varga').id);

Hook it answers

Handouts answers the hook shawnsvtts-phone.openHandout, which carries a payload of { handoutId }. ShawnsVTTs Phone calls it when a player presses OPEN HANDOUT. Handouts then opens that handout in the viewer. You can call it yourself to show a handout to the person running the macro:

Hooks.callAll('shawnsvtts-phone.openHandout', { handoutId: 'ENTRY_ID' });

Related

Foundry Virtual Tabletop belongs to Foundry Gaming LLC. ShawnsVTTs modules are independent add-ons and are not made, endorsed or supported by Foundry Gaming LLC.