Foundry Vtt System Dev

Foundry VTT System Development

Build game systems for Foundry Virtual Tabletop (v14+). Systems define the core rules — Actor/Item types, dice mechanics, combat, character sheets — while modules extend them. This skill covers the full system lifecycle from manifest to publication. v13→v14 differences appear as "Changed in v14" notes; for the full list read foundry-vtt-module-dev/references/v14-migration.md.

This skill depends on foundry-vtt-module-dev for the shared references it points at (v14-migration.md, active-effects-v2.md, scene-levels.md, measured-templates.md) — install both.

Quick Start

System Structure

my-system/
├── system.json           ← manifest (required) — declares types via documentTypes
├── template.json         ← legacy type defaults (optional, deprecated since v14, removed in v16)
├── scripts/
│   ├── main.mjs          ← ES module entry point
│   ├── actor.mjs         ← custom Actor class
│   ├── item.mjs          ← custom Item class
│   ├── data/
│   │   ├── character-data.mjs
│   │   └── npc-data.mjs
│   └── sheets/
│       └── character-sheet.mjs
├── templates/
│   └── actor/
│       └── character-sheet.hbs
├── styles/
│   └── my-system.css
├── packs/                ← compendium data
└── lang/
    └── en.json           ← localization strings

Use boilerplate/system.json and boilerplate/main.mjs as starting points.

Manifest Example (system.json)

Every system needs a valid system.json. System-specific fields beyond what modules use:

{
  "id": "my-system",
  "type": "system",
  "title": "My System",
  "description": "A custom game system for Foundry VTT.",
  "version": "1.0.0",
  "compatibility": {
    "minimum": "14",
    "verified": "14"
  },
  "documentTypes": {
    "Actor": { "character": {}, "npc": {} },
    "Item": { "weapon": {}, "spell": {} }
  },
  "authors": [{ "name": "Your Name" }],
  "esmodules": ["scripts/main.mjs"],
  "styles": [{ "src": "styles/my-system.css" }],
  "languages": [{ "lang": "en", "name": "English", "path": "lang/en.json" }],
  "background": "systems/my-system/assets/setup-bg.png",
  "grid": { "type": 1, "distance": 5, "units": "ft", "diagonals": 0 },
  "primaryTokenAttribute": "health",
  "secondaryTokenAttribute": "power"
}

Field-by-field notes are in System Manifest (system.json) below; references/system-manifest.md has the full schema.

Type Declaration Example

Declare every subtype in system.json under documentTypes, then give each one a TypeDataModel. The manifest declares the type; defineSchema() supplies the fields, defaults, validation, and derived data:

{
  "documentTypes": {
    "Actor": {
      "character": { "htmlFields": ["biography"] },
      "npc": {}
    },
    "Item": {
      "weapon": { "htmlFields": ["description"] },
      "spell": { "htmlFields": ["description"] }
    }
  }
}

// scripts/data/weapon-data.mjs
export class WeaponData extends foundry.abstract.TypeDataModel {
  static defineSchema() {
    const fields = foundry.data.fields;
    return {
      description: new fields.HTMLField({ initial: "" }),
      damage: new fields.StringField({ initial: "1d6" }),
      quantity: new fields.NumberField({ required: true, integer: true, min: 0, initial: 1 })
    };
  }
}
// init: Object.assign(CONFIG.Item.dataModels, { weapon: WeaponData });

Shared fields go in a base class (class BaseItemData extends TypeDataModel) that subtypes extend — that replaces template.json's templates inheritance.

Changed in v14: template.json is deprecated (removed in v16). See Declaring Types → Legacy: template.json below before keeping one.

Initialization Lifecycle

Systems run through the same hooks as modules, but the init hook is where you register core system components:

const SYSTEM_ID = "my-system";

Hooks.once("init", () => {
  // Register data models for each type
  Object.assign(CONFIG.Actor.dataModels, {
    character: CharacterData,
    npc: NpcData
  });
  Object.assign(CONFIG.Item.dataModels, {
    weapon: WeaponData,
    spell: SpellData
  });

  // Register custom document classes
  CONFIG.Actor.documentClass = MySystemActor;
  CONFIG.Item.documentClass = MySystemItem;

  // Set initiative formula
  CONFIG.Combat.initiative = {
    formula: "1d20 + @abilities.dex.mod",
    decimals: 2
  };

  // Register system sheets. Core registers no default Actor/Item sheet,
  // so there is nothing to unregister first.
  foundry.documents.collections.Actors.registerSheet(SYSTEM_ID, CharacterSheet, {
    makeDefault: true,
    types: ["character"]
  });

  // Register settings
  game.settings.register(SYSTEM_ID, "schemaVersion", {
    scope: "world",
    config: false,
    type: Number,
    default: 0
  });
});

