fvtt-active-effects

# Foundry VTT Active Effects

**Domain:** Foundry VTT Module/System Development
**Status:** Production-Ready
**Last Updated:** 2026-01-05

## Overview

Active Effects automatically modify Actor data through a changes array. They're the primary mechanism for buffs, debuffs, equipment bonuses, and temporary conditions.

### When to Use This Skill

- Creating equipment bonuses that modify actor stats
- Implementing buff/debuff spells with duration
- Setting up status conditions (prone, stunned, etc.)
- Using CUSTOM mode for complex calculations
- Managing effect transfer from items to actors

## ActiveEffect Structure

### Core Properties

```javascript
{
  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
  }
}
```

## Effect Modes

### CONST.ACTIVE_EFFECT_MODES

| 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 |

### Mode Examples

```javascript
// 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