Plugins / ParticleForge

Writing effects

Every effect is a YAML file in plugins/ParticleForge/effects/. The 56 bundled ones are copied there on first start, so the quickest way to make your own is to copy one, rename it and change it. Any file you add or edit is picked up by /pf reload, with players online.

A complete effect

Save this as plugins/ParticleForge/effects/custom/fountain.yml:

name: custom/fountain
category: custom
defaults:
  ring-particle: END_ROD
steps:
  - id: glow
    type: PARALLEL
    steps:
      - id: ring
        type: RING
        duration: 40
        params:
          particle: ${ring-particle}
          radius: 1.2
          points: 16
          rotation-deg-per-tick: 6
      - id: spiral
        type: HELIX
        duration: 40
        params:
          particle: HAPPY_VILLAGER
          radius: 0.6
          height: 2.5
          turns: 2

Run /pf reload, then /pf preview custom/fountain to see it at your feet, or /pf place add fountain custom/fountain to pin it to a spot.

The parts

• name is how you play the effect. Using category/effect keeps /pf list tidy.
• steps run one after another. Each step needs an id that is unique inside the file, a type, a duration in ticks (20 ticks = 1 second) and its params.
• PARALLEL runs the steps inside it at the same time. REPEAT runs them as many times as its times param says. DELAY waits for its duration.
• defaults are values you can reuse as ${name} anywhere in the params.

Step types

Most steps take particle, count, speed and spread. Shapes add their own sizes (radius, height, turns, points...). The bundled files use every type, so grep them for an example of the one you want.

Particle names work on every version: an effect can use the old name (VILLAGER_HAPPY, REDSTONE) or the new one (HAPPY_VILLAGER, DUST) and the right one is picked for your server.

Turn, move or spin one step

Every step is drawn pointing up, around the effect's origin. A pose: block on a step turns, moves or spins that step alone, with the same words as a placed effect: axis, pitch, yaw, offset and spin. It goes next to params, not inside it:

steps:
  - id: wall
    type: RING
    duration: 60
    params:
      radius: 1.5
    pose:
      axis: +z          # the ring stands up, facing south
      offset: 0 1 0     # one block higher
      spin: 20          # and turns, 20 degrees per second
  - id: floor
    type: RING
    duration: 60
    params:
      radius: 1.5       # this one stays flat on the floor

A pose on a PARALLEL or REPEAT step applies to everything inside it, and a step inside can carry its own pose on top. When the effect is placed with a pose of its own, the step's pose is applied first and the placed pose second, so a wall ring inside an effect laid along -x ends up where you would expect. A bad axis or offset is reported in the console and that step is drawn as built.

Variations with extends

To make a version of an existing effect, extend it and change only what differs. The easy way is to change one of its defaults:

name: custom/fountain-soul
extends: custom/fountain
defaults:
  ring-particle: SOUL_FIRE_FLAME

overrides: replaces the params of a step by its id, but only for steps listed directly under steps:, not ones inside a PARALLEL or REPEAT. For anything nested, put the value in defaults as above and use it as ${name}.

When something is wrong

A broken file never stops the others from loading. The console says which file failed and why: a missing name, two steps with the same id, an unknown type, or a ${value} with no default.

Keep reading

• Overview
• Commands and permissions
• Configuration reference
• Bundled effects
• Developer API
• Placed effects