Changed in v14: CONFIG.ActiveEffect.legacyTransferral no longer exists — delete the line. Effects on owned Items with transfer: true apply to the Actor in place through Actor#allApplicableEffects(); nothing is copied onto the Actor. If you still need the AppV1 sheet class for a fallback, it lives at foundry.appv1.sheets.ActorSheet (deprecated since v13, removed in v16).

Shared API — see the foundry-vtt-module-dev skill for Hooks lifecycle (init/setup/ready), Settings API, and Localization.

Namespaces (foundry.*)

Nearly every core API moved into the foundry.* namespace in v13. In v14 the legacy globals are deprecation shims scheduled for removal in v15 (most) or v16 (the AppV1 framework); the bare foundry.utils globals (mergeObject, getProperty, ...) and the dice-term globals (Die, DiceTerm, ...) are already gone. Write against the namespaced paths:

For the full table, see the foundry-vtt-module-dev skill's "Namespaces" section. The same migration applies — write new files against namespaced paths, update old files when you touch them.

Production Architecture

Patterns every shipping system uses, extracted from the foundryvtt/dnd5e reference implementation. Adopt these before your codebase grows past ~10 source files:

• Single ESM entry + barrel files — one my-system.mjs declared in system.json; each subdirectory exports a _module.mjs re-exporting its public API. The entry imports namespaces (import * as dataModels from "./data/_module.mjs").
• globalThis.<systemId> API surface — expose your system API on one global so modules and macros have a stable contract (game.mySystem.documents.MySystemActor).
• flags.hotReload in system.json — declare which file types Foundry should live-reload (CSS, hbs, JSON). Cuts UI iteration time dramatically.
• htmlFields and filePathFields per documentType — required for proper sanitization, ProseMirror enrichment, asset migration, and search indexing.
• Migration version flags — flags.<systemId>.needsMigrationVersion + compatibleMigrationVersion in system.json, gated by Hooks.once("ready") + game.user.isGM.
• Single frozen config.mjs — all static system data (abilities, damage types, schools) in one file, assigned to CONFIG.MY_SYSTEM in init. One source of truth.
• Staged init hooks — split work across init (CONFIG mutations, sheets, settings) → i18nInit (translate CONFIG labels) → setup (enrichers, packs) → ready (migrations, GM-only side effects).
• Pack folders — group compendium packs hierarchically in the sidebar via packFolders in system.json.
• Build pipeline — Rollup ESM bundle + LESS/Sass + @foundryvtt/foundryvtt-cli for LevelDB pack compilation.

The updated boilerplate/system.json and boilerplate/main.mjs demonstrate the namespace, hotReload, htmlFields, packFolders, migration flags, and staged-hook patterns end-to-end.

For the full rationale, dnd5e references, and concrete templates, read references/production-patterns.md.

System Manifest (system.json)

Manifest fields a system needs (system-only fields plus the shared ones that matter here):

The primaryTokenAttribute and secondaryTokenAttribute reference keys in actor.system. The attribute must lead to an object with value and max keys (e.g., system.health.value / system.health.max).

For full details, read references/system-manifest.md.

Declaring Types

The v14 way has two parts, and both are required for every subtype:

1. documentTypes in system.json — the declaration. Any document with hasTypeData (Actor, Item, JournalEntryPage, Cards, Card, ChatMessage, Combat, Combatant, RegionBehavior, ActiveEffect, ...) accepts subtypes. Core type names (base, text, image, ...) are reserved and throw.
2. TypeDataModel in CONFIG.<Document>.dataModels — the schema. Field defaults come from initial, shared fields from class inheritance, validation from field options, derived values from prepareDerivedData().

Hooks.once("init", () => {
  Object.assign(CONFIG.Actor.dataModels, { character: CharacterData, npc: NpcData });
  Object.assign(CONFIG.Item.dataModels, { weapon: WeaponData, spell: SpellData });
});

Legacy: template.json (deprecated since v14, removed in v16)

