Direct Effect API

The Direct Effect API creates entries shown through Manage API Effects. Scene rows added through Particle Effects or Filter Effects remain separate.

Manage API-created effects

Use Manage API Effects to inspect, edit, or delete active effects created by macros, presets, or module integrations.

Edit API-created effects

Use the edit action in Manage API Effects when an API-created row needs adjustment without re-running the macro or integration that created it.

Create effects

Play particles and filters

const created = await FXMASTER.api.effects.play({
  particles: [
    {
      type: "rain",
      options: {
        topDown: true,
        splash: true,
        density: 0.45
      }
    }
  ],
  filters: [
    {
      type: "bloom",
      options: {
        blur: 2,
        bloomScale: 1,
        threshold: 0.5
      }
    }
  ]
});

Leave options out entirely, or omit individual options, to use the effect’s default values for anything not supplied.

A successful call returns the IDs assigned to the new rows:

{
  particles: ["apiMacro_…_p"],
  filters: ["apiMacro_…_f"]
}

No active Scene returns false. An otherwise valid request with no entries returns empty arrays.

Preserve explicit stack order

Use one ordered effects array when particles and filters must be interleaved. The supplied order is treated as the requested top-to-bottom order for the newly promoted rows.

const created = await FXMASTER.api.effects.play({
  effects: [
    {
      kind: "filter",
      type: "water",
      options: {
        opacity: 0.7,
        waves: true,
        caustics: true
      }
    },
    {
      kind: "particle",
      type: "fish",
      options: {
        density: 0.25
      }
    }
  ]
});

When effects is supplied, separate particles and filters arrays are ignored.

Stable explicit IDs

FXMaster generates independent IDs by default, so the same payload can be played more than once. A macro can instead provide a stable API-managed ID.

The required format is:

apiMacro_<unique name>_p
apiMacro_<unique name>_f

Use _p for a particle and _f for a filter.

await FXMASTER.api.effects.play({
  particles: [
    {
      id: "apiMacro_dockRain_p",
      type: "rain",
      options: {
        topDown: true,
        density: 0.35
      }
    }
  ]
});

An explicit ID outside this namespace or with the wrong suffix is ignored and replaced with a generated ID.

Manage effects

Stop rows

The safest stop input is the object returned by play():

const created = await FXMASTER.api.effects.play({
  particles: [{ type: "rain", options: { density: 0.35 } }]
});

await FXMASTER.api.effects.stop(created);

IDs can also be passed by kind:

await FXMASTER.api.effects.particles.stop([
  "apiMacro_dockRain_p"
]);

await FXMASTER.api.effects.filters.stop([
  "apiMacro_ritualBloom_f"
]);

stop() only removes matching API rows. It does not clear Scene effects added through Particle Effects or Filter Effects.

Toggle a payload

toggle() stores a group for the effect payload. The first call plays it; a later call with the same payload stops the created rows.

const result = await FXMASTER.api.effects.toggle({
  toggleKey: "harbor-storm",
  particles: [
    {
      type: "rain",
      options: {
        topDown: true,
        density: 0.45
      }
    }
  ]
});

The result identifies the action and active state:

{
  active: true,
  action: "play",
  particles: ["apiMacro_…_p"],
  filters: []
}

An explicit toggleKey is recommended when macros may evolve but should continue controlling the same logical group.

Targeting and transitions

Target another Scene

Every direct method accepts a Scene document or Scene UUID:

const scene = game.scenes.getName("Harbor");

await FXMASTER.api.effects.play({
  scene,
  particles: [{ type: "fog", options: { density: 0.3 } }]
});

Skip fades

Set skipFading: true for an immediate effect on or effect off transition. This option will completely skip the default fade in/fade out time for an effect:

await FXMASTER.api.effects.stop({
  particles: ["apiMacro_dockRain_p"],
  skipFading: true
});