fvtt-v13-migration

# 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:
```javascript
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:
```json
{
  "esmodules": ["scripts/module.js"],
  "scripts": []
}
```

### Internationalization (i18n)
**ALWAYS** use `game.i18n.localize()` or `game.i18n.format()` for user-facing text. Never hardcode English strings.

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

// GOOD
ui.notification