template.json still loads. For every type it lists, the server resets that type's documentTypes entry to {} and copies back only the document-level htmlFields, filePathFields and gmOnlyFields — so the type name survives but its per-subtype declarations in system.json are dropped while the file exists. Its default data lands in game.model and is used only for types that have no registered TypeDataModel (a data model wins outright). strictDataCleaning still applies to that fallback path. The server logs a warning on every start while the file exists.

Migration path for an existing system:

• Move each template's default values into initial options on the matching TypeDataModel fields; shared templates become a base class.
• Move each type name into documentTypes in system.json. Leave htmlFields / filePathFields / gmOnlyFields in template.json's document-level block for now — while the file exists the server resets each listed type's entry and copies only that block back, so subtype declarations would be wiped on every start.
• Delete template.json, then put htmlFields / filePathFields / gmOnlyFields on the subtype objects. Stored documents keep their data; run migrateData() only where field paths changed.

For full details, read references/system-manifest.md.

Actor & Item Classes

Systems replace the default Actor and Item classes with custom subclasses:

// In init hook
CONFIG.Actor.documentClass = MySystemActor;
CONFIG.Item.documentClass = MySystemItem;

Actor: getRollData()

Override getRollData() to expose system data for roll formulas (@abilities.str.mod):

class MySystemActor extends Actor {
  getRollData() {
    const data = super.getRollData();
    // Add shorthand for abilities
    data.abilities = this.system.abilities;
    data.level = this.system.level;
    return data;
  }
}

Actor: _preCreate() for Default Items

Add starter items when an Actor is created:

async _preCreate(data, options, user) {
  await super._preCreate(data, options, user);
  const items = this.items.map(i => i.toObject());
  items.push({ name: "Unarmed Strike", type: "weapon", system: { damage: "1" } });
  this.updateSource({ items });
}

Item: roll()

Implement system-specific roll logic:

class MySystemItem extends Item {
  async roll({ messageMode } = {}) {
    const rollData = this.getRollData();
    const roll = new foundry.dice.Roll(this.system.formula, rollData);
    await roll.evaluate();
    await roll.toMessage({
      speaker: ChatMessage.getSpeaker({ actor: this.actor }),
      flavor: `${this.name} — ${this.type}`
    }, { messageMode }); // undefined → the user's core.messageMode setting
  }
}

Changed in v14: the rollMode option of Roll#toMessage / ChatMessage.create is deprecated (until v16) in favour of messageMode, a key of CONFIG.ChatMessage.modes (public, gm, blind, self, ic). Map an old value with foundry.dice.Roll._mapLegacyRollMode(rollMode); read the user default from game.settings.get("core", "messageMode").

TypeDataModel & defineSchema

Each Actor/Item type needs a TypeDataModel class that defines its data schema:

class CharacterData extends foundry.abstract.TypeDataModel {
  static defineSchema() {
    const fields = foundry.data.fields;
    return {
      level: new fields.NumberField({ required: true, integer: true, min: 1, max: 20, initial: 1 }),
      abilities: new fields.SchemaField({
        str: new fields.NumberField({ required: true, integer: true, min: 1, max: 20, initial: 10 }),
        dex: new fields.NumberField({ required: true, integer: true, min: 1, max: 20, initial: 10 })
      }),
      health: new fields.SchemaField({
        value: new fields.NumberField({ required: true, integer: true, min: 0, initial: 10 }),
        max: new fields.NumberField({ required: true, integer: true, min: 0, initial: 10 })
      }),
      biography: new fields.HTMLField({ initial: "" })
    };
  }
}

Register in init with Object.assign(CONFIG.Actor.dataModels, { character: CharacterData }).

prepareDerivedData()

Override on TypeDataModel to compute derived values (modifiers, max HP, AC). Use helper methods per type to stay organized:

class CharacterData extends foundry.abstract.TypeDataModel {
  prepareDerivedData() {
    this._prepareAbilities();
    this._prepareHealth();
  }

  _prepareAbilities() {
    for (const [key, score] of Object.entries(this.abilities)) {
      this.abilities[key] = { score, mod: Math.floor((score - 10) / 2) };
    }
  }

  _prepareHealth() {
    const conMod = this.abilities.con?.mod ?? 0;
    this.health.max = 10 + this.level + conMod;
  }
}

Never write to the database in prepareDerivedData() — it is purely in-memory computation.

Sheet Registration

System sheets use ActorSheetV2 / ItemSheetV2 with HandlebarsApplicationMixin:

