The PC Actor API was added in v6 and provides programmatic access to PC actor functions that are normally accessed through the graphical interface in Foundry VTT.

Overview

The API is available exclusively for PC actors (actor.type === "PC"). Access the API through the actor.api property:

const actor = game.actors.get("actor-id");
if (actor.api) {
    // Use the API
    await actor.api.rollAttribute("strength");
}

Attributes

Several of the API often requires you to send in what attribute you are requesting the availible values are as follows:

World of Darkness v20 attritbute settings
strength, dexterity, stamina, charisma, manipulation, appearance, perception, intelligence, wits

World of Darkness v5 attribute settings
strength, dexterity, stamina, charisma, manipulation, composure, intelligence, wits, resolve

Abilities

Several of the API often requires you to send in what ability you are requesting to use. To learn this id you can open to edit any ability on a PC Actor sheet and check for its id value. It is this value you can use.

It is also possible to use the ability item's item._id but these are unique for each sheet.

Advantage

To learn the id of the advantage you wish to roll you can open to edit any advantage on a PC Actor sheet in the Setting tab under Stats.

Available Methods

Core Roll Methods

`rollAttribute(attributeKey, options)`

Rolls an attribute and returns the number of successes.

Parameters:

attributeKey (string, required) - The requested attribute key to roll.
options (object, optional)
- difficulty (number, default: 6) - Difficulty level (must be positive integer, overrides item difficulty if set)
- useWillpower (boolean, default: false) - Whether to use willpower
- bonus (number, default: 0) - Additional bonus dice

Returns: Promise<number> - Number of successes

Example:

const actor = await game.actors.get(actorid);
const success = await actor.api.rollAttribute('perception', { 
    difficulty: 7, 
    useWillpower: true 
});

`rollAbility(abilityId, attributeKey, options)`

Rolls an ability and returns the number of successes.

Parameters:

abilityId (string, required) - The ability item ID
attributeKey (string|null, optional) - Optional attribute key to combine with (null = no attribute)
options (object, optional)
- difficulty (number, default: 6) - Difficulty level (must be positive integer, overrides item difficulty if set)
- useWillpower (boolean, default: false) - Whether to use willpower
- bonus (number, default: 0) - Additional bonus dice

Returns: Promise<number> - Number of successes

Example:

const actor = await game.actors.get(actorid);
const success = await actor.api.rollAbility('athletics', 'dexterity', { difficulty: 6 });

// Ability without attribute
const success = await actor.api.rollAbility("ability-id");

// Ability with attribute
const success = await actor.api.rollAbility("ability-id", "attribute-id", { difficulty: 6 });

`rollAdvantage(advantageId, options)`

Rolls an advantage and returns the number of successes.

Parameters:

advantageId (string, required) - The advantage item ID
options (object, optional)
- difficulty (number, default: 6) - Difficulty level (must be positive integer, overrides item difficulty if set)
- useWillpower (boolean, default: false) - Whether to use willpower
- bonus (number, default: 0) - Additional bonus dice

Returns: Promise<number|false> - Number of successes, or false if advantage.system.settings.useroll === false

Example:

const actor = await game.actors.get(actorid);
const success = await actor.api.rollAdvantage('willpower');

Actor Item Usage Methods

`useFeature(featureId)`

Uses a feature (background, merit, flaw, etc.) that are availible to be rolled, opening a dialog for rolling.

Parameters:

featureId (string, required) - The feature item ID

Returns: Promise<true|false> - false if feature.system.isrollable === false

Example:

const actor = await game.actors.get(actorid);
const itemid = await actor.api.getItemId('Super trait');
actor.api.useFeature(itemid);

`useCombatItem(itemId, options)`

Uses a combat weapon (melee or ranged), opening a dialog for rolling.

Parameters:

itemId (string, required) - The weapon item ID
options (object, optional)
- action (string, default: "attack") - Action type: "attack" or "damage"

