Gambit's FXMaster

Supporting The Module

Welcome to the official release of FXMaster V8! This release brings brand new handling for V14 Scene Levels, new Manage Layers functionality to order particle and filter effects, new macro API with improved flexibility, and more! Hope everyone enjoys!

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 May, it will get you access to the 🟢Summer Leaves, 🟡Fire, 🟢Aurora Borealis, ⚪Wind, ⚪Wind Wisp, 🔵Water, 🟡Lightning Bolts, 🔵Fish, 🟢Glitch, 🔵Ice, 🟤Duststorm, 🟤Sandstorm, 🟢Ghosts, 🟡Sunlight, 🟢Magic Crystals, 🟡Fireflies, 🌸Sakura Bloom, and 🌸Sakura Blossoms Effects - Effects are previewed below:

_p0` / `apiPreset__f0`, which will show up here if you ever need to inspect or remove them manually. ### 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 dialog allows you to name the macro, and toggle optionals for a Play or Toggle macro as well as Skip Fading true/false parameter. A macro is created in the macro directory after saving. It's not put onto the hotbar, so you need to drag it there yourself if you'd like 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. ## Levels   When using native Scene Levels in Foundry V14+, scene-wide _Particle Effects_ and _Filter Effects_ can be limited to specific Levels instead of rendering across the whole scene. This makes it possible to keep an effect on only the selected floor or floors while other Levels remain unaffected. ### Using Levels with Scene Effects In the _Particle Effects Management_ and _Filter Effects Management_ apps, scene-wide effects include a **Levels** selector. - **All Levels** - The effect renders everywhere it normally would on the current scene. - **One or more specific Levels** - The effect is restricted to the selected Scene Levels. This Level restriction can be combined with other FXMaster routing options such as **Below Tokens**, **Below Tiles**, and **Below Foreground**. Native tile, foreground, and supported suppression behavior are still respected after the Level restriction is applied. **Notes** - The **Levels** selector is intended for scene-wide effects added through the FXMaster management apps. - Region-based FXMaster effects follow the Region's own placement, assigned levels, and elevation visibility handling. - On scenes that do not use multiple native Scene Levels, scene-wide effects behave as normal global effects. ## Layers   The _Manage Layers_ window is used to control the render order of enabled FXMaster effects. It allows scene-wide, region-based, and API-created effects to be mixed together in a single stack so you can decide which effects render above or below the others. ### Manage Layers Window  To open: **Scene Controls → FXMaster Controls → Manage Layers** (layer-group icon). The window lists every currently enabled _Particle Effect_ and _Filter Effect_ that participates in FXMaster's scene compositor. What it shows: - **Order** - The current top-to-bottom render order. Higher entries in the list render above lower entries. - **Effect** - The effect name and whether it is a _Particle_ or _Filter_ effect. - **Source** - Where the effect came from. - **Scene** - Added directly through the main FXMaster management apps. - **Region** - Added by an FXMaster Region behavior. - **API** - Added programmatically by an API call. - **API - Preset** - Added by the Presets API. - **API - Macro** - Added by a saved FXMaster macro or other macro-style API playback. - **Owner** - The Scene or Region that owns the effect. - **Level** - On scenes using multiple native Levels, this column shows which Scene Level or Levels the effect is currently limited to if relevant. Actions: - **Move Up / Move Down** - Reorder an effect in the stack. - **Reset Order** - Restore the default FXMaster stack order for the current scene. **Notes** - The Foundry Grid can be added as part of the Layer stack by turning on the FXMaster setting "Include Foundry Grid in FX Stack". This will allow placing effects over or under the grid within the Layers manager, can give a greater sense of depth to certain particles when on a gridded scene. - Layer order is separate from **Below Tokens**, **Below Tiles**, and **Below Foreground**. Those options still control whether an effect appears underneath those scene elements, while the Layers window controls the order between FXMaster effects themselves. - Effects added later will appear in the list automatically with highest priority and can be reordered at any time. - The **Level** column is informational. To change which Level an effect uses, edit the effect in its manager or Region behavior. ## Developer API FXMaster exposes three supported global APIs for macros and third-party packages: ```js FXMASTER.api FXMASTER.api.presets FXMASTER.api.effects ``` > **Tip:** Call these after the world is ready (for example inside `Hooks.once("ready", ...)`) so `FXMASTER` and `CONFIG.fxmaster` are initialized. FXMaster contains three high level api commands to stop or start effects on a given scene. ```js // Stop all scene effects on a given scene. await FXMASTER.api.stopSceneEffects({ scene: canvas.scene, skipFading: true }); // Stop all region effects on a given scene. Note: This will not delete FXMaster region behaviors, it disables any FXMaster region behavior await FXMASTER.api.stopRegionEffects({ scene: canvas.scene, skipFading: true }); // Start all region effects on a given scene. Note: This will re-enable existing region effects that have been disabled await FXMASTER.api.startRegionEffects({ scene: canvas.scene, skipFading: true }); ``` ### Presets API FXMaster’s _Presets API_ applies curated, scene-wide environment effects by name. A preset can include multiple _Particle Effects_ and _Filter Effects_, and FXMaster resolves the best available preset variant automatically: - If **FXMaster+** is active and a preset has an FXMaster+ variant, that tier is preferred. - Otherwise, the core FXMaster variant is used when available. #### Accessing the Presets API ```js FXMASTER.api.presets ``` #### Common preset operations ```js // Play or update a preset on the current scene await FXMASTER.api.presets.play("sunshower", { direction: "north", density: "high", belowForeground: false, }); // Toggle a preset on or off await FXMASTER.api.presets.toggle("blizzard", { topDown: true, soundFx: true, }); // Stop a preset await FXMASTER.api.presets.stop("blizzard"); // Stop any active API preset, then play the requested preset await FXMASTER.api.presets.switch("acid-rain"); // Introspection helpers console.log(FXMASTER.api.presets.list()); console.log(FXMASTER.api.presets.listValid()); console.log(FXMASTER.api.presets.listActive()); console.log(FXMASTER.api.presets.listActive({ scene: "Scene.abc123" })); ``` #### Preset options All preset methods accept an optional `opts` object. | Option | Type | Default | Description | | --- | --- | --- | --- | | `topDown` | `boolean` | `false` | Prefer the preset’s top-down variant when one exists. | | `direction` | `string \| number` | - | Override the preset direction. Supports compass strings such as `"n"`, `"ne"`, `"north"`, `"southwest"`, plus `"up"`, `"down"`, `"left"`, `"right"`, or a numeric degree value. | | `color` | `string` | - | Hex color override such as `#88ccff` or `#8cf`. FXMaster only applies it when the preset effect supports a tint/color parameter. | | `speed` | `"very-low" \| "low" \| "medium" \| "high" \| "very-high" \| number` | - | Relative speed override or explicit numeric multiplier. | | `density` | `"very-low" \| "low" \| "medium" \| "high" \| "very-high" \| number` | - | Relative density override or explicit numeric multiplier. | | `belowTokens` | `boolean` | - | Override whether the preset renders below tokens. | | `belowTiles` | `boolean` | `false` | Override whether the preset renders below tiles. | | `belowForeground` | `boolean` | `false` | Override whether the preset renders below foreground coverage. | | `darknessActivationEnabled` | `boolean` | - | Explicitly enable or disable darkness activation. | | `darknessActivationMin` | `number` | - | Minimum scene darkness level for the preset’s activation range. | | `darknessActivationMax` | `number` | - | Maximum scene darkness level for the preset’s activation range. | | `soundFx` | `boolean` | - | Enable or disable preset-linked Sound FX when **FXMaster+** is active. | | `levels` | `string \| number \| Array` | - | Restrict the preset to one or more native Scene Levels by id or name. Invalid selections fall back to all levels. | | `scene` | `Scene \| string` | current scene | Target Scene document or Scene UUID. | | `splash` | `boolean` | `true` | Enable or disable rain splash particles when a preset includes Rain. | | `silent` | `boolean` | `true` | Suppress UI warning notifications for missing presets or invalid override values. | #### Notes - Presets created by this API are stored on the Scene using keys that start with `apiPreset_...`. They do **not** modify FXMaster’s `core_*` scene entries or effects created by other modules. - `FXMASTER.api.presets.switch(name, opts)` stops any active API-managed presets before playing the requested one. If `name` is omitted or falsy, it only stops active API presets. - `FXMASTER.api.presets.hasFxmaster()` and `FXMASTER.api.presets.hasFxmasterPlus()` are available when a macro needs to check the active module tier. - API-created preset rows can be inspected and removed from the **API Effects UI Manager**. ### Effects API FXMaster’s _Effects API_ adds arbitrary scene-wide _Particle Effects_ and _Filter Effects_ without replacing FXMaster’s built-in scene manager state. API-created rows appear in the **API Effects UI Manager**, can be layered with the rest of the FX stack, and can be removed by id, by exact payload match, or through a toggle group. #### Accessing the Effects API ```js FXMASTER.api.effects ``` Available methods: ```js FXMASTER.api.effects.play(...) FXMASTER.api.effects.stop(...) FXMASTER.api.effects.toggle(...) FXMASTER.api.effects.particles.stop(...) FXMASTER.api.effects.particles.toggle(...) FXMASTER.api.effects.filters.stop(...) FXMASTER.api.effects.filters.toggle(...) ``` > **Note:** There is no scoped `play` helper. Use `FXMASTER.api.effects.play({ particles: [...] })` or `FXMASTER.api.effects.play({ filters: [...] })` when you only want one effect kind. The easiest way to capture an exact `options` payload is to configure an effect in the FXMaster UI and save it as a macro, or inspect an API-created row in the **API Effects UI Manager**. #### Effect entry shape Use `effects` when you want a mixed, ordered list of particles and filters. Each entry in `effects` must include `kind`. ```js const mixedEffects = [ { kind: "filter", type: "color", options: { belowTokens: false, color: { value: "#9cc8ff", apply: true }, saturation: 0.1, contrast: 1.05, }, }, { kind: "particle", type: "rain", options: { direction: 90, density: 0.15, speed: 1, }, }, ]; ``` Use `particles` or `filters` when you only want a single effect kind. In those arrays, `kind` is implied and can be omitted. ```js const particles = [ { type: "snow", options: { direction: 110, density: 0.12, speed: 0.9 } }, ]; const filters = [ { type: "underwater", options: { speed: 0.5, scale: 1.2 } }, ]; ``` Each effect entry can also include `id` or `effectId` for a stable API-managed id. FXMaster preserves explicit ids only when they use the API id namespace (for example `apiMacro_myStorm_p` or `apiMacro_myStorm_f`); otherwise it generates a new id automatically. Saved FXMaster macros use this pattern for static stop samples. Any effect `options` object may also include `levels` to restrict that effect to one or more native Scene Levels. #### Effects API arguments | Field | Used by | Description | | --- | --- | --- | | `effects` | `play`, `stop`, `toggle` | Ordered mixed array of effect entries. Use this when you want to mix particles and filters and preserve the requested FX stack order from top to bottom. | | `particles` | `play`, `stop`, `toggle` | Particle-only array. For `play` and `toggle`, entries are particle definitions. For `stop`, entries may be ids, UIDs, or full particle payloads. | | `filters` | `play`, `stop`, `toggle` | Filter-only array. For `play` and `toggle`, entries are filter definitions. For `stop`, entries may be ids, UIDs, or full filter payloads. | | `scene` | all methods | Target Scene document or Scene UUID. Defaults to the current scene. | | `skipFading` | `play`, `stop`, `toggle` | When `true`, FXMaster applies or removes particles and filters immediately instead of fading them in or out. | | `toggleKey` | `toggle` | Stable key used to associate repeated toggle calls with the same API-managed group. Aliases `key`, `id`, and `name` are also accepted. | #### Play, stop, and toggle Play a mixed, ordered set of effects and capture the ids that were created: ```js const ids = await FXMASTER.api.effects.play({ effects: [ { kind: "filter", type: "color", options: { color: { value: "#9cc8ff", apply: true }, saturation: 0.1, contrast: 1.05, }, }, { kind: "particle", type: "rain", options: { direction: 90, density: 0.15, speed: 1, }, }, ], skipFading: true, }); ``` Play only particles: ```js await FXMASTER.api.effects.play({ particles: [ { type: "snow", options: { direction: 110, density: 0.12, speed: 0.9 } }, { type: "fog", options: { scale: 1.2, density: 0.08, alpha: 0.6 } }, ], }); ``` Play only filters on a specific Scene: ```js await FXMASTER.api.effects.play({ filters: [ { type: "underwater", options: { speed: 0.5, scale: 1.2 }, }, ], scene: "Scene.abc123", }); ``` Stop by the ids returned from `play`: ```js await FXMASTER.api.effects.stop({ ...ids, skipFading: true, }); ``` Stop by exact payload match when ids are not available: ```js await FXMASTER.api.effects.stop({ effects: [ { kind: "filter", type: "color", options: { color: { value: "#9cc8ff", apply: true }, saturation: 0.1, contrast: 1.05, }, }, { kind: "particle", type: "rain", options: { direction: 90, density: 0.15, speed: 1, }, }, ], skipFading: true, }); ``` Toggle a named effect group on or off: ```js await FXMASTER.api.effects.toggle({ effects: [ { kind: "particle", type: "fog", options: { scale: 1.25, density: 0.08, alpha: 0.6 }, }, { kind: "filter", type: "bloom", options: { blur: 2, bloomScale: 1.1, threshold: 0.4 }, }, ], toggleKey: "swamp-haze", skipFading: true, }); ``` When `toggleKey` is omitted, FXMaster derives a repeatable toggle key from the effect payload. Later calls with the same payload, or the same explicit `toggleKey`, toggle that group off. `play` and `stop` return an object shaped like `{ particles: string[], filters: string[] }`. `toggle` returns `{ active, action, particles, filters }`. #### Scoped helpers Use the scoped helpers when you already know you only want one effect kind. ```js await FXMASTER.api.effects.particles.stop(ids.particles, { skipFading: true }); await FXMASTER.api.effects.filters.stop(ids.filters, { skipFading: true }); await FXMASTER.api.effects.particles.toggle( [{ type: "snow", options: { direction: 110, density: 0.12, speed: 0.9 } }], { toggleKey: "roof-snow", skipFading: true }, ); await FXMASTER.api.effects.filters.toggle( [ { type: "color", options: { color: { value: "#88ccff", apply: true }, saturation: 0.15 }, }, ], { toggleKey: "cold-tint" }, ); ``` #### Built-in filter effect types Core FXMaster currently registers these filter types: `bloom`, `color`, `fog`, `lightning`, `oldfilm`, `predator`, `underwater`, `screenShake` FXMaster+ registers additional filter effect types: `water`, `lightningbolts`, `ice`, `sunlight`, `duststorm`, `glitch`, `wind`, `auroraborealis`, `fire` You can inspect the currently registered filter types in a running world with: ```js Object.keys(CONFIG.fxmaster.filterEffects ?? {}) ``` Filter option names vary by effect. The most reliable way to get an exact filter payload is to configure the effect in the UI and save it as a macro, then reuse the generated `options` object inside `FXMASTER.api.effects`. #### Built-in particle effect types Core FXMaster currently registers these particle types: `autumnleaves`, `bats`, `birds`, `bubbles`, `clouds`, `crows`, `eagles`, `embers`, `fog`, `hail`, `rain`, `rats`, `snow`, `snowstorm`, `spiders`, `stars` FXMaster+ registers additional particle effect types: `sakurabloom`, `sakurablossom`, `magiccrystals`, `fireflies`, `ghosts`, `sandstorm`, `fish`, `windwisps`, `fire` You can inspect the currently registered particle types in a running world with: ```js Object.keys(CONFIG.fxmaster.particleEffects ?? {}) ``` #### Common particle effect options Most particle effects accept a subset of the following options. The exact option bag varies by effect type. | Option | Type | Description | | --- | --- | --- | | `scale` | `number` | Scale factor applied relative to the effect’s base size. | | `direction` | `number` | Effect direction in degrees. | | `speed` | `number` | Speed multiplier relative to the effect’s base speed. | | `lifetime` | `number` | Lifetime multiplier for the emitted particles. | | `density` | `number` | Particle density for the effect. | | `alpha` | `number` | Particle opacity from `0` to `1`. | | `tint` | `{ value: string, apply: boolean }` | Tint the effect with a color when supported. | | `animations` | `string[]` | Optional animation names used by effects that support multiple motion variants. | ## 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](https://ko-fi.com/secretfire). ## 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]. [Foundry Virtual Tabletop]: https://foundryvtt.com/ [JB2A]: https://github.com/Jules-Bens-Aa/JB2A_DnD5e [Jinker's Animated Art]: https://github.com/jinkergm/JAA [Jack Kerouac's Animated Spell Effects]: https://github.com/jackkerouac/animated-spell-effects [Jack Kerouac's Animated Spell Effects Cartoon]: https://github.com/jackkerouac/animated-spell-effects-cartoon [Boss Loot Animated Assets]: https://github.com/boss-loot/boss-loot-assets-free [Wild Magic Surge]: https://foundryvtt.com/packages/wild_magic_surge_animated_dungeon_lighting_one [Sequencer]: https://github.com/fantasycalendar/FoundryVTT-Sequencer [U~man]: https://github.com/mesfoliesludiques [ghost]: https://github.com/ghost-fvtt [theripper93]: https://github.com/theripper93 [Wasp]: https://github.com/fantasycalendar [SecretFire]: https://github.com/Feu-Secret [whtdragon]: https://forums.rpgmakerweb.com/index.php?threads/whtdragons-animals-and-running-horses-now-with-more-dragons.53552/ [Font Awesome]: https://fontawesome.com/ [BSD 3-Clause]: ./LICENSES/BSD-3-Clause.txt [CC BY-NC-SA-4.0]: ./LICENSES/CC-BY-NC-SA-4.0.txt [CC BY-4.0]: ./LICENSES/CC-BY-4.0.txt [Rexard Game Dev Assets EULA]: ./LICENSES/LicenseRef-RexardGameDevAssetsEULA.txt