const { HandlebarsApplicationMixin } = foundry.applications.api;

class CharacterSheet extends HandlebarsApplicationMixin(foundry.applications.sheets.ActorSheetV2) {
  static PARTS = {
    header: { template: "systems/my-system/templates/actor/header.hbs" },
    body:   { template: "systems/my-system/templates/actor/body.hbs" }
  };

  async _prepareContext(options) {
    return { actor: this.document, system: this.document.system };
  }
}

Shared API — see the foundry-vtt-module-dev skill for ApplicationV2, Active Effects, and Hooks lifecycle.

For full details, read references/actor-item-classes.md.

Dice System

Custom DiceTerm

Extend foundry.dice.terms.Die for custom mechanics (e.g., exploding dice):

class ExplodingDie extends foundry.dice.terms.Die {
  async _evaluate(options = {}) {
    await super._evaluate(options);
    for (const result of [...this.results]) {
      if (result.result >= this.faces) {
        const bonus = new foundry.dice.terms.Die({ number: 1, faces: this.faces });
        await bonus._evaluate();
        this.results.push(...bonus.results);
      }
    }
    return this;
  }
}

// Register in init
CONFIG.Dice.terms["x"] = ExplodingDie;
// Usage: "2x6" → 2d6, exploding on max

Custom Roll Class

Extend foundry.dice.Roll for system-specific behavior:

class MySystemRoll extends foundry.dice.Roll {
  static instantiateAST(ast) {
    // Custom AST processing for system-specific terms
    return CONFIG.Dice.parser.flattenTree(ast).map(node => {
      const cls = foundry.dice.terms[node.class] ?? foundry.dice.terms.RollTerm;
      return cls.fromParseNode(node);
    });
  }
}

// Register in init
CONFIG.Dice.rolls = [MySystemRoll];

Sending Rolls to Chat

Roll#toMessage(messageData, { messageMode, create }) posts the roll. messageMode is a key of CONFIG.ChatMessage.modes; leave it undefined to honour the user's core.messageMode setting. Blind rolls ("blind") skip interactive dice fulfillment. Chat commands (/gmroll, /blindroll, ...) are defined in foundry.applications.sidebar.tabs.ChatLog.CHAT_COMMANDS; add a system command there, not in the deprecated MESSAGE_PATTERNS.

Changed in v14: CONFIG.Dice.rollModes and CONST.DICE_ROLL_MODES are deprecation proxies over CONFIG.ChatMessage.modes. A system that offered its own roll-mode selector should iterate CONFIG.ChatMessage.modes and pass the chosen key as messageMode.

For full details, read references/dice-system.md.

Combat & Initiative

Global Initiative Formula

// In init hook
CONFIG.Combat.initiative = {
  formula: "1d20 + @abilities.dex.mod + @abilities.wis.mod",
  decimals: 2
};

The formula uses roll data from the combatant's actor. @abilities.dex.mod resolves via getRollData(). When the CONFIG formula is empty, Combatant#_getInitiativeFormula() falls back to the manifest's initiative field.

Combat#rollInitiative(ids, { formula, updateTurn, messageMode, messageOptions }) posts one chat message per combatant. Hidden combatants roll with messageMode: "gm" unless you pass a mode.

Changed in v14:

• messageOptions.rollMode → top-level messageMode (deprecated until v16).
• Combat#getCombatantByActor / getCombatantByToken → getCombatantsByActor(actor) / getCombatantsByToken(token), which return arrays (deprecated until v15).
• Combat has a name field (editable from the tracker header); Combatant has roundJoined (the round it entered, initial 1).
• Active Effect expiry is driven by the combat lifecycle: Combat calls ActiveEffect.registry.refresh(event, { combat }) for combatStart, roundStart, turnStart, turnEnd, roundEnd, combatEnd (the values of CONST.ACTIVE_EFFECT_EXPIRY_EVENTS), plus combatRewind and updateWorldTime. An effect's duration.expiry names the event that ends it (default "turnStart" for numeric durations); CONFIG.ActiveEffect.expiryAction ("update" sets duration.expired, "delete" removes the effect, null does nothing) decides what happens. A system with its own timing (e.g. "end of the scene") registers a label in CONFIG.ActiveEffect.expiryEvents and calls ActiveEffect.registry.refresh("myEvent", context) itself.

Per-Actor Initiative

Override getInitiativeRoll() on a custom Combatant for per-actor formulas:

