API and Hooks

Peddler exposes a small API for macros and other modules, and fires namespaced hooks at every significant point in a shopping session.

Getting the API

The same object is available two ways once the module is ready:

const api = game.modules.get('peddler').api;
// or
const api = globalThis.Peddler;

The API is assigned during the Foundry ready hook. The peddler.ready hook fires immediately after assignment and receives the API object, so it is the safe entry point for integrations.

Method reference

Member	Signature	Notes
version	getter	Returns the installed module version string, or null.
openShop	openShop({ shopUuid, userId } = {})	Async. Opens the vignette for the given shop actor UUID. userId defaults to the current user. Returns the vignette application, or null if entry was refused.
openQueuePanel	openQueuePanel(shopActor)	GM only. Opens the queue panel for a shop actor. Returns the panel, or null.
setupShop	setupShop(actor, archetypeId = null)	Async, GM only. Converts an actor into a shop, creates its dialogue journal, and returns the created journal page. Pass null for a blank tree.
archetypes	getter	Returns the array of valid archetype id strings for setupShop. See Shop Archetypes.
openTreeEditor	openTreeEditor(page)	Opens the Dialogue Tree Editor for a journal entry page. Brings an existing editor for that page to front.
notify	notify(message, { type, timeout, permanent, anchor } = {})	Shows a Peddler-styled toast and returns { dismiss }. Shorthands: notify.info, notify.success, notify.warn, notify.error.

Hook reference

All hook names are prefixed with peddler.. Payloads are a single object argument unless noted.

Hook	Fires when	Payload
peddler.ready	The module API has been assigned.	The API object itself.
peddler.preOpenShop	Before a vignette opens. Return false from a listener to cancel the open.	{ shopActor, userId }
peddler.openShop	The vignette is created, before its first render.	{ shopActor, userId, sessionId }
peddler.sessionStart	The vignette has rendered and the session is live.	{ session }
peddler.nodeEnter	The walker enters a node.	{ session, node }
peddler.nodeExit	The walker leaves a node through a choice.	{ session, node, choice }
peddler.choiceMade	The player picks a choice, including free-text matches.	{ session, choice }
peddler.trade	A trade commits successfully.	{ shopActor, buyerActor, summary }
peddler.tradeRollback	A trade fails mid-commit and its document changes are undone.	{ shopActor, buyerActor, reason }
peddler.sessionEnd	The session ends.	{ session, reason }
peddler.shopOpened	World time advances past a scheduled shop’s opening hour. GM client only.	{ actor, time }
peddler.restock	A shop restock cycle completes. GM client only.	{ actor, restocked, added, refilled, deleted }

peddler.preTrade exists in the module’s hook constants but has no call site, so listeners on it never fire.

Session hooks fire on the shopping player’s client. Trades commit on the GM client over Foundry’s query system, so peddler.trade and peddler.tradeRollback fire on the committing client. Treat these two hooks as the trade integration point; the underlying socket queries are internal and not public API.

The trade summary is { added, sold, total, currency }, where added and sold are arrays of { name, qty, uuid } rows.

A choice in the Dialogue Tree Editor can also fire a custom hook under the peddler. prefix through its effect list, with an author-defined payload.

Trade outcomes

Transaction nodes resolve to one of four outcome strings:

• success
• insufficient_funds
• out_of_stock
• cancelled

The tree routes on the outcome. When a Transaction node has no dedicated choice for insufficient_funds or out_of_stock, the walker falls back to its cancelled choice.

System and theme integration

System support ships inside the module; there is no adapter registration API. See System Adapters for what each system integration covers.

When the 3DS Atlas module is active, Peddler registers itself for shared theming. See Themes and Chassis.