-
-
Notifications
You must be signed in to change notification settings - Fork 35
User Guide
Convenient Effects adds two new buttons to the token controls.
When the Add Convenient Effects button is pressed, the Convenient Effects app will open showing multiple collapsed folders. You can expand or collapse any folder and hover over an effect for a brief description of what it does. To apply an effect, select any number of tokens on the canvas and then select the effect you want from the list. This will toggle it on or off for all selected tokens.
![Convenient Effects App](https://github.com/DFreds/dfreds-convenient-effects/raw/main/docs/wiki/convenient-effects-app.png)
You can also click and drag any effect from the Convenient Effects app onto an actor sheet to apply it to that actor. This is useful for when that actor isn't currently on the canvas.
When the Remove Convenient Effects button is pressed, a dialog will display showing all active convenient effects for the selected tokens. You can easily choose which effects you want to remove and confirm it by clicking Remove.
![Remove Effects Dialog](https://github.com/DFreds/dfreds-convenient-effects/raw/main/docs/wiki/remove-effects.png)
Certain effects have multiple types of effects to choose from when adding or removing them. For instance, Enhance Ability has six different effects to choose from. These nested effects are indicated by a tree icon in the app. When chosen, a dialog is displayed allowing you to choose which of the nested effects to apply.
![Nested Effects Dialog](https://github.com/DFreds/dfreds-convenient-effects/raw/main/docs/wiki/nested-effects.png)
Note: Built-in nested effects are hidden by default. They can be shown as normal in the Convenient Effects app by setting the Show Nested Effects as described here.
Throughout your game, you're likely going to have effects that get applied more often than others. Convenient Effects provides a way to add or remove any effect from the Favorites folder. To do so, you can right click the effect and click Add/Remove Favorite from the context menu. Adding an effect as a favorite will remove it from its current folder and add it to the Favorites folder at the top. Conversely, removing an effect as a favorite will remove it from the Favorites folder and add it back to its original folder.
![Nested Effects Dialog](https://github.com/DFreds/dfreds-convenient-effects/raw/main/docs/wiki/favorite-effects.png)
This module allows any of the defined effects (custom or included) to be added as status effects on the token. To do so, first enable the Modify Status Effects so that the setting is set to either Replace or Add.
Once enabled, right click on any effect in the Convenient Effects application and select Toggle Status Effect to add or remove the effect from the list. This will apply or remove an icon next to the effect to indicate the state of the status effect. Once you are finished, everyone connected to the game should reload the Foundry application to see the changes.
![Status Effects](https://github.com/DFreds/dfreds-convenient-effects/raw/main/docs/wiki/status-effects.png)
Note: Convenient Effects ships with all the standard conditions automatically set to be status effects. Any or all of these can be removed or disabled. If you ever want to set the status effects back to the defaults, click the "Reset Status Effects to Defaults" button located at the top of the app.
Conflict: You should not use this and Combat Utility Belt's "Enhanced Conditions" at the same time, as multiple modules replacing/adding to the available status effects can cause conflicts.
Convenient Effects allows you to create your own custom effects using the standard active effect sheet.
Custom effects can be created by either pressing the "Create Effect" button or by right clicking and existing effect and clicking "Duplicate as Custom".
![Creating Effects](https://github.com/DFreds/dfreds-convenient-effects/raw/main/docs/wiki/creating-effects.png)
If you choose to create a new effect, you're presented with the active effect config sheet with all the default values. If you choose to duplicate an effect, all values will be filled in with the duplicated effects values.
![Active Effect Sheet](https://github.com/DFreds/dfreds-convenient-effects/raw/main/docs/wiki/active-effect-sheet.png)
Note that an additional field is added for custom effects with the label "Effect Description". This is the text that will be shown when hovering over the effect in the app.
From here, you can also turn your custom effect into a nested effect using the Nested Effects section.
Any created custom effects can be imported from a JSON file or exported to a JSON file. This is helpful when you want to transfer custom effects between worlds.
![Import/Export Custom Effects](https://github.com/DFreds/dfreds-convenient-effects/raw/main/docs/wiki/import-export-custom-effects.png)
To export the effects, click the "Export custom effects" button after expanding the Custom effects folder. This will open a native file handler which allows you to rename the file. Please do not change the file extension from .json
.
To import custom effects, click the "Import custom effects" button after expanding the Custom effects folder. This will open a dialog allowing you to choose the file to import. You should navigate to and select the .json
file that was exported in order to import it.
NOTE: This will merge with any custom effects you currently have in the world.
You can directly link to effects in text via the following format:
@toggleEffect[Bane]{Toggle Bane on Selected Actor}
@toggleEffect[Bardic Inspiration]
If the effect within the brackets does not exist, you'll get a broken link as shown in the image.
@toggleEffect[Non-existent Effect]{Toggle effect that doesn't exist}
@toggleEffect[Non-existent Effect]
![Text Enrichment](https://github.com/DFreds/dfreds-convenient-effects/raw/main/docs/wiki/text-enrichment.png)
Any effects included or created can be toggled, added, or removed using macros.
To create a macro, click and drag a Convenient Effect from the app to the hotbar. This will create a new macro that will toggle the effect on or off for any selected tokens.
Convenient Effects ships with a small compendium of macros. The intention is to read and understand these so that you can create your own. For advanced users, additional methods are defined and documented here.
// Replace first argument with any available effect from the list
game.dfreds.effectInterface.toggleEffect('Bane');
This will toggle the effect Bane for any selected tokens. You can switch 'Bane' to any effect name listed in the Convenient Effects application.
let fromActorId = game.actors.get('some actor id').uuid; // get UUID based on some actor ID (replace it)
let fromTokenId = canvas.tokens.get('some token id').actor.uuid; // get UUID based on some token ID (replace it)
let fromActorName = game.actors.find(actor => actor.data.name == 'Merric (Halfling Barbarian)')?.uuid; // get UUID based on first actor name that matches
game.dfreds.effectInterface.toggleEffect('Aid', { uuids: [fromActorId, fromTokenId, fromActorName] });
let actorUuids = canvas.tokens.controlled.map(token => token.actor.uuid); // get multiple uuids from controlled tokens
game.dfreds.effectInterface.toggleEffect('Bane', { uuids: actorUuids });
Essentially, providing a UUID (unique identifier) to the toggleEffect
method will apply it only to actors that match that UUID. The macro shows several ways to get that information.
const uuid = canvas.tokens.controlled[0].actor.uuid;
const hasEffectApplied = await game.dfreds.effectInterface.hasEffectApplied('Bane', uuid);
if (!hasEffectApplied) {
game.dfreds.effectInterface.addEffect({ effectName: 'Bane', uuid });
}
This will add the provided effect to the actors that match the UUID.
const uuid = canvas.tokens.controlled[0].actor.uuid;
const hasEffectApplied = await game.dfreds.effectInterface.hasEffectApplied('Bane', uuid);
if (hasEffectApplied) {
game.dfreds.effectInterface.removeEffect({ effectName: 'Bane', uuid });
}
This will remove the provided effect from the actors that match the UUID.
const uuid = canvas.tokens.controlled[0].actor.uuid;
const effectData = game.dfreds.effectInterface.findEffectByName('Bane').convertToObject();
effectData.name = 'Test';
game.dfreds.effectInterface.addEffectWith({ effectData, uuid });
Each effect included in Convenient Effects can be customized before being added. In this example, the Bane effect is copied but renamed to 'Test'.
Midi-QoL has graciously added support for auto applying Convenient Effects. For instance, if a player decides to cast Blur on themselves, the Blur effect will automatically be applied to their character. If a barbarian wants to Rage, then Midi will auto apply the Rage condition.
Midi does this by checking the name of the feature that was used and checking to see if there is a matching Convenient Effect. If there is, it applies it to the targeted token or to the user if it has a target of "Self".
To enable this behavior, you need to enable the "Auto apply item effects to targets" and the "Apply Convenient Effects" settings located in the Midi workflow configuration settings.
![Midi Settings](https://github.com/DFreds/dfreds-convenient-effects/raw/main/docs/wiki/midi-settings.png)
Whenever a convenient effect is applied, removed, or expires from a time limit, you have the option to print out the information in chat. This setting dictates who the chat message is sent to by their role. All roles with privilege equal to or higher than the selected role are sent the message.
Chat messages can be disabled for everyone by setting the selection to 'None'.
This setting dictates which roles should be able to access the token control to open the Convenient Effects app. All roles with privilege equal to or higher than the selected role are able to view and use the controls.
This control can be disabled for everyone by setting the selection to 'None'.
This setting dictates which roles should be able to access the token control to remove effects. All roles with privilege equal to or higher than the selected role are able to view and use the controls.
This control can be disabled for everyone by setting the selection to 'None'.
This settings allows players to create, duplicate, edit, and delete all custom effects.
Certain convenient effects have built-in integration with ATE to change the amount of light the token emits, the vision of a token, or the size of a token via an active effect. Examples include Torch, the Light cantrip, and Holy Aura. If this setting is enabled, it allows these effects to be added.
Note that in order to use the size changes for enlarge or reduce, the appropriate setting must be enabled in ATE.
Certain convenient effects have built-in integration with Token Magic to apply token effects via an active effect. Examples include Blur, Mirror Image, and Shield. If this setting is enabled, it allows these effects to be added.
Note that this also requires DAE to work.
The status effects that are shown when right-clicking a token can be modified by this module. If you set this to option to Replace, all default status effects provided by Foundry will be overwritten by the status effects from this module. If you set this option to Add, the status effects from this module are appended to the end of the Foundry default status effects.
Note that this requires a full reload of Foundry on change (done automatically). Also note that using this feature is incompatible with Combat Utility Belt.
If enabled, this setting prioritizes applying convenient effects to targets before selected tokens. While not totally useful for a GM who can select any token on the canvas, this is particularly useful for players that have access to the new token controls (see Controls Permission).
This defines when the description of the effect is shown in chat. It requires that Chat Message Permission be enabled.
If enabled, this setting will display nested effects in the application. These are otherwise hidden and accessed via the parent effect, indicated by a tree icon.
SocketLib allows convenient effects to be executed as if they were applied by a GM, even if a player is the one that triggers them.
If you allow your players to view the convenient effects app via the settings and they set their personal settings to Prioritize Targets, they can now actually apply effects to any linked or PC actors they're targeting.
This also fixes the integration with Midi QoL (see section) so that any matching effects can be applied to linked tokens such as named NPCs or other player characters when they target them and cast spells/use features.
SocketLib only affects the above use cases. If you were using and enjoying Convenient Effects without letting (pesky) players use it and without the Midi integration, nothing else changes for you.
LibWrapper allows for wrapping core Foundry functions. It's used by dozens of modules, so there is a chance you already have it.
LibWrapper provides an easy way to wrap Foundry methods while minimizing the chances of two modules conflicting with each other. While this is not technically a hard dependency, you will get a popup explaining that a fallback is being used (included with this module). You should enable libWrapper to remove this popup.
None of the modules listed in this section are required for Convenient Effects to work. However, they do improve the usage of various effects immensely.
Times Up handles automatic expiration of effects that have durations. A lot of the included effects in Convenient Effects have durations set, so this will allow them to be expired at the right time.
If you choose not to install this, effects will never expire and have to be removed manually.
DAE handles various additional expiration effects, such as after one attack or after one hit. It also adds ability to reference actor data in effect value definitions (i.e. @abilities.dex.mod), adds an extended set of custom fields like all of the traits, and the ability to update derived fields, such as abilities.dex.mod.
If you don't use this module, some included effects will only partially work.
Midi-Qol handles a vast amount of automation for various active effects. Specifically, it allows for granting auto advantage/disadvantage to effects as well as displaying prompts for optional uses of effects (like using your bardic inspiration on a saving throw).
Midi-QoL has also explicitly integrated with Convenient Effects to allow users to auto apply the active effects from Convenient Effects when appropriate. See Integrating with Midi-QoL for more information.
Active Token Effects (or ATE) allows active effects to also manipulate dim/bright vision for a token, dim/bright light emitted by a token, or the size of a token. Certain effects (like Torch) will use ATE to change the vision or lighting on whoever it affects.
Note that the integration of this module must be opted into via the settings as described here.
Token Magic FX allows for active effects to add visual FX to tokens via active effects. For example, the Blur spell can actually make the token look blurred.
This requires enabling DAE as it uses the macro.tokenMagic
active effect added by it.
Note that the integration of this module must be opted into via the settings as described here.