const original = Combatant.prototype.getInitiativeRoll;
Combatant.prototype.getInitiativeRoll = function (formula) {
  if (this.actor?.type === "character") {
    formula = "1d20 + @abilities.dex.mod";
  } else if (this.actor?.type === "npc") {
    formula = "1d10 + @abilities.dex.mod";
  }
  return original.call(this, formula);
};

For safer patching, use libWrapper:

libWrapper.register("my-system", "Combatant.prototype.getInitiativeRoll", function (wrapped, formula) {
  if (this.actor?.type === "character") formula = "1d20 + @abilities.dex.mod";
  return wrapped(formula);
}, "WRAPPER");

Shared API — see the foundry-vtt-module-dev skill for combat hooks (combatStart, combatTurn, combatRound) and Token HUD.

For full details, read references/combat-initiative.md.

Data Migration

Schema Versioning

Track the current schema version in settings and run migrations on world load:

const MIGRATIONS = [
  { version: 1, fn: migrateV1 },
  { version: 2, fn: migrateV2 }
];

Hooks.once("ready", async () => {
  if (!game.user.isGM) return;
  const current = game.settings.get("my-system", "schemaVersion") ?? 0;
  const target = MIGRATIONS.at(-1).version;
  if (current >= target) return;

  for (const { version, fn } of MIGRATIONS) {
    if (current < version) await fn();
  }
  await game.settings.set("my-system", "schemaVersion", target);
  ui.notifications.info("my-system | Migration complete.");
});

migrateData() on TypeDataModel

static migrateData(source, options) runs on the raw system object every time a document is constructed, before validation. Rename fields and transform values here. It must return the data — v14 warns (until v16) on implementations that return nothing:

class CharacterData extends foundry.abstract.TypeDataModel {
  static migrateData(source, options) {
    // Field rename: hp → health
    if ( "hp" in source && !("health" in source) ) {
      source.health = source.hp;
      delete source.hp;
    }
    // Value transform: string level → number
    if ( typeof source.level === "string" ) source.level = Number(source.level) || 1;
    return super.migrateData(source, options);
  }
}

Field-level migration: DataField#_migrate(value, options, _state) replaces migrateSource (deprecated until v16). Override it on a custom field to migrate that field's value wherever the field is used.

Update Operators

Deleting or replacing keys in an update() uses data operators. The -=key / ==key special keys still work but warn (deprecated until v16):

// Delete a key
await actor.update({ "system.legacy": _del });                    // global alias
await actor.update({ "system.legacy": new foundry.data.operators.ForcedDeletion() });

// Replace an object wholesale instead of merging into it
await actor.update({ "system.abilities": _replace({ str: 10 }) }); // global alias of ForcedReplacement.create

foundry.utils.mergeObject(..., { applyOperators }) replaces { performDeletions }; foundry.utils.objectsEqual → foundry.utils.equals.

template.json → TypeDataModel

Moving a type off template.json changes no stored data — the system object keeps its keys. Give the TypeDataModel the same field paths and the documents load unchanged. Only a path rename needs migrateData(). Unknown keys are dropped on the next save unless a field declares them, so audit each template key against defineSchema() before deleting the file.

For full details, read references/data-migration.md.

Character Creation

Default Items in _preCreate()

Add starter items when an Actor is created:

async _preCreate(data, options, user) {
  await super._preCreate(data, options, user);
  const starterItems = [
    { name: "Unarmed Strike", type: "weapon", system: { damage: "1" } },
    { name: "Basic Spell", type: "spell", system: { level: 0 } }
  ];
  this.updateSource({ items: starterItems });
}

Prototype Token Defaults

Set default token properties in _preCreate():

this.updateSource({
  "prototypeToken.texture.src": this.parent.img,
  "prototypeToken.name": this.parent.name,
  "prototypeToken.displayName": CONST.TOKEN_DISPLAY_MODES.OWNER_HOVER,
  "prototypeToken.displayBars": CONST.TOKEN_DISPLAY_MODES.OWNER,
  "prototypeToken.bar1": { attribute: "health" },
  "prototypeToken.bar2": { attribute: "power" },
  "prototypeToken.disposition": CONST.TOKEN_DISPOSITIONS.FRIENDLY,
  "prototypeToken.sight": { enabled: true, range: 60 }
});

