Foundry VTT V13 Development Guide

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

Overview

This guide covers V13-specific patterns and migration from earlier versions. For modules targeting V13, follow these guidelines.

When to Use This Skill

• Migrating a module/system from V12 or earlier to V13
• Converting CommonJS (

  require

  ) to ESM (

  import

  /

  export

  )
• Implementing DataModel for structured data
• Updating deprecated patterns (

  actor.data.data

  to

  actor.system

  )
• Fixing hook signature changes after V13 upgrade
• Setting up V13-compatible manifest configuration

Core Architecture Principles

Use DataModel for Structured Data

ALWAYS use

foundry.abstract.DataModel

for defining data structures instead of plain JavaScript objects. DataModels provide:

• Built-in validation and type coercion
• Schema definition with

  DataSchema

• Automatic data preparation lifecycle
• Integration with Foundry's document system

Example:

class MyModuleData extends foundry.abstract.DataModel {
  static defineSchema() {
    const fields = foundry.data.fields;
    return {
      name: new fields.StringField({ required: true, blank: false }),
      value: new fields.NumberField({ initial: 0, min: 0 }),
      enabled: new fields.BooleanField({ initial: true })
    };
  }
}

ESM Modules Only

Foundry V13 uses ECMAScript Modules (ESM) exclusively. Your code must:

• Use

  import

  and

  export

  statements (NO

  require()

  )
• Declare

  "esmodules"

  in your manifest (NOT

  "scripts"

  )
• Use

  .js

  extensions in import paths when importing relative files

Example manifest entry:

{
  "esmodules": ["scripts/module.js"],
  "scripts": []
}

Internationalization (i18n)

ALWAYS use

game.i18n.localize()

or

game.i18n.format()

for user-facing text. Never hardcode English strings.

// BAD
ui.notifications.info("Item created successfully");

// GOOD
ui.notifications.info(game.i18n.localize("MYMODULE.Notifications.ItemCreated"));

// For dynamic values
const message = game.i18n.format("MYMODULE.Notifications.ItemCreatedWithName", {
  name: itemName
});

Localization files go in

lang/en.json

:

{
  "MYMODULE.Notifications.ItemCreated": "Item created successfully",
  "MYMODULE.Notifications.ItemCreatedWithName": "Item {name} created successfully"
}

Common V13 Pitfalls

Hook Arguments Have Changed

Many hooks in V13 have different argument signatures than V12. Always check the current API documentation.

Example:

createToken

Hook

// V12 (OLD - WRONG in V13)
Hooks.on("createToken", (scene, tokenData, options, userId) => { });

// V13 (CORRECT)
Hooks.on("createToken", (tokenDocument, options, userId) => { });

Document vs Data

V13 distinguishes between Document classes (e.g.,

Actor

,

Item

) and their data models:

• Access document properties directly:

  actor.name

  ,

  item.system

• Use

  actor.system

  to access system-specific data defined in your DataModel
• Avoid accessing

  actor.data.data

  (deprecated pattern from V10)

// BAD (V10 pattern)
const hp = actor.data.data.attributes.hp.value;

// GOOD (V13 pattern)
const hp = actor.system.attributes.hp.value;

Active Effects Structure

Active Effects in V13 use a cleaner structure:

• Effects are stored in

  document.effects

  (EffectCollection)
• Use

  await actor.createEmbeddedDocuments("ActiveEffect", [effectData])

• Effect changes use

  key

  (path to property) and

  mode

  (add, multiply, override, etc.)

const effectData = {
  name: game.i18n.localize("MYMODULE.Effects.Blessed"),
  icon: "icons/magic/light/beam-rays-yellow.webp",
  changes: [{
    key: "system.attributes.ac.bonus",
    mode: CONST.ACTIVE_EFFECT_MODES.ADD,
    value: "2"
  }],
  duration: { rounds: 10 }
};

await actor.createEmbeddedDocuments("ActiveEffect", [effectData]);

Canvas Rendering Layers

V13 has reorganized canvas layers. Use the correct layer references:

• canvas.tokens

  - TokenLayer

• canvas.tiles

  - TilesLayer

• canvas.lighting

  - LightingLayer

• canvas.grid

  - GridLayer

Dialog API Updates

Dialog construction now prefers Application V2 patterns in some contexts, but classic Dialogs still work:

new Dialog({
  title: game.i18n.localize("MYMODULE.Dialog.Title"),
  content: `<p>${game.i18n.localize("MYMODULE.Dialog.Content")}</p>`,
  buttons: {
    yes: {
      icon: '<i class="fas fa-check"></i>',
      label: game.i18n.localize("MYMODULE.Dialog.Confirm"),
      callback: () => { /* action */ }
    },
    no: {
      icon: '<i class="fas fa-times"></i>',
      label: game.i18n.localize("MYMODULE.Dialog.Cancel")
    }
  },
  default: "yes"
}).render(true);

Data Field Types Reference

When defining DataModel schemas, use these field types from

foundry.data.fields

:

• StringField

  - Text data

• NumberField

  - Numeric values (integers or floats)

• BooleanField

  - True/false values

• ObjectField

  - Nested objects

• ArrayField

  - Arrays of values

• SchemaField

  - Nested DataModel schema

• HTMLField

  - Sanitized HTML content

• FilePathField

  - File paths (images, sounds, etc.)

• ColorField

  - Color values (hex strings)

• AngleField

  - Angles in degrees

• AlphaField

  - Alpha transparency (0-1)

Best Practices

1. Always await async operations - Most Foundry operations are async
2. Check for user permissions - Use

   game.user.isGM

   or document permission checks
3. Use

   fromUuidSync()

   or

   fromUuid()

   - For reliable document references
4. Leverage Hooks - Don't override core behavior, extend it via hooks
5. Handle errors gracefully - Wrap operations in try/catch and show user-friendly messages
6. Test with multiple users - Permission and rendering issues often appear in multi-user scenarios
7. Follow Foundry's module conventions - Use proper manifest structure, versioning, and compatibility flags

Manifest Requirements

Your

module.json

or

system.json

must declare V13 compatibility:

{
  "id": "my-module",
  "title": "My Module",
  "version": "1.0.0",
  "compatibility": {
    "minimum": "13",
    "verified": "13",
    "maximum": "13"
  },
  "esmodules": ["scripts/init.js"],
  "languages": [
    {
      "lang": "en",
      "name": "English",
      "path": "lang/en.json"
    }
  ]
}

Development Workflow

1. Enable "Developer Mode" in Foundry settings for better error messages
2. Use browser DevTools Console for debugging
3. Use

   console.log()

   liberally, or set up proper logging with

   CONFIG.debug

4. Test in a fresh world to avoid conflicts with other modules
5. Use

   CONFIG.debug.hooks = true

   to see all hook executions

Remember: When in doubt, check the official Foundry VTT V13 API documentation at https://foundryvtt.com/api/

Implementation Checklist

Module Structure

• Manifest declares

  "esmodules"

  (not

  "scripts"

  )
• All imports use ESM syntax with

  .js

  extensions
• Compatibility set to minimum V13

Data Patterns

• DataModel classes define schemas with

  defineSchema()

• Access system data via

  document.system

  (not

  data.data

  )
• Active Effects use correct change structure

Code Quality

• All user-facing strings use

  game.i18n.localize()

• Hook callbacks use V13 argument signatures
• Async operations are properly awaited
• Permissions checked before privileged operations

Testing

• Module loads without console errors
• DataModel validation works correctly
• Hooks fire with expected arguments
• Multi-user scenarios tested

References

• Foundry VTT V13 API
• DataModel API
• Migration Guide
• ESM in Foundry

---

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