Active Effects

Overview

Foundry Virtual Tabletop provides a convenient system for applying changes to characters (Actors) based on certain effects, equipment, spells, or other special traits that might give temporary benefits or downsides. This provides Game Systems and Add-on Modules with the ability to create, modify, and distribute their own prefab conditions that users can use to shape how these effects apply to characters in their specific games.

This page provides an overview of Active Effects, their function, and how to find data structures you can use active effects to modify, and how to import items from compendiums or json files.

Object Data Paths

This article is going to refer to Data Paths a lot when talking about how to create Active Effects. All of the data stored on a character is stored in an Object, Data Paths are used to tell the Active Effects system where to find the data it will modify. Data paths are presented in a simple 'dot notation', case-sensitive words separated by . such as data.attributes.ac.bonus

How Active Effects Change Actors

In order to understand how Active Effects work, it's important to first understand the way that Foundry Virtual Tabletop stores data for Actors. Character sheets store a wide variety of different data, and while it's certainly easy to change a 10 to an 11 on a particular character attribute, when games involve a lot of temporary effects it's easy to forget what the original number was after you've changed it.

For the purposes of this article, it's easiest to imagine that Foundry VTT stores a second copy of the data for each character. When an Active Effect is applied, the original data is unchanged. Instead, the change is applied to a copy of the Actor which is presented to the user. By preserving the original data in this way, when a character loses a magical item or a temporary effect they can have the active effect removed- at which point their original data is restored. This convenient process allows for one or more active effects to be stored on an actor and toggled on or off as needed without making permanent changes.

Active effects can apply to an Actor from one of three sources.

Actor-Level Active Effects

The most basic active effects are stored on an Actor itself, and in most cases they can be modified directly from a character sheet. Most game systems which use Active Effects have a section on their character sheets reserved for the express purpose of creating and managing active effects at the Actor level. A good example of this would be a situation where perhaps your character has a bonus to their movement speed while they are driving their car.

Condition-Level Active Effects

Many game systems use Conditions (commonly referred to as status effects) to apply active effects for very temporary bonuses or penalties. These are most often defined at a System level and are applied to an actor via the Token HUD, by right-clicking and choosing the appropriate Condition (or status effect). Often, these active effects will have a pre-defined duration and will be automatically toggled off when they expire.

Item-Level Active Effects

When an Item which contains an Active Effect is dropped onto an Actor sheet, it will usually transfer the effect to its actor. This allows for a character to have a magical item that increases their attributes, such as a belt that increases their Brawn by 2- or a cursed knife that reduces their dexterity by 2.

Creating Active Effects

Due to reliance on data paths, Active Effect creation can seem daunting for those who might just be getting started with a game system, but learning to use them is something that is easy to master with a few tools in your toolbox.

The most important thing to do before trying to get started is to make sure that your game system provides a way to manage Active Effects. Not all game systems provide user access to the active effects tools, for example the Pathfinder Second Edition systems actively prevent users from creating Active Effects, and provides its suite of preconfigured effects and ways to use them.

If a game system provides access to creating active effects, an "Effects" tab will be present on Actor and Item sheets.

Finding Data Paths

Identifying the pieces of data that Active Effects can modify within your game system can seem a little tricky at first, because it does involve using the Developer Tools (F12 or CMD+Shift+I for macOS). However, this is a simple command that will show you all the paths that can potentially be changed.

The first step is finding out what types of Actors or Items you have available that you might want to modify.

1. Open your Developer Tools (F12 or CMD+Shift+I).
2. Click the "Console" tab.
3. At the bottom, in the console prompt, paste game.system.model.Actor or game.system.model.Item and press the Enter key.
4. A list of types of Actors or Items will be displayed based on which command you used, compressed to a single line that you can click to expand.

Once you know what kind of actor you want to change, you can get the list of modifiable traits for that actor type using a similar process, but instead of simply using Object.keys(foundry.utils.flattenObject(game.system.model.Actor.ACTORTYPEHERE)), replacing "ACTORTYPEHERE" with your chosen actor type, such as 'character'.

For example, if you are using the dnd5e game system and wish to find the data paths for a player character, you would use Object.keys(foundry.utils.flattenObject(game.system.model.Actor.character)).

The output of this gives you a very simplified, expandable list of datapaths which may be modified by your system.

Creating an Active Effect From an Actor Sheet or Item Sheet

Once you have identified the data paths you want to modify, you can create an Active Effect by accessing the 'effects' tab of your character's Actor sheet. The process for creating an Active Effect is the same regardless of whether you are creating the effect on an Actor or on an Item.

1. Open the Actor or Item sheet you wish to modify.
2. Optional: if this is an Item, decide if the effect should transfer to an actor or not. By default, the checkbox for Transfer Effect to Actor is checked.
3. Click the "Effects" tab.
4. Click the "+" button to add a new Attribute Key.
5. Fill out the small form that appears. The most important field is "Attribute Key", where you will place the data path you found (such as system.attributes.ac.bonus). The Change Mode determines how the Effect Value that you choose will be applied.
6. Click "Submit Changes".
7. Confirm the change applied to your actor by checking their character sheet!

Once you have created an Active Effect, it will appear in the list of Active Effects on the Actor or Item sheet. You can usually toggle the effect on or off by clicking the toggle next to the effect's name.

Effects With Multiple Changes

It isn't uncommon for magic items or special equipment to modify more than one aspect of a character. The Active Effects system allows for defining effects which change multiple values at different data paths. When creating an effect as above, you can repeat steps 4-6 as necessary to make multiple changes inside the same effect.

API References

To interact with Active Effects documents programmatically, you will primarily use the following API concepts:

• classes/client.ActiveEffect
• classes/client.ActiveEffectConfig