Changed in v14: PrototypeToken uses an allow-list of Token fields: name, displayName, actorLink, width, height, depth, texture, lockRotation, rotation, alpha, disposition, displayBars, bar1, bar2, light, sight, detectionModes, occludable, ring, turnMarker, movementAction, flags, plus randomImg, appendNumber, prependAdjective. depth is new. level and elevation are not prototype fields — a Token gets those when it is placed on a Scene. Writing them in _preCreate() does nothing.

A GM can also set per-type prototype defaults in the world (PrototypeTokenOverrides, stored in the core.prototypeTokenOverrides setting). Those overrides apply on top of your _preCreate() values for sight.enabled, ring.enabled, turnMarker, displayName, displayBars, disposition, and lockRotation.

Shared API — see the foundry-vtt-module-dev skill for DialogV2, Active Effects, and compendium import.

For full details, read references/character-creation.md.

Advanced System Features

Status Effects

Add system-specific conditions in init, keyed by id, and delete the core ones the system replaces:

CONFIG.statusEffects["my-system.prone"] = {
  id: "my-system.prone",
  name: "MY_SYSTEM.Conditions.Prone",
  img: "systems/my-system/icons/conditions/prone.svg",
  system: {
    changes: [{ key: "system.attributes.ac", type: "add", value: -2 }]
  }
};
CONFIG.statusEffects["my-system.dead"] = {
  id: "my-system.dead",
  name: "MY_SYSTEM.Conditions.Dead",
  img: "systems/my-system/icons/conditions/dead.svg",
  overlay: true
};
delete CONFIG.statusEffects.dead;   // drop a core condition the system replaces
CONFIG.specialStatusEffects.DEFEATED = "my-system.dead";

Assigning a whole array (CONFIG.statusEffects = [...]) is deprecated since v14. The setter empties the list first, so it also wipes conditions other packages added earlier in init. Add and remove entries by id instead. ActiveEffect.fromStatusEffect(id) copies each entry (minus id and hud) into the effect data, so any ActiveEffectData field works here: changes under system, duration, statuses, showIcon, _id.

Changed in v14:

• CONFIG.statusEffects is a Proxy over the array and is also indexed by status id. A module adds one condition with CONFIG.statusEffects["my-module.dazed"] = {...} instead of pushing; delete CONFIG.statusEffects["dead"] removes one. Read with Object.values(CONFIG.statusEffects) or foundry.utils.iterateValues.
• icon and label are deprecated aliases for img and name.
• Changes live in system.changes with a string type ("add", "multiply", "override", "upgrade", "downgrade", "subtract", "custom"), not a numeric mode. A root-level changes array still loads — migrateData moves it to system.changes and maps the mode — but it warns. An entry with no type field gets "base", so system.changes uses ActiveEffectTypeDataModel.
• hud: false (or hud: {actorTypes: ["character"]}) controls whether the condition shows in the Token HUD.

Active Effect Subtypes

Active Effects are typed documents in v14. Declare subtypes in system.json under documentTypes.ActiveEffect and register a data model per subtype (a system uses bare names; a module prefixes them with its id). Every model must keep a changes ArrayField whose element schema defines type, phase, and priority — Foundry verifies this at startup and throws otherwise:

class SpellEffectData extends foundry.data.ActiveEffectTypeDataModel {
  static defineSchema() {
    const fields = foundry.data.fields;
    return Object.assign(super.defineSchema(), {
      spellLevel: new fields.NumberField({ integer: true, min: 0, initial: 1 }),
      isSuppressed: new fields.BooleanField()
    });
  }
}

Hooks.once("init", () => {
  Object.assign(CONFIG.ActiveEffect.dataModels, { spell: SpellEffectData });

  // Register a system-specific change type
  CONFIG.ActiveEffect.changeTypes["mysystem.percent"] = {
    label: "MY_SYSTEM.Changes.Percent",
    defaultPriority: 30,
    handler: (targetDoc, change, { modifyTarget = true } = {}) => {
      const current = foundry.utils.getProperty(targetDoc, change.key) ?? 0;
      const update = current * (1 + (Number(change.value) / 100));
      if ( modifyTarget ) foundry.utils.setProperty(targetDoc, change.key, update);
      return { [change.key]: update };
    }
  };
});

A change type id must be at least three characters and split on . into alphanumeric segments only (or match custom.{number}) — ActiveEffectTypeDataModel validates it on every change that carries the type. A hyphen is illegal, so a system whose id is my-system cannot namespace change types with that id; drop the hyphen (mysystem.percent) or use a bare name (percent).

