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.
| Function | Who can run it | What it does |
|---|---|---|
| openEditor(entryId, actor) | GM | Opens 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) | Anyone | Returns { entryId } for the actor's card, or null if the actor has none. |
| cards.throwCard(actorId, to) | Anyone | Throws 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) | Anyone | Shows 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
- Macros and the phone API for the Phone's side
- Cards for NPCs
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.