This skill should be used when creating or applying Active Effects, working with effect changes and modes (ADD, MULTIPLY, OVERRIDE, CUSTOM), implementing duration tracking for combat, or handling effect transfer from items to actors.
Creates and applies Active Effects with proper modes, durations, and transfer settings for buffs, debuffs, and equipment bonuses. Use when modifying actor data through effects, implementing temporary conditions, or handling item-to-actor effect transfers.
/plugin marketplace add ImproperSubset/hh-agentics/plugin install fvtt-dev@hh-agenticsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Domain: Foundry VTT Module/System Development Status: Production-Ready Last Updated: 2026-01-05
Active Effects automatically modify Actor data through a changes array. They're the primary mechanism for buffs, debuffs, equipment bonuses, and temporary conditions.
{
name: "Shield of Faith",
img: "icons/magic/defensive/shield.png",
disabled: false,
transfer: true, // Transfer from item to actor
origin: "Item.abc123", // Source reference
statuses: ["blessed"], // Status identifiers
changes: [
{
key: "system.attributes.ac.bonus",
mode: 2, // ADD
value: "2"
}
],
duration: {
seconds: 600, // 10 minutes
rounds: null,
turns: null,
combat: null,
startTime: null,
startRound: null,
startTurn: null
}
}
| Mode | Value | Behavior |
|---|---|---|
| CUSTOM | 0 | System-specific logic via hook |
| ADD | 1 | Sum numbers, concat strings |
| MULTIPLY | 2 | Multiply numeric values |
| OVERRIDE | 3 | Replace value entirely |
| UPGRADE | 4 | Use if value > current |
| DOWNGRADE | 5 | Use if value < current |
// ADD - most common
{ key: "system.attributes.ac.bonus", mode: 2, value: "2" }
// MULTIPLY - percentage bonuses
{ key: "system.attributes.movement.walk", mode: 2, value: "1.5" }
// OVERRIDE - fixed values
{ key: "system.attributes.ac.calc", mode: 3, value: "natural" }
// UPGRADE - only if better
{ key: "system.abilities.str.value", mode: 4, value: "19" }
// DOWNGRADE - only if worse
{ key: "system.abilities.dex.value", mode: 5, value: "4" }
// Actor.prepareData() execution:
1. this.data.reset() // Reset to source
2. this.prepareBaseData() // Basic setup
3. this.prepareEmbeddedDocuments() // Effects apply HERE
4. this.prepareDerivedData() // Calculate derived values
Critical: Effects apply in step 3, so they cannot modify values created in step 4.
prepareBaseData() {
// Initialize values that effects will target
this.system.attributes.ac.bonus = 0;
this.system.modifiers.all = [];
}
prepareDerivedData() {
// Use modified values here
const ac = this.system.attributes.ac.base +
this.system.attributes.ac.bonus;
}
For complex calculations, use mode 0 with the applyActiveEffect hook:
Hooks.on("applyActiveEffect", (actor, change, current, delta, changes) => {
// Only handle our custom keys
if (!change.key.startsWith("system.custom.")) return;
switch (change.key) {
case "system.custom.damageReduction":
// Stack damage reduction multiplicatively
const existing = current || 1;
changes[change.key] = existing * (1 - delta);
break;
case "system.custom.attackBonus":
// Add with diminishing returns
const bonus = current || 0;
changes[change.key] = bonus + Math.floor(delta / (1 + bonus / 10));
break;
}
});
const combatEffect = {
name: "Haste",
changes: [...],
duration: {
rounds: 10,
combat: game.combat?.id,
startRound: game.combat?.round,
startTurn: game.combat?.turn
}
};
await actor.createEmbeddedDocuments("ActiveEffect", [combatEffect]);
const timedEffect = {
name: "Poison",
changes: [...],
duration: {
seconds: 3600, // 1 hour
startTime: game.time.worldTime
}
};
// Combat-based
const remaining = effect.duration.rounds -
(game.combat.round - effect.duration.startRound);
// Time-based
const elapsed = game.time.worldTime - effect.duration.startTime;
const remaining = effect.duration.seconds - elapsed;
Effects are copied from Item to Actor when embedded:
// Default: CONFIG.ActiveEffect.legacyTransferral = true
// Effect is duplicated to actor.effects
Effects stay on Item but apply to parent Actor:
// In system init:
CONFIG.ActiveEffect.legacyTransferral = false;
// Benefits:
// - Edit effects without re-adding items
// - Cleaner data model
// - Effects removed when item removed
{
name: "Magic Sword Bonus",
transfer: true, // Apply to actor (default)
// transfer: false // Stay on item only
changes: [...]
}
const magicArmorEffect = {
name: "+2 Armor",
img: "icons/equipment/chest/plate.png",
transfer: true,
changes: [
{
key: "system.attributes.ac.bonus",
mode: 2, // ADD
value: "2"
}
]
};
await item.createEmbeddedDocuments("ActiveEffect", [magicArmorEffect]);
async function applyBless(actor) {
await actor.createEmbeddedDocuments("ActiveEffect", [{
name: "Bless",
img: "icons/magic/holy/prayer.png",
statuses: ["blessed"],
changes: [
{ key: "system.bonuses.attack", mode: 2, value: "1d4" },
{ key: "system.bonuses.save", mode: 2, value: "1d4" }
],
duration: {
rounds: 10,
combat: game.combat?.id,
startRound: game.combat?.round
}
}]);
}
const proneEffect = {
name: "Prone",
img: "icons/svg/falling.svg",
statuses: ["prone"],
changes: [
{ key: "system.attributes.ac.bonus", mode: 2, value: "-4" }
],
flags: {
core: { statusId: "prone" }
}
};
{
key: "system.attributes.ac.bonus",
mode: 2,
value: "@abilities.dex.mod" // Roll data reference
}
// WRONG - calculated in prepareDerivedData, too late
{ key: "system.attributes.ac.value", ... }
// CORRECT - target the bonus that feeds into calculation
{ key: "system.attributes.ac.bonus", ... }
// WRONG - effects cannot modify embedded items
{ key: "items.0.system.damage", ... }
// CORRECT - modify actor data only
{ key: "system.bonuses.weaponDamage", ... }
// WRONG - bonus undefined, effect fails
prepareDerivedData() {
this.system.ac.total = this.system.ac.base + this.system.ac.bonus;
}
// CORRECT - initialize in prepareBaseData
prepareBaseData() {
this.system.ac.bonus = 0;
}
// Effect values are always strings in the changes array
{ key: "system.hp.bonus", mode: 2, value: "10" }
// ADD mode parses to number automatically
// For CUSTOM mode, parse manually:
const numValue = Number(change.value);
// Always check before processing
for (const effect of actor.effects) {
if (!effect.active) continue; // Skip disabled
// Process effect...
}
// Or use the filtered collection
for (const effect of actor.appliedEffects) {
// Only active effects
}
// UI may not update in real-time
// Close/reopen sheet to see accurate duration
// Or force refresh:
await effect.updateDuration();
// Discover available data paths:
const paths = Object.keys(
foundry.utils.flattenObject(game.system.model.Actor.character)
);
console.log(paths);
// Or inspect a specific actor:
console.log(Object.keys(
foundry.utils.flattenObject(actor.system)
));
prepareBaseData()transfer: true for item effects that apply to actorseffect.active before processingLast Updated: 2026-01-05 Status: Production-Ready Maintainer: ImproperSubset
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.