ActiveEffect is a compendium document type in v14, so a system can ship a pack of conditions. Effects apply in phases: Actor#applyActiveEffects("initial") runs in prepareEmbeddedDocuments(), applyActiveEffects("final") after prepareDerivedData(). Register extra phases in CONFIG.ActiveEffect.phases and call applyActiveEffects("myPhase") yourself. ActiveEffect.CHANGE_TYPES is the merged, cached view of CONST.ACTIVE_EFFECT_CHANGE_TYPES and your registrations — register in init, before it is first read. To change how a core type applies, override the static _applyChangeAdd / _applyChangeSubtract / _applyChangeMultiply / _applyChangeOverride / _applyChangeUpgrade / _applyChangeCustom / _applyChangeUnguided methods on your ActiveEffect subclass. Read foundry-vtt-module-dev/references/active-effects-v2.md for the whole model.

Hotbar Macros

Register a hotbarDrop hook in ready to let players drag items to the macro bar:

Hooks.once("ready", () => {
  Hooks.on("hotbarDrop", (bar, data, slot) => {
    if (data.type === "Item") {
      createItemMacro(data, slot);
      return false;
    }
  });
});

Return false to prevent default handling. The helper creates a script macro that calls item.roll() via UUID.

Custom Enrichers

Register inline syntax patterns via CONFIG.TextEditor.enrichers in init:

CONFIG.TextEditor.enrichers.push({
  pattern: /@Check\[([^\]]+)\](?:\{([^}]+)\})?/g,
  enricher: async (match, options) => {
    const [, ability, label] = match;
    const anchor = document.createElement("a");
    anchor.classList.add("inline-check");
    anchor.dataset.action = "rollCheck";
    anchor.dataset.ability = ability;
    anchor.innerHTML = `<i class="fa-solid fa-dice-d20"></i> ${label ?? ability}`;
    return anchor;
  },
});

Now @Check[strength]{STR Save} in any enriched text becomes a clickable link. Handle clicks via data-action in your sheet's action handlers. Give the enricher an id if you also need an onRender callback.

Changed in v14: TinyMCE is gone; ProseMirror is the only editor. Register an alternative engine in CONFIG.TextEditor.engines. CONFIG.TextEditor.inserts lets a system add its own ProseMirror insert menu entries ({ action, title, html, inline?, children? }) — a readaloud block, a stat-block wrapper — without writing a ProseMirror plugin.

Token Customization

Override CONFIG.Token.objectClass to customize token rendering (e.g., custom resource bars):

CONFIG.Token.objectClass = MySystemToken;

Override CONFIG.Token.documentClass for custom token data handling. Set per-type prototype token defaults in _preCreate() — characters get actorLink: true and friendly disposition, NPCs get actorLink: false and hostile disposition.

Resource bar colors come from CONFIG.Token.barConfig ({ bar1: { colors: { empty, full } }, bar2: {...} }, Color values). Override Token#_getBarColors(index, data) on your CONFIG.Token.objectClass to color a bar from the actor's state — green while healthy, red when bloodied:

class MySystemToken extends foundry.canvas.placeables.Token {
  _getBarColors(index, data) {
    if ( index !== 0 ) return super._getBarColors(index, data);
    const pct = data.value / data.max;
    return pct < 0.5
      ? { empty: foundry.utils.Color.from("#400"), full: foundry.utils.Color.from("#f22") }
      : super._getBarColors(index, data);
  }
}

Changed in v14: CONFIG.<Document>.layerClass is deprecated. Replace a canvas layer through CONFIG.Canvas.layers.<name>.layerClass instead. Tokens carry level and depth fields — see foundry-vtt-module-dev/references/scene-levels.md.

Custom Journal Entry Pages

Define system-specific journal page types (class descriptions, bestiary entries) using TypeDataModel:

CONFIG.JournalEntryPage.dataModels["class"] = ClassPageData;
foundry.applications.apps.DocumentSheetConfig.registerSheet(
  foundry.documents.JournalEntryPage, "my-system", ClassPageSheet,
  { types: ["class"], makeDefault: true }
);

Declare custom page types in system.json under documentTypes.JournalEntryPage. Core reserves the text, image, pdf, and video type names.

Changed in v14: the bare DocumentSheetConfig global is a deprecation shim — use foundry.applications.apps.DocumentSheetConfig. JournalEntryCategory is a new embedded document; pages carry a category field for grouping in the journal sidebar.

