世界维护示例

战斗之外的世界杂活都在这页：传图片、建 NPC、同步规则数据。开团前备世界或批量维护内容时，照抄示例改参数即可。

上传本地资产

上传本地图片到 Foundry data storage：

{
  "sourcePath": ".tmp/fvtt-assets/coin-scarab-single.png",
  "targetDir": "worlds/COS/assets/monsters",
  "filename": "coin-scarab-swarm.png",
  "overwrite": true
}

npm run fvtt:cdp -- --port 9230 --target-url autofvtt.criticalrole.top asset-upload --json '@asset.json'

从 Compendium 创建 NPC

从 compendium clone 一个 NPC，并在创建时打补丁：

{
  "packId": "dnd5e.monsters",
  "entryId": "hx240PG5r5qpRet3",
  "name": "路边行李吞噬者 Roadside Luggage Devourer",
  "folder": "本周遭遇 - 宝箱怪",
  "updates": {
    "system.details.cr": 4,
    "system.attributes.hp.max": 98,
    "prototypeToken.width": 2,
    "prototypeToken.height": 2
  }
}

npm run fvtt:cdp -- --port 9230 --target-url autofvtt.criticalrole.top actor-create-from-compendium --json '@actor.json'

更新 Actor 图片

更新 actor、prototype token 和指定 embedded item 的图片：

{
  "actorIdentifier": "金币虫群 Coin-Scarab Swarm",
  "img": "worlds/COS/assets/monsters/coin-scarab-swarm.png",
  "prototypeToken": true,
  "items": ["Swarm", "啃咬 Bites", "财宝拟态 Treasure Mimicry"]
}

npm run fvtt:cdp -- --port 9230 --target-url autofvtt.criticalrole.top actor-set-image --json '@image.json'

攻击伤害迁移

按严格 manifest 审计世界 Actor 的旧版攻击基础伤害 bonus，并在本地保存完整 Actor 回滚快照：

npm run fvtt:cdp -- --port 9230 --target-url autofvtt.criticalrole.top actor-damage-migrate `
  --json '@docs/foundry-automation/data/dragonlance-ch1-attack-damage-migration.json' `
  --backup '.tmp-fvtt-damage-migration/backups/dragonlance-ch1.json'

双语 Actor 同步

按严格 manifest 审计或同步双语 Actor 的规则数据，并覆盖场景中所有未链接 Token 的 synthetic Actor/ActorDelta：

npm run fvtt:cdp -- --port 9230 --target-url autofvtt.criticalrole.top actor-bilingual-sync `
  --json '@docs/foundry-automation/data/dragonlance-ch1-bilingual-actor-sync.json' `
  --backup '.tmp-fvtt-damage-migration/backups/dragonlance-ch1-bilingual.json'

确认 dry-run 的配对数、世界 Actor、未链接 Token 和待同步状态符合 manifest 后再传 --apply。命令先保存完整 Actor/Token JSON 快照，然后通过 Foundry Document API 同步规则字段与 Item 拓扑；本地化名称、描述、图片，以及 HP/临时 HP/资源消耗等当前状态会保留。

确认 dry-run 的 Actor、attack、pending 数量与 manifest 完全一致后，显式传 --apply。命令会先再次执行 dry-run 并写入备份，只有备份成功才调用 Foundry embedded Item Document API；manifest 中的世界、版本、Actor/Item/activity ID、名称、攻击属性、伤害骰和附加伤害任一不匹配都会拒绝写入。