Foundry VTT Hooks

Domain: Foundry VTT Module/System Development Status: Production-Ready Last Updated: 2026-01-04

Overview

Foundry VTT uses an event-driven architecture where hooks allow modules to intercept and respond to VTT workflows. Understanding hooks is fundamental to all Foundry development.

When to Use This Skill

Registering event handlers for document changes
Creating module APIs that other packages can consume
Debugging hook execution order
Preventing memory leaks from orphaned hooks
Understanding async limitations in hooks

Core Concepts

Method	Purpose	Cancellable	Persists
`Hooks.on(name, fn)`	Register persistent listener	N/A	Yes
`Hooks.once(name, fn)`	Register one-time listener	N/A	No
`Hooks.call(name, ...args)`	Trigger hook (stoppable)	Yes	N/A
`Hooks.callAll(name, ...args)`	Trigger hook (all run)	No	N/A
`Hooks.off(name, id)`	Unregister by ID	N/A	N/A

Lifecycle Hooks (Execution Order)

These fire once per client connection, in this order:

init → i18nInit → setup → ready

Hook	When	Use For
`init`	Foundry initializing	Register sheets, settings, CONFIG
`i18nInit`	Translations loaded	Localization-dependent setup
`setup`	Before Documents/UI/Canvas	Pre-game state setup
`ready`	Game fully ready	World initialization, game data access

javascript

// Correct registration order
Hooks.once("init", () => {
  // Register settings
  game.settings.register("my-module", "mySetting", { /* ... */ });

  // Register document sheets
  DocumentSheetConfig.registerSheet(Actor, "my-module", MyActorSheet, {
    makeDefault: true
  });
});

Hooks.once("ready", () => {
  // Safe to access game.actors, game.users, etc.
  console.log(`${game.actors.size} actors in world`);
});

Document Hooks

All document types follow this pattern:

Hook	Trigger Method	Can Cancel
`preCreate{Doc}`	`Hooks.call`	Yes
`create{Doc}`	`Hooks.callAll`	No
`preUpdate{Doc}`	`Hooks.call`	Yes
`update{Doc}`	`Hooks.callAll`	No
`preDelete{Doc}`	`Hooks.call`	Yes
`delete{Doc}`	`Hooks.callAll`	No

javascript

// Prevent update if condition met
Hooks.on("preUpdateActor", (actor, change, options, userId) => {
  if (change.system?.hp?.value < 0) {
    ui.notifications.warn("HP cannot be negative");
    return false; // Cancels the update
  }
});

// React after update
Hooks.on("updateActor", (actor, change, options, userId) => {
  if (change.system?.hp?.value === 0) {
    ChatMessage.create({ content: `${actor.name} has fallen!` });
  }
});

Render Hooks

Render hooks fire for the entire inheritance chain:

javascript

// renderActorSheet → renderDocumentSheet → renderFormApplication → renderApplication

// ApplicationV1 signature
Hooks.on("renderActorSheet", (app, html, data) => {
  html.find(".header").append("<button>Custom</button>");
});

// ApplicationV2 signature (V12+)
Hooks.on("renderActorSheetV2", (app, html, context, options) => {
  // html is the rendered element
});

Common Pitfalls

1. Async Functions Cannot Cancel Hooks

CRITICAL: Hooks never await callbacks. Async functions return a Promise, not false.

javascript

// WRONG - Won't prevent the update!
Hooks.on("preUpdateActor", async (actor, change, options, userId) => {
  const allowed = await someAsyncCheck();
  if (!allowed) return false; // Returns Promise, not false!
});

// CORRECT - Synchronous check for cancellation
Hooks.on("preUpdateActor", (actor, change, options, userId) => {
  if (!someCondition) return false; // Actually prevents update
});

2. Memory Leaks from Orphaned Hooks

Hooks keep references to callbacks, preventing garbage collection:

javascript

// BAD - Hook persists after app closes
class MyApp extends Application {
  constructor() {
    super();
    Hooks.on("updateActor", this._onUpdate.bind(this));
  }
}

// GOOD - Store ID and clean up
class MyApp extends Application {
  constructor() {
    super();
    this._hookId = Hooks.on("updateActor", this._onUpdate.bind(this));
  }

  close(options) {
    Hooks.off("updateActor", this._hookId);
    return super.close(options);
  }
}

3. Object Mutation vs Re-assignment

Objects are passed by reference - mutation works, re-assignment doesn't:

javascript

// WORKS - Mutation affects original
Hooks.on("preUpdateActor", (actor, change, options, userId) => {
  change.name = "Modified"; // Changes the actual update
});

// DOESN'T WORK - Re-assignment breaks reference
Hooks.on("preUpdateActor", (actor, change, options, userId) => {
  change = { name: "New" }; // Local variable only!
});

