ParticleForge

Effects you compose in a file, not in Java

ParticleForge is a free particle effect engine for Paper and Spigot, from 1.17 to 26.x. Fifty-six finished effects you can play straight away, and eighteen building blocks to write your own in a YAML file, with no Java and no restart.

It is built for servers that want effects everywhere without paying for them in performance.

Why ParticleForge

You compose effects, you don't code them: rings, spirals, beams, helixes, bursts and cones are pieces you stack in a file, in sequence or at the same time. A new effect is a text edit and a reload.
It has a budget and keeps to it: by default 64 effects can run at once and 4 per player, so an ambitious effect can't take the server down. The policy decides which effect goes when the cap is hit.
Distance costs less: faraway viewers get a simpler version, and players who can't see the location aren't processed at all.
One broken effect doesn't break the rest: each running effect is isolated, so a mistake in one file doesn't stop the others.
Other plugins can use it: there is an API, and plugins that ask for it and don't find it carry on without effects instead of failing to start.

How it works in play

You want a spiral of colour when somebody claims land. You copy the closest of the fifty-six effects, change its colour and radius, reload, and preview it at your feet until it looks right. Then you point your own plugin at it by name. With two hundred players online, the budget keeps that effect from becoming everybody's lag.

Writing an effect

A complete effect: a ring and a vortex that climbs through it at the same time, then a burst of fireworks.

name: claims/claim-marker
category: claims
steps:
  - id: marker
    type: PARALLEL
    steps:
      - id: ring
        type: RING
        duration: 40
        params:
          particle: END_ROD
          radius: 1.5
          points: 24
      - id: climb
        type: VORTEX
        duration: 40
        params:
          particle: DUST
          color: "#4FA3FF"
          start-radius: 1.2
          end-radius: 0.2
          height: 3.0
          turns: 2
  - id: pop
    type: BURST
    duration: 6
    params:
      particle: FIREWORK
      count: 30
      speed: 0.3

Configuration

effects/ holds one YAML file per effect, reloadable with players online.
config.yml holds the budgets (64 effects at once, 4 per player), the distances at which effects simplify (16, 48 and 96 blocks) and the language, each with a comment.
Particle names work on every version: use the old or the new name and the right one is picked for your server.

Commands and permissions

/pf list [category], /pf info <effect> and /pf stop need particleforge.use, which everyone has. Stopping another player's effects needs the admin permission.
/pf preview <effect>, /pf reload and /pf debug need particleforge.admin, which operators have.
Every node is declared in plugin.yml, so your permissions plugin lists them all.

Requirements

Paper or Spigot from 1.17 to 26.x, on the Java version your server already uses. Purpur and other forks work too.
No dependencies.

FAQ

Do I need to know Java?
No. Effects are YAML files. The API is only for plugin developers.

Will it lag my server?
Active effects are capped globally and per player, and effects far from a viewer are simplified or skipped.

Can I change a bundled effect?
Yes. Edit the file in effects/ and run /pf reload.

For questions or bug reports, use the discussion tab on this page or our Discord.