Particle Effects System

The particle effect system is build to be extensible and modular.
There are a couple of different modules to change the behavior of effects, and they can be combined for more customizability.

First, the basics of the system. The system consists mainly of two classes, ParticleEffect and ParticleAnimation.

ParticleEffect

ParticleEffects are effects of one specific Particle type with a specific duration, and only run once.

Properties:

name (optional): Display name of the effect, that can be used in-game.
description (optional): Description of the effect.
icon (default=FIREWORK_STAR): Icon of the effect.
particle (required): The particle type. See Particle List
data (default=null): The data of the particle. For example, DustOptions
offset (default=[0.0, 0.0, 0.0]): The random offset for the particle.
count (default=1): The amount of particles.
extra (default=0): The extra value of the particle. Usually the speed.
timer (default="wolfyutilities:linear"): The timer that controls the effect and calculates the time increments, etc.
animator (required): The animator that defines the shape/behavior of the particles.

Timer

The timer manages the runtime of the ParticleEffect, like start value, how to increase each tick, and when it should stop.

• Linear
• Pi
• Random

Linear

(wolfyutilities:linear)
Formula: t += increment

Increases the timer by a specified increment. The increment cannot be 0!

Pi

(wolfyutilities:pi_fraction)
Formula: t += PI / fraction

Increases the timer by a fraction of PI. The fraction value cannot be 0.
If setting the stop value you need to make sure the timer isn't increased indefinitely:
If fraction is bigger than 0, then the stop value must be bigger than 0!
If fraction is smaller than 0, then the stop value must be smaller than 0!

Random

(wolfyutilities:random)
Formula: t += random.nextDouble() * multiplier

Increases the timer by a random amount each run.
You can specify a seed for the random generator and a multiplier for the random result that output.
Each run the timer will choose a random value between 0.0 - 1.0, which is then multiplied with the multiplier.

Important!
The stop value for this timer is not affected by the randomness! The timer has a separate counter that counts the runs, and will stop if it reaches the stop value.

Animator

The animator specifies the actual shape and behavior of the effect.
There are currently only three default animators available.

• Basic
• Circle
• Sphere

Basic

(wolfyutilities:basic)
This animator has no further options and will just spawn the particle at the given location without any modification.

Circle

(wolfyutilities:circle)
Spawns the particles in a circle shape of the specified radius. The default radius is 1.
There is no option to rotate the circle yet, so it will just lay flat on the z-axis.

Sphere

(wolfyutilities:sphere)
Spawns the particle in a spherical shape of the specified radius. The default radius is 1.

ParticleAnimation

ParticleAnimations contain multiple ParticleEffects.
They have a specified duration in ticks, ParticleEffects can be configured at specific ticks, and they can be repeated.

Properties:

name (optional): Display name of the animation, that can be used in-game.
description (optional): Description of the animation.
icon (default=FIREWORK_ROCKET): Icon of the animation.
delay (default=0): The delay in tick after, which the animation is executed.
interval (default=1): The duration of each interval.
repetitions (default=1): The amount of times the interval is repeated. If -1 the animation continues forever.
effects (required, tick=[ParticleEffect]): The ParticleEffects that are run per tick of the interval.

Example

CustomCrafting uses this for the particle animation of the advanced crafting table. It just spawns the enchanting table particles with the specified settings.

"animation": {
        "effects" : {
          "0" : [ {
            "effect" : {
              "particle" : "ENCHANTMENT_TABLE",
              "name" : "",
              "description" : [ ],
              "icon" : "FIREWORK_ROCKET",
              "offset" : [ 0.0, 0.0, 0.0 ],
              "count" : 2,
              "extra" : 0.75,
              "timer" : {
                "key" : "wolfyutilities:linear",
                "startValue" : 0.0,
                "stopValue" : 1.0,
                "increment" : 1.0
              },
              "animator" : {
                "key" : "wolfyutilities:basic"
              }
            },
            "offset" : [ 0.5, 1.25, 0.5 ],
            "tick" : 0
          } ]
        },
        "name" : "Advanced Crafting Table",
        "description" : [ "This is the default effect for the advanced crafting table", "" ],
        "icon" : "ENCHANTING_TABLE",
        "delay" : 0,
        "interval" : 5,
        "repetitions" : -1
      }