Gambit's FXMaster

Supporting The Module

---

Welcome to the official release of FXMaster V7! This is a massive overhaul of Filters which have essentially been re-built from the ground up. Scene Filters can now be masked by regions, and Filters can be played directly within Regions. To allow making filters look more realistic, there is a new Edge Fade % parameter that will gradually fade a given effect to the region borders. Beyond Filter exclusive functionality, regions have been given much more flexibility by allowing elevation restrictions for both Particles and Filters. This will be super helpful for users of the Levels module, and more generally the upcoming Foundry V14 core levels integration. Particles and Filters have also received another often requested feature, the ability to place tokens above or below a given effect. Finally, many Particles and Filters have seen tweaks and functionality enhancements in V7. One special callout is the Lightning Filter effect, which now has a Thunder aware mode to sync lightning flashes up with Thunder sounds.

Any support via the Patreon or Ko-fi is greatly appreciated! If you are a Patreon subscriber you will receive access to the FXMaster+ module. FXMaster+ can be accessed from Patreon, and it's where I will be adding new particle effects and filters moving forward. For the month of September, it will get you access to the 🟢 Ghosts, 🟡 Sunlight, 🟢 Magic Crystals, 🟡 Fireflies, 🌸 Sakura Bloom, 🌸 Sakura Blossoms — Particle Effects previewed below:

ghosts.mp4

Sunlight (click to expand)

sunlight.mp4

Magic Crystals (click to expand)

magiccrystals.mp4

Fireflies (click to expand)

fireflies.mp4

Sakura Bloom (click to expand)

sakura-effect.mp4

---

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, lightning, and more.
• Animation 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
    • Animation Effects  
      • Placing Animation Effects
      • Managing Animation Effects
    • Particle Effects  
      • Particle Effects via Region Behavior
      • Masking Particle Effects
      • ⚠ Warning Regarding Large Scenes
    • Filter Effects  
      • Filter Effects via Region Behavior
      • Masking Filter Effects
    • Save Particle and Filter Effects as a 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
  • 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/gambit07/fxmaster/releases/latest/download/module.json

FAQ

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

  A: Most likely, you created a permanently playing animation effect by dragging an animation 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 Animation 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.
  Animation 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 Animation Effects via the Custom folder in the module's settings. It's not possible to provide your own Particle Effects or Filter Effects.

Usage

The functionality of FXMaster can be accessed via Effect Controls in scene controls. Each FXMaster app has its own tool inside scene controls.

Animation Effects  

Animation Effects are video files that can be previewed and/or placed on the canvas via clicking and dragging. FXMaster aggregates animations from popular animation module providers including: JB2A, Jinker's Animated Art, Jack Kerouac's Animated Spell Effects, Jack Kerouac's Animated Spell Effects Cartoon, Boss Loot Animated Assets, and Wild Magic Surge. Along side the built in module support, you can also add your own Custom folder of animations from the modules settings.

On first world load after updating or installing FXMaster, the animation effects database will be built. You will see an active UI notification window while this process runs. It can take anywhere from 5 to 10 minutes depending on how many animations exist in your world. Once the process completes, you are ready to use the Animation Effects window. If you ever add or remove animations, either from a Custom folder or an Animation module, you can re-build the animations database at any time via the Settings menu option "Refresh Animations Database."

Clicking on this tool opens the Animation Effects Management app:

In this app, you can filter based on specific animation providers and search for specific animations. Searching supports advanced queries using AND, OR, and NOT, e.g.: (eldritch OR arrow) AND NOT blast

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

Placing Animation Effects

In order to place an Animation Effect, simply drag it from the window to the canvas which will create a Tile on the canvas that includes your animation.

Managing Animation Effects

Animation Effects details can be viewed by right clicking an animation icon in the window. Details included are the Author, File Name, File Path, and Sequencer Path. Additionally, you can adjust the Scale and Anchor of a placed tile within this menu. Finally, you can Favorite an animation within this window, which will create a Favorites tag in the main window dropdown. If you make a change, hit the "Save Changes" button to save the Animation Effect and close the app.

Particle Effects  

Particle Effects 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.

There are two ways to implement Particle Effects: via the Effect Controls menu for global Particle Effects, or via a Region using the FXMaster: Particle Effects Region behavior.

Particle Effects via Effect Controls App

Clicking on the Effect Controls tool opens the Particle Effects Management app:

In this app, you can configure individual Particle Effects. They are sorted into different groups ("Weather", "Ambient", and "Animals").

You can activate individual Particle Effects by clicking the corresponding toggle button.

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

Particle Effects via Region Behavior

After adding a Region, open the Region config menu and navigate to the Behaviors tab. Add a new behavior and select the option 'FXMaster: Particle Effects':

In this menu, you can configure individual Particle Effects in the same way as in the main app, and add region elevation visibility handling. Selecting the checkbox next to a Particle Effect will display a dropdown of its options. Saving the Region behavior will add the selected Particle Effects to the region. For region elevation, use the Elevation Constraints dropdown.

None - No elevation restrictions are considered. Tokens POV - Visibility will be restricted to a given tokens POV. For example, if the region elevation bottom is set to 10 feet, and region elevation top is set to 20 feet, the particle effect will be visible to the token while their elevation is between 10 and 20 feet. If the region elevation bottom is set to 10 feet, and region elevation top is infinite, the particle effect will be visible to the token while their elevation is 10 feet or above. If the region elevation bottom is infinite, and region elevation top is 20, the particle effect will be visible to the token while their elevation is 20 feet or below. Specific Tokens POV - Same visibility as Tokens POV, but only allows that visibility based on Token UUID's entered. Any Token UUID not entered will not be able to see the particle effect.

