foundry-pf2e

name

foundry-pf2e

description

Authoring Foundry VTT Pathfinder 2e (PF2e) modules with TypeScript, Svelte 5, and Vite, targeting Foundry v14 APIs only (ApplicationV2 / DialogV2 / DataModel — never the v1 namespace). Use whenever working inside a Foundry/PF2e module repo: editing module.json, src/ esmodules, hooks, settings, document flags, compendium packs (the fvtt CLI), a Svelte UI mounted in ApplicationV2, the Vite lib build, or multi-client state sync. Trigger even when the user only mentions Foundry, a PF2e module, ApplicationV2, foundry packs, hooks, or a module.json — don't wait to be named.

Foundry VTT PF2e module authoring

Conventions and APIs for the runegoblin family of Foundry Pathfinder 2e modules. These are hybrid modules: compendium content (packs/) plus a scripted esmodule (src/) built with TypeScript + Svelte 5 + Vite into dist/<id>.js + .css, which module.json loads.

New module? Start from the runegoblin-foundrytemplate template and run npm run init -- <new-id>; it rewrites the id/title everywhere. Don't hand-scaffold from scratch.

Two rules that override defaults

1. v14 only — no v1 APIs. Use only current Foundry APIs under the foundry.* tree. Never the v1 namespace or deprecated globals: no foundry.appv1; no bare Application / FormApplication / Dialog; no bare mergeObject / duplicate / getProperty (use the foundry.utils.* forms). Every window is an ApplicationV2 (foundry.applications.api.ApplicationV2); dialogs are DialogV2 (foundry.applications.api.DialogV2); structured data is foundry.abstract.DataModel with defineSchema(). If a class seems to exist only in v1, find its V2 replacement before writing it — don't fall back to v1.

2. TypeScript everywhere, including tooling. App code, vite.config.ts, svelte.config.ts, and Node scripts (scripts/*.ts) are all TypeScript. Run scripts with node scripts/foo.ts; Node ≥22.18 strips types by default, so no tsx/ts-node. Don't introduce .mjs/.js tooling unless a tool's config loader requires it.

Reference files — read the one that fits the task

Load these as needed; don't read all of them up front.

• references/foundry-api.md — the API surface: foundry.* namespaces, game.*, hooks and lifecycle, documents & flags, settings, the packs runtime API, ambient globals, and where the authoritative docs live. Read when writing hooks, settings, flags, or any Foundry API call.
• references/svelte-in-applicationv2.md — the Foundry UI glue: a thin ApplicationV2 shell that mount()s a Svelte 5 component (unmount() on close), the *.svelte shim, and Svelte's own AI tooling (@sveltejs/mcp autofixer) for the language itself. Read when building or editing any UI.
• references/vite-build.md — the build: lib config emitting one .js + one .css, the @ alias, what is and isn't bundled (.hbs/assets aren't), the release zip, and why npm run check is separate. Read when touching the build or adding templates/assets.
• references/packs-cli.md — compendium packs: the fvtt pack/unpack workflow, the LevelDB lock, _key, registering packs in module.json, and distribution — raw compendia vs. a derived Adventure pack (keepId, the _library/ convention, when not to use one). Read when working with packs/ or deciding how content ships.
• references/multi-client-sync.md — keeping state consistent across connected clients: document-flag propagation vs. raw socket, GM-authority request/reply, race safety. Read only when state must sync across clients.
• references/testing.md — the two-tier verification harness: npm test (vitest, zero-setup, the CI tier) vs. npm run test:e2e (Playwright against a real headless Foundry), what each proves, commands + preconditions, checking harness health before trusting green, and how to author a spec. Read when verifying a change, adding tests, or wiring CI.

Essentials worth knowing without opening a file

Module identity. The module id (e.g. pf2e-my-module) is the key for flags, settings, the socket channel (module.<id>), and pack names (<id>.<pack>). Use a const MODULE_ID = '<id>' and reference it everywhere.

Public API. Expose it the Foundry way: game.modules.get(MODULE_ID).api = {...} (on ready, or earlier if dependents need it). Don't attach to game. api isn't a typed field on Module, so cast at the assignment: (module as { api?: T }).api.

Localization. User-facing strings live in lang/en.json under <id>.* and are read with game.i18n.localize('<id>.key') / format(key, data). No hard-coded strings. lang/ ships verbatim (not built) and is in the release zip.

Flags for state. Persisted module state lives in document flags: doc.getFlag('<id>', key) / setFlag(...) / unsetFlag(...). For structured data use foundry.abstract.DataModel + static defineSchema().

Authoritative docs. Official reference: https://foundryvtt.com/api/ (pick the v14 build). The foundry-pf2e typedefs (node_modules/foundry-pf2e/types/) are what tsc checks and add PF2e types. On conflict, trust the typedefs for what compiles, the docs for what runs.