FoundryVTT Modding

Purpose

To guide the development of custom FoundryVTT modules and systems, emphasizing TypeScript configuration, modern build tools (Vite/Rollup), schema structures (module.json), Actor/Item sheet architecture, and hook lifecycles.

When to Use

Use when writing, refactoring, or structuring TypeScript/JavaScript code for FoundryVTT modules or systems, defining manifest metadata, or hooking into Foundry's rendering lifecycle.

TypeScript & Build Configuration

Use @league-of-foundry-developers/foundry-vtt-types for autocomplete and type safety of the game, canvas, and other global variables.
Configure tsconfig.json to target ES2022+ and resolve modules correctly.
Set up vite.config.ts or rollup.config.js to bundle files into a single distribution file under dist/ and copy assets/templates.

Manifest Layout (`module.json` / `system.json`)

Ensure the manifest contains clean references to script entrypoints:

{
  "id": "my-module",
  "title": "My Foundry Module",
  "description": "Custom additions for Homebrew Magic",
  "version": "1.0.0",
  "compatibility": {
    "minimum": "11",
    "verified": "12"
  },
  "esmodules": ["dist/module.mjs"],
  "styles": ["styles/module.css"]
}

Lifecycle Hooks

Standardize hook registrations to keep initialization organized:

init: Register game settings, active effect keys, and customize configuration structures (CONFIG).
setup: Perform setups dependent on settings availability.
ready: Execute scripts that require canvas or database collections to be fully loaded.

Hooks.once("init", () => {
  console.log("Initializing Homebrew Magic Module");
  
  // Register custom sheets
  Actors.registerSheet("homebrew-magic", CustomActorSheet, {
    makeDefault: true
  });
});

2.0 KiB Raw Blame History