Standard Combat Flow

When your agent runs a combat encounter, follow this loop: build the combat catalog once when combat starts, then read context, execute an action, inspect the receipt, and decide the next step on every turn.

To start or take over an existing combat:

npm run fvtt:cdp -- --port 9230 --target-url autofvtt.criticalrole.top doctor
npm run fvtt:cdp -- --port 9230 --target-url autofvtt.criticalrole.top combat-snapshot
npm run fvtt:cdp -- --port 9230 --target-url autofvtt.criticalrole.top build-combat-catalog --out encounter.json

Every turn

npm run fvtt:cdp -- --port 9230 --target-url autofvtt.criticalrole.top combat-context --json '@encounter.json'
npm run fvtt:cdp -- --port 9230 --target-url autofvtt.criticalrole.top execute-turn --json '@turn.json' --include-context-after

Recommended turn.json:

{
  "sourceTokenId": "pNPz2V5cFKYZmzds",
  "actionKey": "greatsword.attack",
  "targetTokenIds": ["SUnqlZmNomEYNOzh"],
  "catalog": {
    "version": 1,
    "tokens": {}
  }
}

execute-turn does not advance the turn by default. Add --advance, or set "advance": true at the top level of the JSON request, when the turn should advance after the action or action sequence finishes.

Multiattack sequences

Put a multiattack in one actions sequence. The top-level sourceTokenId, targetTokenIds, and catalog become defaults for every action:

{
  "sourceTokenId": "pNPz2V5cFKYZmzds",
  "targetTokenIds": ["SUnqlZmNomEYNOzh"],
  "catalog": {
    "version": 1,
    "tokens": {}
  },
  "actions": [
    { "actionKey": "claws.attack" },
    { "actionKey": "claws.attack" }
  ]
}

For debugging or one-off calls, you may pass real Foundry IDs directly:

{
  "sourceTokenId": "pNPz2V5cFKYZmzds",
  "itemId": "CXwSa8DUIlIvjg9H",
  "activityId": "dnd5eactivity000",
  "targetTokenIds": ["SUnqlZmNomEYNOzh"],
  "postDelayMs": 0
}

Execution results

The result includes:

  • status: completed / no-workflow / error
  • itemCardId
  • damageRolled
  • tokenDiffs
  • warnings
  • timings
  • optional combatAfter / contextAfter

Sequence mode also returns sequence: true, actions[], and resolvedActions[]. The aggregate result contains the sequence-wide status, actionCount, successCount, damageRolled, tokenDiffs, warnings, and itemCardIds.

When the agent evaluates the result, inspect tokenDiffs first and chat flags second. Raw midi-qol damage may differ from the actual HP delta because of resistance, immunity, damage reduction, or temporary HP.