用途:用于构建、扩展、调试和维护 Foundry Virtual Tabletop(v14+)模块,覆盖从新建脚手架到版本迁移的完整生命周期。从 v13 升级时,资料建议先阅读 references/v14-migration.md。
主要能力与结构:模块目录包含 module.json 清单、scripts/main.mjs 入口、templates/、styles/、packs/ 与 lang/。清单需声明 id、title、version、compatibility(minimum/verified)、documentTypes、esmodules、styles、languages、socket、relationships、packs、library、quickstart 等字段;id 只允许 [A-Za-z0-9_-] 且须与文件夹同名。
初始化:通过 init、setup、ready 三个钩子按序注册设置、自定义文档类型与表;init 阶段 game.user 尚不可用,ready 阶段可访问 game.actors 等。
样式:使用 CSS Cascade Layers,核心层顺序为 reset、variables、elements、blocks、applications、compatibility、layouts、system、modules、exceptions;模块在清单中指定 layer,或使用内层 @layer 分组。推荐使用主题 CSS 变量(如 --color-text-primary、--color-warm-2、--font-primary)而非硬编码颜色,v14 新增 --cursor-* 变量。
API 与数据:几乎全部核心 API 位于 foundry.* 命名空间,旧的裸全局(mergeObject、getProperty、Die 等)在 v14 已移除。数据层基于 DataModel/Document,可继承 TypeDataModel 定义 schema 并注册到 CONFIG.<Doc>.dataModels;模块可通过 documentTypes 贡献自定义子类型。UI 统一使用 ApplicationV2,旧 Application/FormApplication 已弃用。
使用方式:将模块放入 {userData}/Data/modules/my-module/ 或建立符号链接,启动 Foundry 并在世界观中启用模块,通过浏览器控制台查看日志与错误。
限制与注意:template.json 已弃用,静态 .html 以 text/plain 提供;-=key/==key 更新语法弃用,改用 foundry.data.operators 的 _del 与 _replace;{{select}} 与 {{colorPicker}} 在 v14 移除,富文本仅支持 ProseMirror;旧 shim 计划在 v15 移除。价格、授权、性能数据等暂未提供。