FXMaster

FXMaster is a module for Foundry Virtual Tabletop that provides various types of effects:

• Particle Effects, including weather (rain, clouds, fog, snow, etc.), animals (crows, bats, spiders, etc.), and a few others.
• Filter Effects, including color overlays, underwater, and lightning.
• Clickable Special Effects, using video files provided by external sources.

This module also provides ways to easily configure these effects.

Table of Contents

• FXMaster
  • Table of Contents
  • Installation Instructions
  • FAQ
  • Usage
    • Special Effects
      • Playing Special Effects
      • Elevation
      • Cast Modes
      • Managing Custom Special Effects
    • Particle Effects
      • Masking Particle Effects
      • ⚠ Warning Regarding Large Scenes
    • Invert Particle Effect Mask
    • Filter Effects
    • Save Particle and Filter Effects as Macro
    • Clear Particle and Filter Effects
  • Developer API
    • Filter Effects
      • Available Filter Effects With Supported Options
    • Particle Effects
      • Available Particle Effects With Supported Options
      • Particle Effect Options
    • Special Effects
      • Playing a Video File on the Canvas
      • Retrieving Effect Presets
      • Playing a Video File Between Two Tokens
      • Animation Easing
    • Adding Your Own Special Effects to FXMaster
  • Contributing
  • Acknowledgement
  • Licensing

Installation Instructions

To install FXMaster, find FXMaster in the module browser, or paste the following URL into the Install Module dialog in the Setup menu of Foundry Virtual Tabletop:

https://github.com/ghost-fvtt/fxmaster/releases/latest/download/module.json

FAQ

• Q: I have put a special effect onto a scene, and now I can't get rid of it anymore. How do I remove it?

  A: Most likely, your created a permanently playing special effect by dragging a special effect onto the canvas, which is just a regular Tile and not managed by FXMaster. To remove it, go to the Tile Controls and remove the Tile there.

• Q: What is the difference between Particle Effects, Filter Effects, and Special Effects?

  A: Particle Effects are global effects that display particles on the whole scene. Mostly they are weather effects, but they also include animals and some other effects.
  Filter Effects are filters that adjust the whole scene in some way, e.g. by adjusting the color or distorting the scene to look like it's underwater.
  Special Effects are animations (video files) that can be played on your chosen location on the canvas.

• Q: Can I provide my own effects?

  A: You can provide your own Special Effects, as described in Managing Custom Special Effects. It's not possible to provide your own Particle Effects or Filter Effects at this point.

• Q: I have installed a module that provides additional animation files, but they are not showing up as Special Effects. What do I need to do?

  A: Some of these modules (e.g. JB2A) provide a setting to activate their integration with FXMaster, which is disabled by default. You can enable that setting in the module settings. If there is no such setting, the module may not provide direct integration with FXMaster. In that case, you can still use the animation files provided by the module, but you need to configure them by yourself as described in Managing Custom Special Effects.

Usage

The functionality of FXMaster can be accessed via the Effect Controls () in the scene controls. Each individual functionality of FXMaster has its own tool inside this scene control.

Special Effects

Special Effects are essentially video files that can be played on the canvas via clicking or dragging. FXMaster includes only a couple of example effects. If you want more, you will need to install a module providing animation files like JB2A, Jinker's Animated Art, or Jack Kerouac's Animated Spell Effects. All of them integrate with FXMaster. Alternatively, you can also add your own Special Effects.

Clicking on this tool opens the Special Effects Management dialog:

In this dialog, you can see folders containing different sets of Special Effects. By clicking on a folder, you expand it:

You can preview the effects by hovering over the black box with your mouse.

Predefined Special Effects have a clone icon () on the right. By clicking it, you open a dialog to create a custom Special Effect, prefilled with the data from this Special Effect. For more information on creating custom Special Effects, see Managing Custom Special Effects.

Playing Special Effects

