World Maintenance Examples

Use these commands for world maintenance outside combat: upload images, create NPCs, and synchronize rules data. Copy an example and adjust its parameters when preparing a world or maintaining content in bulk.

Upload a local asset

Upload a local image into 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'

Create an NPC from a compendium

Clone an NPC from a compendium and patch it during creation:

{
  "packId": "dnd5e.monsters",
  "entryId": "hx240PG5r5qpRet3",
  "name": "Roadside Luggage Devourer",
  "folder": "This Week's Encounter - Mimics",
  "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'

Update Actor images

Update the Actor image, prototype Token image, and images on selected embedded Items:

{
  "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'

Attack-damage migration

Audit legacy base-damage bonuses on world Actors against a strict manifest and save complete local Actor rollback snapshots:

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'

Confirm that the dry-run Actor, attack, and pending counts match the manifest exactly before passing --apply. The command runs the dry-run again and writes the backup before calling Foundry’s embedded Item Document API. It refuses to write if any manifest field differs, including the world, version, Actor/Item/activity ID, name, attack ability, damage dice, or bonus damage.

Bilingual Actor synchronization

Audit or synchronize bilingual Actor rules data against a strict manifest, including the synthetic Actors/ActorDeltas of every unlinked Token in the scene:

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'

Confirm that the dry-run pair count, world Actors, unlinked Tokens, and pending synchronization state match the manifest before passing --apply. The command saves complete Actor and Token JSON snapshots first, then uses the Foundry Document API to synchronize rules fields and Item topology. Localized names, descriptions, images, and live state such as HP, temporary HP, and consumed resources are preserved.