Always Visible for GM - Ignores Tokens POV for GM and makes the effect always visible.

In addition, you can subscribe the Particle Region behavior to the Token Enters and Token Exits events. These events can work in concert with the Elevation Constraints options, or on their own.

Token Enters: Effect becomes visible when a token enters the bounds of the region. This event can be paired with Token Exits to turn an effect on and off when a token moves in/out. Alternatively, you can only add the Token Enters event, in which case the effect will become visible once a token enters, and remain visible even if they exit. Token Exits: Effect becomes not visible when a token exits the bounds of the region.

Masking Particle Effects

By default, Particle Effects added via the app are displayed across the entire scene. However, it is possible to mask them from specific areas. This can be achieved within Regions by using the Region behavior "Suppress Weather" or "FXMaster: Suppress Scene Particles". "Suppress Weather" masks all Particle and Filter effects along with core Foundry effects, "FXMaster: Suppress Scene Particles" only masks FXMaster Particle Effects.

Particle Effects are only displayed outside the region areas when masked. If a Hole shape is added to the region, scene particle effects will display in the hole area cutout.

⚠ Warning Regarding Large Scenes

The Particle Effects provided by FXMaster can have a pretty significant impact on performance, primarily due to the amount of customization FXMaster offers. Increasing density and particle size particularly in large scenes (around 10,000 px × 10,000 px and larger) can be very costly. 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. When creating Particle Effects on large scenes like the above, try to limit density and size as much as possible for a more performant experience.

Filter Effects  

Filter Effects include effects that change the underlying scene visuals in some way like altering the color, displaying an old film effect, or adding underwater displacement. There are two ways to implement Filter Effects: via the Effect Controls menu for global Filter Effects, or via a Region using the FXMaster: Filter Effects Region behavior.

Filter Effects via Effect Controls App

Clicking on this tool opens the Filter Effects Management app:

You can activate individual Filter Effects by clicking the corresponding toggle button.

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.

The options will be adjusted in real-time as you make changes to them.

Filter Effects via Region Behavior

After adding a Region, open the Region config menu and navigate to the Behaviors tab. Add a new behavior and select the option 'FXMaster: Filter Effects':

In this menu, you can configure individual Filter Effects in the same way as in the main app, and add region elevation visibility handling. Selecting the checkbox next to a Filter Effect will display a dropdown of its options. Saving the Region behavior will add the selected Filter Effects to the region. For region elevation, use the Elevation Constraints dropdown.

None - No elevation restrictions are considered.
Tokens POV - Visibility will be restricted to a given tokens POV. For example, if the region elevation bottom is set to 10 feet, and region elevation top is set to 20 feet, the filter effect will be visible to the token while their elevation is between 10 and 20 feet. If the region elevation bottom is set to 10 feet, and region elevation top is infinite, the filter effect will be visible to the token while their elevation is 10 feet or above. If the region elevation bottom is infinite, and region elevation top is 20, the filter effect will be visible to the token while their elevation is 20 feet or below.
Specific Tokens POV - Same visibility as Tokens POV, but only allows that visibility based on Token UUID's entered. Any Token UUID not entered will not be able to see the filter effect.

Always Visible for GM - Ignores Tokens POV for GM and makes the effect always visible.

In addition, you can subscribe the Filter Region behavior to the Token Enters and Token Exits events. These events can work in concert with the Elevation Constraints options, or on their own.

Token Enters: Effect becomes visible when a token enters the bounds of the region. This event can be paired with Token Exits to turn an effect on and off when a token moves in/out. Alternatively, you can only add the Token Enters event, in which case the effect will become visible once a token enters, and remain visible even if they exit.
Token Exits: Effect becomes not visible when a token exits the bounds of the region.

Masking Filter Effects

By default, Filter Effects added via the scene app are displayed across the entire scene. However, it is possible to mask them from specific areas. This can be achieved within Regions by using the Region behavior "Suppress Weather" or "FXMaster: Suppress Scene Filters". "Suppress Weather" masks all Particle and Filter effects along with core Foundry effects, "FXMaster: Suppress Scene Filters" only masks FXMaster Filter Effects.

Filter Effects are only displayed outside the region areas when masked. If a Hole shape is added to the region, scene filter effects will display in the hole area cutout.

Save Particle and Filter Effects as a 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 onto 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 they were in 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 and Particle 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	belowTokens, frequency, spark_duration, brightness, audioAware, audioBassThreshold, audioChannels
underwater	belowTokens, speed, scale
predator	belowTokens, noise, period, lineWidth
color	belowTokens, color, saturation, contrast, brightness, gamma
bloom	belowTokens, blur, bloomScale, threshold
oldfilm	belowTokens, sepia, noise, noiseSize, scratch, scratchDensity

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	FXMaster+	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)
rats		✓		✓	✓	✓	✓	✓
sakurabloom	✓	✓	✓	✓	✓	✓	✓	✓
sakurablossom	✓	✓		✓	✓	✓	✓	✓
fireflies	✓	✓		✓	✓	✓	✓	✓

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

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.
• ghost for maintaining functionality on this module for the past few years.
• theripper93 for contributing his ideas regarding handling particle effect masking elegantly.
• Wasp for providing the Sequencer module.
• 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.
• 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.