In order to play a special effect, simply select it from the list and click on the canvas while having the Effects Controls active (it doesn't work if you have any other control such as the Token Controls active). Alternatively, you can drag on the canvas, which shows a red line from the start point to your mouse pointer. Releasing the mouse button then results in the effect being played, facing the direction you dragged towards. Depending on the selected Cast Mode, the Special Effect might also move or scale towards that direction.

You can also create permanently playing variants of Special Effects. In order to do so, simply drag the Special Effect from the Special Effects Management onto the scene. This creates a Tile with the video of the Special Effect. The Tile is not managed by FXMaster, it is just a regular Foundry Core Tile. In particular, this means that, in order to move, resize, or adjust it in any other way, or also to remove it, you need to go to the Tile Controls and perform the desired action there.

Elevation

The elevation input field in the top row of the Special Effects Management allows you to specify at which elevation Special Effects are being played. The default elevation is 1, which is just above the default elevation of tokens, tiles, and drawings (they sit at 0, by default).

Cast Modes

The first five icons in the top row of the Special Effects Management provide a way to switch between the different Cast Modes for Special Effects, simply by clicking on them. Here is an overview of the available modes:

Cast Mode	Icon	Description
Face Target		Special Effects face towards the target.
Move to Target		Special Effects face and move towards the target.
Extend to Target		Special Effects face towards the target and extend to it.
Expand to Target		Special Effects face towards the target and expand to it, scaling the whole effect up while keeping the aspect ratio.
Rotate		Special Effects rotate clockwise. The dragged distance specifies the rotation speed.

Managing Custom Special Effects

Custom Special Effects can be added in two ways: By cloning a predefined one as explained above, or by clicking the plus icon () in the top row of the Special Effects Management. In both cases, a dialog to create a new custom Special Effect is opened:

In this dialog, you can choose the name of the Special Effect, specify the folder it should be created in (you can also specify a new folder name), select the video file to use, and configure the various options. Once you are done, hit the “Save Changes” button to save the Special Effect and close the dialog.

Instead of the clone icon that predefined Special Effects have, custom ones have edit () and delete () icons. Clicking the edit icon opens the dialog to create a custom Special Effect, prefilled with the data from this one. You can overwrite the existing one by keeping the name and folder the same. Clicking the delete icon simply deletes the Special Effect.

Particle Effects

Particle Effects are global effects that are displayed all across the scene. They include weather effects like rain, fog, clouds, and snow, but also other global particle effects such as birds flying across the scene or spiders crawling around.

Clicking on this tool opens the Particle Effects Management dialog:

In this dialog, you can configure individual Particle Effects. They are sorted into different groups (“Animals”, “Other”, and “Weather”). By clicking on a group, you expand it, showing all effects in that group:

You can activate individual Particle Effects by checking the corresponding checkbox and then clicking on “Save Changes”.

By clicking on the name of a Particle Effect, you expand it, showing the options for that effect:

The available options differ slightly between Particle Effects because not all options make sense for all of them. The options are:

Option	Description
Scale	A factor that scales the effect relative to its base size.
Direction	The direction of the effect in degrees.
Speed	A factor that adjusts the speed of the effect relative to its base speed.
Lifetime	A factor that adjusts the lifetime of the individual particles.
Density	The density of the effect. For most effects, it represents the number of particles per grid unit.
Opacity	A factor between 0 and 1 that adjusts the opacity of the particles.
Tint	Tint the effect with this color.
Animations	A selection of animations from the list of animations for the effect to use. If it is empty, the default animation is used.

Once you are finished with adjusting the options, you can apply them by clicking the “Save Changes” button.

Masking Particle Effects

By default, Particle Effects are displayed all across the entire scene. However, it is possible to constrain them to specific areas. This can be achieved by creating drawings and then marking them as Particle Effect Mask. To do that, open the HUD for the drawing (by right-clicking the drawing) and then click on the “Mask FXMaster Particle Effects” control icon () on the left of the drawing HUD:

You can mark as many drawings as mask as you want.

By default, the Particle Effects are only displayed outside the marked areas. This can be inverted via the Invert Particle Effect Mask tool.

⚠ Warning Regarding Large Scenes

Similar to the foundry core weather effects, the Particle Effects provided by FXMaster can have a pretty significant impact on performance in large scenes (around 10,000 px × 10,000 px and larger). Be careful when enabling Particle Effects in such scenes as it might make them crash. If that happens, launch the world in safe configuration and delete the configured Particle Effects for the scene by running the following as a script macro or in the developer console (F12):

canvas.scene.unsetFlag("fxmaster", "effects");

You can then safely reactivate your modules.

Invert Particle Effect Mask

Clicking on this tool inverts the Particle Effect Mask for the current scene. This tool acts as a toggle and the color indicates whether it is currently active or not.

Inverting the Particle Effect Mask can be very useful when the goal is to display Particle Effects only in specific smaller areas, instead of specifying the areas in which they should not be displayed, which is the default.

Filter Effects

Filter Effects work similarly to Particle Effects. They are also displayed all across the entire scene but unlike Particle Effects it's not possible to confine them to certain areas with a mask.

Clicking on this tool open the Filter Effects Management dialog:

You can activate individual Filter Effects by checking the corresponding checkbox and then clicking on “Save Changes”.

By clicking on the name of a Filter Effect, you expand it, showing the options for that effect:

The available options differ heavily between individual Filter Effects, so it doesn't make much sense to list them here.

Once you are finished with adjusting the options, you can apply them by clicking the “Save Changes” button.

Save Particle and Filter Effects as Macro

This tool allows you to create a macro from the currently active Particle Effects and Filter Effects. When clicking this tool, a macro is created in the macro directory. It's not put into the hotbar, so you need to drag it there yourself if you want to.

When executed, the macro sets the Particle Effects and Filter Effects of the current scene to the state from when the macro was created.

Clear Particle and Filter Effects

When clicked, this tool shows a confirmation dialog to delete all Particle Effects and Filter Effects from the current scene.

Developer API

FXMaster provides functionality to interact with Filter Effects, Particle Effects, and Special Effects from other packages and macros.

Filter Effects

• Adding or updating a named filter

  FXMASTER.filters.addFilter("myfilterID", "color", {
    color: { value: "#ff00ff", apply: true },
    gamma: 1.0,
    contrast: 1.0,
    brightness: 1.0,
    saturation: 0.2,
  });

• Removing a named filter

  FXMASTER.filters.removeFilter("myfilterID");

• Toggling a named filter on and off

  FXMASTER.filters.switch("myfilterID", "color", {
    color: { value: "#ff00ff", apply: true },
    gamma: 1.0,
    contrast: 1.0,
    brightness: 1.0,
    saturation: 0.2,
  });

• Setting the list of active filters

  FXMASTER.filters.setFilters([
    {
      type: "color",
      options: {
        /* ... */
      },
    },
    {
      type: "lightning",
      options: {
        /* ... */
      },
    },
  ]);

Available Filter Effects With Supported Options

Type	Options
lightning	frequency, spark_duration, brightness
underwater	speed, scale
predator	noise, period, lineWidth
color	color, saturation, contrast, brightness, gamma
bloom	blur, bloomScale, threshold
oldfilm	sepia, noise

You can get a complete list by typing CONFIG.fxmaster.filters in your web console.

Particle Effects

• Switching a named particle effect on and off:

  Hooks.call("fxmaster.switchParticleEffect", {
    name: "myParticleEffectID",
    type: "rain",
    options: { density: 0.5 },
  });

• Setting the active paticle effects:

  Hooks.call("fxmaster.updateParticleEffects", [
    {
      type: "rain",
      options: {
        /* ... */
      },
    },
    {
      type: "bubbles",
      options: {
        /* ... */
      },
    },
  ]);

Available Particle Effects With Supported Options

Type	scale	direction	speed	lifetime	density	alpha	tint	animations
snowstorm	✓	✓	✓	✓	✓	✓	✓
bubbles	✓		✓	✓	✓	✓	✓
clouds	✓	✓	✓	✓		✓	✓
embers	✓		✓	✓	✓	✓	✓
rainsimple	✓	✓	✓	✓	✓	✓	✓
stars	✓		✓	✓	✓	✓	✓
crows	✓		✓	✓	✓	✓	✓
bats	✓		✓	✓	✓	✓	✓
spiders	✓		✓	✓	✓	✓	✓
fog	✓		✓	✓	✓	✓	✓
raintop	✓	✓	✓	✓	✓	✓	✓
birds	✓		✓	✓	✓	✓	✓	✓ (glide, flap, mixed)
leaves	✓		✓	✓	✓	✓	✓
rain	✓	✓	✓	✓	✓	✓	✓
snow	✓	✓	✓	✓	✓	✓	✓
eagles	✓		✓	✓	✓	✓	✓	✓ (glide, flap)

Particle Effect Options

Option	Type	Description
scale	number	A factor that scales the effect relative to its base size.
direction	number	The direction of the effect in degrees.
speed	number	A factor that adjusts the speed of the effect relative to its base speed.
lieftime	number	A factor that adjusts the lifetime of the individual particles.
density	number	The density of the effect. For most effects, it represents the number of particles per grid unit.
alpha	number	A factor between 0 and 1 that adjusts the opacity of the particles (this is called “Opacity” in the Particle Effects Management).
tint	{value: string, apply: boolean}	Tint the effect with this color.
animations	string[]	An array of animations from list of animations for the effect to use. If it is empty or not defined, the default animation is used.

Special Effects

Special effects are essentially temporary video files that are being played on the canvas. They are defined by several parameters:

Parameter	Type	Description
file	string	The video file path.
anchor	{x: number, y: number}	The starting point of the effect. x and y are values between 0 and 1.0, representing fractions of the width and height of the video file.
position	{x: number, y: number}	The position at which the anchor of the effect is to be placed.
angle	number	The initial direction of the effect in degrees. The default assumption is that the effect direction from left to right. If that's not the case, you need to set this value accordingly.
speed	number | "auto"	The speed at which the effect plays and moves.
scale	{x: number, y: number}	The scale of the effect. x and y are numbers between 0 and 1, representing by how much the width and height of the effect are scaled.
animationDelay	{start: number, end: number}	Delays before and after the effect plays (if speed > 0).
ease	string	The easing function to use in order for the movement animation to look more natural. You can find the valid values in easeFunctions in ease.js.
width	number	Sets the width of the sprite. For example, this can be used to stretch a beam towards a specific target.
elevation	number	Sets the elevation at which the effect is played.

Playing a Video File on the Canvas

const data = {
  file: "myfile.webm",
  position: {
    x: 1200,
    y: 1200,
  },
  anchor: {
    x: 0,
    y: 1,
  },
  angle: 90,
  speed: 0,
  scale: {
    x: 0.7,
    y: 0.7,
  },
};
canvas.specials.playVideo(data);
game.socket.emit("module.fxmaster", data);

Retrieving Effect Presets

From module presets

const effectData = CONFIG.fxmaster.specialEffects.fxmaster.effects.find((ef) => ef.label === "Blood Splatter");

From custom presets

const effectData = CONFIG.fxmaster.specialEffects.custom.effects.find((ef) => ef.label === "Energy Circle");

Playing a Video File Between Two Tokens

You can use the canvas.specials.drawSpecialToward method with the speed set to "auto" to adapt the speed so that the video ends when the target is reached.

function castSpell(effect) {
  const tokens = canvas.tokens.controlled;
  if (tokens.length == 0) {
    ui.notifications.error("Please select a token");
    return;
  }
  game.user.targets.forEach((i, t) => {
    canvas.specials.drawSpecialToward(effect, tokens[0], t);
  });
}

castSpell({
  file: "modules/fxmaster/assets/specialEffects/jinker/dragonBornBlack-CopperAcid30x5Line.webm",
  anchor: {
    x: -0.08,
    y: 0.5,
  },
  speed: "auto",
  angle: 0,
  scale: {
    x: 1,
    y: 1,
  },
});

Animation Easing

You can customize the canvas.specials.drawSpecialToward to ease the animation toward the target. Here is some example data. The easing options are given in the ease.js file.

{
  file: "modules/fxmaster/assets/specialEffects/jinker/dragonBornBlack-CopperAcid30x5Line.webm",
    anchor: {
      x: -.08,
      y: 0.5
    },
  speed: "auto",
  angle: 0,
  scale: {
    x: 1,
    y: 1
  }
  animationDelay: {
    start: 0.5,
    end: 0.2
  },
  ease: "InCirc"
}

Adding Your Own Special Effects to FXMaster

Here is a demo module you can use as a template: FoundryVTT FXMaster Specials Demo Template.

In one file, you configure each of your special effects:

export const effects = {
  label: "MYMODULE",
  effects: [
    {
      label: "Smoke Bomb",
      file: "modules/fxmaster/assets/specialEffects/fxmaster/smokeBomb.webm",
      scale: {
        x: 1.0,
        y: 1.0,
      },
      angle: 0,
      anchor: {
        x: 0.5,
        y: 0.5,
      },
      speed: 0,
      author: "U~man",
    },
  ],
};

Then, in a second file, you add the previously created effects by merging them into the CONFIG.fxmaster.specialEffects object as follows:

import { effects } from "./effects.js";

Hooks.once("init", function () {
  // Adding special effects
  if (!CONFIG.fxmaster) CONFIG.fxmaster = {};
  foundry.utils.mergeObject(CONFIG.fxmaster, { specialEffects: { MYMODULE: effects } });
});

The effects should now appear in the Specials selection dialog.

Contributing

Code and content contributions are accepted. Please feel free to submit issues to the issue tracker or submit pull requests for code changes.

Acknowledgement

Many thanks to:

• U~man for the original work on this module. Really, most of this is his work.
• theripper93 for contributing his ideas regarding handling particle effect masking elegantly.
• Wasp for providing the Sequencer module that will inspire future updates.
• SecretFire for exchanging ideas, providing help, and shaders for the filter effects. Donate here.

Licensing

• The software component of FXMaster is licensed under BSD 3-Clause.
• Jinker's Acid Line and Red Fire Cone video effects are borrowed from Jinker's Animated Art and are licensed as free for use.
• Jules and Ben's Witch Bolt effect is from JB2A and is licensed under CC BY-NC-SA-4.0.
• The Seagull sprites used in the Birds particle effect are from whtdragon.
• The control and tool icons are from Font Awesome, licensed under the CC BY-4.0.
• The icons for particle effects are by Rexard and licensed under Rexard Game Dev Assets EULA.
• The rat sprites used in the Rats particle effect by crymoonster are licensed under CC BY-4.0.