4. Hooks Fire Per-Client

Each client runs hooks independently. Check userId to avoid duplicate actions:

javascript

// BAD - All clients try to create the item
Hooks.on("createActor", (actor, options, userId) => {
  actor.createEmbeddedDocuments("Item", [itemData]);
});

// GOOD - Only triggering client acts
Hooks.on("createActor", (actor, options, userId) => {
  if (userId !== game.user.id) return;
  actor.createEmbeddedDocuments("Item", [itemData]);
});

5. Hook Context (this) Issues

javascript

// WRONG - Can't unregister by function reference
Hooks.on("updateActor", this.onUpdate);
Hooks.off("updateActor", this.onUpdate); // Fails!

// WRONG - bind() creates new function each time
Hooks.on("updateActor", this.onUpdate.bind(this));
Hooks.off("updateActor", this.onUpdate.bind(this)); // Different function!

// CORRECT - Use hook ID
this._hookId = Hooks.on("updateActor", this.onUpdate.bind(this));
Hooks.off("updateActor", this._hookId); // Works

Creating Custom Hooks for Module APIs

Basic Pattern

javascript

// my-module.js
Hooks.once("init", () => {
  const api = {
    registerExtension: (config) => { /* ... */ },
    doAction: (data) => { /* ... */ }
  };

  // Expose API
  game.modules.get("my-module").api = api;

  // Announce readiness
  Hooks.callAll("myModuleReady", api);
});

// Other modules consume it
Hooks.once("myModuleReady", (api) => {
  api.registerExtension({ name: "My Extension" });
});

Allowing Cancellation

javascript

class MySystem {
  static performAction(data) {
    // Allow other modules to prevent action
    const allowed = Hooks.call("myModule.beforeAction", data);
    if (allowed === false) return null;

    const result = this._doWork(data);

    // Notify completion (cannot be cancelled)
    Hooks.callAll("myModule.afterAction", result);

    return result;
  }
}

Naming Convention

Use namespaced names: moduleName.eventName

combatTracker.turnChanged
tokenMagic.effectApplied
myModule.ready

Debugging Hooks

Enable Debug Mode

javascript

// In browser console
CONFIG.debug.hooks = true;

// Toggle macro
CONFIG.debug.hooks = !CONFIG.debug.hooks;
console.warn("Hook debugging:", CONFIG.debug.hooks);

Debug Specific Hook

javascript

// Log arguments for a specific hook once
Hooks.once("updateActor", (...args) => console.log("updateActor args:", args));

Developer Mode Module

Use the Developer Mode module for persistent debug flag management without shipping debug code.

Implementation Checklist

Use Hooks.once for init/setup/ready (not Hooks.on)
Store hook IDs for any persistent hooks
Clean up hooks in close() or destruction methods
Check userId === game.user.id before document operations
Never use async for pre* hooks that need cancellation
Mutate objects, don't re-assign them
Use namespaced names for custom hooks
Use Hooks.call for cancellable events, Hooks.callAll for notifications

Quick Reference: Common Hook Signatures

javascript

// Document hooks
Hooks.on("preCreateActor", (document, data, options, userId) => {});
Hooks.on("createActor", (document, options, userId) => {});
Hooks.on("preUpdateActor", (document, change, options, userId) => {});
Hooks.on("updateActor", (document, change, options, userId) => {});
Hooks.on("preDeleteActor", (document, options, userId) => {});
Hooks.on("deleteActor", (document, options, userId) => {});

// Render hooks (V1)
Hooks.on("renderActorSheet", (app, html, data) => {});

// Render hooks (V2)
Hooks.on("renderActorSheetV2", (app, html, context, options) => {});

// Canvas hooks
Hooks.on("canvasReady", (canvas) => {});
Hooks.on("canvasPan", (canvas, position) => {});

References

Last Updated: 2026-01-04 Status: Production-Ready Maintainer: ImproperSubset

Search AI Tools

fvtt-hooks

Install this agent skill to your Project

SKILL.md

Foundry VTT Hooks

Overview

When to Use This Skill

Core Concepts

Lifecycle Hooks (Execution Order)

Document Hooks

Render Hooks

Common Pitfalls

1. Async Functions Cannot Cancel Hooks

2. Memory Leaks from Orphaned Hooks

3. Object Mutation vs Re-assignment

4. Hooks Fire Per-Client

5. Hook Context (this) Issues

Creating Custom Hooks for Module APIs

Basic Pattern

Allowing Cancellation

Naming Convention

Debugging Hooks

Enable Debug Mode

Debug Specific Hook

Developer Mode Module

Implementation Checklist

Quick Reference: Common Hook Signatures

References