Templates with Regions

MeasuredTemplate is deprecated since v14 and removed in v16, merged into the Region document. MeasuredTemplateDocument, MeasuredTemplateConfig and CONST.MEASURED_TEMPLATE_TYPES still exist as deprecation shims that log a warning. Area-of-effect shapes are Regions. RegionDocument has ten shape types — circle, cone, ellipse, emanation, grid, line, polygon, rectangle, ring, token — and canvas.regions places them interactively:

// Ask the user to place a 30-unit radius burst, then read who is inside it.
const region = await canvas.regions.placeRegion({
  name: "Fireball",
  shapes: [{ type: "circle", x: 0, y: 0, radius: canvas.dimensions.distancePixels * 30 }],
  visibility: CONST.REGION_VISIBILITY.ALWAYS,
  levels: [canvas.level.id]
}, { create: false });
if ( region ) {
  const targets = canvas.tokens.placeables.filter(t =>
    region.testPoint({ ...t.center, elevation: t.document.elevation }));
}

placeRegion(data, options) returns the placed RegionDocument, or null if the user cancelled. create: false gives an unsaved preview document — the right choice for a throwaway template. placeRegions(dataArray, options) places several in one gesture. Both accept attachToToken, allowRotation, allowEmpty, and the onMove / onRotate / preConfirm / preCommit callbacks.

For an aura that follows its owner, use RegionDocument.createTokenEmanation(token, range, regionData, { excludeToken, gridBased }) — it creates the Region, sizes it from the token's own shape, and attaches it.

canvas.regions.templateMode is the player-facing toggle: on, the Region tools place one-off templates; off, the GM edits persistent Regions. It defaults to on for non-GM users.

Read foundry-vtt-module-dev/references/measured-templates.md for the full replacement guide.

For full details on these topics, read references/advanced-system-features.md.

Styling & Themes

Systems carry the bulk of CSS in any Foundry world — character sheets, item sheets, chat cards. The patterns below are extracted from the two largest production systems (foundryvtt/dnd5e and foundryvtt/pf2e) and codify what works at scale on v14. The mechanism did not change in v14 — the same body.theme-light / body.theme-dark classes, the same .themed marker, the same @layer names — v14 only adds custom properties.

Nine rules every shipping system follows:

1. Single compiled CSS file declared in system.json styles[]. Never list LESS/SCSS partials.
2. Marker class on every Application root via DEFAULT_OPTIONS.classes: ["my-system", ...].
3. Component CSS is unlayered. Only wrap variable/token definitions in @layer variables. Component CSS without a layer wins against Foundry's @layer applications automatically.
4. CSS custom properties as the abstraction — not LESS/SCSS mixins.
5. Two coexisting variable strategies: override Foundry's --color-*/--font-* for skinning and namespace your own as --my-system-*.
6. Body-class theming — body.theme-light / body.theme-dark. No prefers-color-scheme, no [data-theme].
7. .themed.theme-{light,dark} for popouts and per-application theme overrides. Always pair with body-class selectors.
8. Per-version sheet folders — styles/v1/ for AppV1 fallbacks, styles/v2/ for current AppV2 styles.
9. Sheet scoping by document chain — .my-system.sheet.actor.character.

// styles/my-system.less — entry, only @imports
@import "variables/base.less";    // wrapped in @layer variables
@import "variables/light.less";   // body.theme-light + .themed.theme-light
@import "variables/dark.less";    // body.theme-dark + .themed.theme-dark
@import "v2/sheets.less";         // UNLAYERED — wins over Foundry's base
@import "v2/character.less";
@import "v2/chat.less";

// Per-theme variables via mixin pattern
.mixin-theme-dark() {
  --my-system-bg-card: #2a2018;
  --my-system-text-primary: #e9d8a6;
}

@layer variables {
  body.theme-dark .my-system,
  .themed.theme-dark.my-system {
    .mixin-theme-dark();
  }
}

The boilerplate ships a complete starter: styles/my-system.less, variables/ (base + light + dark), v2/sheets.less, v2/chat.less. Compile with lessc styles/my-system.less styles/my-system.css --source-map or integrate via Vite (see the foundry-vtt-module-dev skill's references/build-pipeline.md).

For the full rationale — Foundry's cascade-layer mechanics, why component CSS stays unlayered, ma

…(truncated)