Returns: `true/false

Example:

const actor = await game.actors.get(actorid);
const itemid = await actor.api.getItemId('Sword');
actor.api.useCombatItem(itemid);

// Attack with weapon
await actor.api.useCombatItem("weapon-id", { action: "attack" });

// Damage roll
await actor.api.useCombatItem("weapon-id", { action: "damage" });

`usePower(powerId)`

Uses a power or rote, opening a dialog for rolling.

Parameters:

powerId (string, required) - The power or rote item ID

Returns: Promise<Object> - Status object indicating dialog was opened

Note:

Accepts both item.type == "Power" and item.type == "Rote" items.
Rote items open a different dialog (DialogAreteCasting) compared to regular powers (DialogPower), as Rotes require special handling for Arete casting mechanics.

Return Object:

{
    success: boolean,
    dialogOpened: boolean,
    powerId: string,
    powerName: string,
    powerType: string
}

Example:

const actor = await game.actors.get(actorid);
const itemid = await actor.api.getItemId('Persuasion');
await actor.api.usePower(itemid);

Utility Methods

`getItemId(itemName)`

Gets an item ID by searching for items with a matching name on the actor.

Parameters:

itemName (string, required) - The item name to search for (case-sensitive, exact match)

Returns: Promise<string|false> - Item ID if exactly one item found, false if no items or multiple items found

Example:

// Get item ID and use it
const itemId = await actor.api.getItemId("Sword");
if (itemId) {
    await actor.api.useCombatItem(itemId, { action: "attack" });
}

// Or use directly in other API calls
await actor.api.useCombatItem(await actor.api.getItemId("Warhammer"));
await actor.api.usePower(await actor.api.getItemId("Dominate"));

Note: If getItemId returns false, the subsequent API call will fail with an error. For safer usage, check the result first.

`modifyHealth(damageType, amount, options)`

Modifies an actor's health (damage levels).

Parameters:

damageType (string, required) - Type of damage: "bashing", "lethal", or "aggravated"
amount (number, required) - Amount of damage (positive = add damage, negative = remove damage)
options (object, optional)
- heal (boolean, default: false) - If true, treat amount as healing (subtract from damage)

Returns: Promise<Object> - Updated health data

Return Object:

{
    bashing: number,
    lethal: number,
    aggravated: number,
    woundlevel: string,
    woundpenalty: number
}

Example:

// Add 2 bashing damage
const health = await actor.api.modifyHealth("bashing", 2);

// Remove 1 lethal damage (two ways)
await actor.api.modifyHealth("lethal", -1);
await actor.api.modifyHealth("lethal", 1, { heal: true });

Error Handling

All API methods validate:

That the actor is of type "PC"
That required parameters are provided
That items/attributes/powers exist and are visible
That values are of the correct type

Errors are thrown as Error objects with descriptive messages.

Console Warnings

Some methods return false instead of throwing errors. When this happens, a console warning is logged to help with debugging:

rollAdvantage: Warns when advantage.system.settings.useroll === false
useFeature: Warns when feature.system.isrollable === false
getItemId: Warns when no items found or multiple items found with the same name

Example warnings:

WoDAPI | rollAdvantage - Advantage 'Willpower' (abc123) cannot be rolled (useroll === false)
WoDAPI | useFeature - Feature 'Resources' (def456) cannot be rolled (isrollable === false)
WoDAPI | getItemId - More than one item with name 'Warhammer' found (2 items). Need to use precise item._id
WoDAPI | getItemId - No item found with name 'Sword' on actor 'John Doe'

Common Patterns

Finding Items by Name

// Safe pattern: check first
const itemId = await actor.api.getItemId("Sword");
if (itemId) {
    await actor.api.useCombatItem(itemId, { action: "attack" });
}

// Direct pattern: use in API call (fails if item not found)
await actor.api.useCombatItem(await actor.api.getItemId("Warhammer"));

Rolling with Custom Difficulty

// Override item's difficulty
await actor.api.rollAttribute("strength", { difficulty: 8 });
await actor.api.usePower("power-id", { difficulty: 7 });

Checking if Item Can Be Rolled

// Advantage: returns false if cannot be rolled
const result = await actor.api.rollAdvantage("advantage-id");
if (result === false) {
    console.log("Cannot roll this advantage");
}

// Feature: returns false if cannot be rolled
const status = await actor.api.useFeature("feature-id");
if (status === false) {
    console.log("Cannot roll this feature");
}

Limitations

PC Actors Only: The API is only available for PC actors (actor.type === "PC")
Dialog Methods: Methods that open dialogs (useFeature, useCombatItem, usePower) require user interaction and display results in chat, not as return values
Item Names: getItemId performs exact, case-sensitive name matching
Weapons Only: useCombatItem only supports weapons, not armor

Health

(max hp) actor.system.traits.health.totalhealthlevels.max

(current hp) actor.system.traits.health.totalhealthlevels.value