ParticleModule

the particle module provides functionality regarding particles.

Animations

the primary system added by this module is the particle animation system. the animations are created with the ParticleAnimation and its dedicated builder class $ParticleAnimationBuilder

Activation Triggers

each animation can define activation triggers. those triggers ensure certain conditions are met before the animations is submitted to be executed. a common example is when the animation is bound to an entity that might not yet exist, an EntityAddedTrigger is added to the animation in order to ensure the animation is loaded once sync adds the entity to the client level. custom activation triggers can be made by implementing the ActivationTrigger interface and implementing the ActivationTriggerInstance to create an instance handler for the type. the trigger must then be registered to the ParticleAnimationRegistries.Keys.ACTIVATION_TRIGGERS.

Spawners

each animation must define a spawner. to use multiple spawners, use the GroupSpawner class. these spawners tell the animator where to spawn particles and what particle types / options to use. there are many different Spawners including, but not limited to SingleSpawner a simple particle spawner, LineSpawner which spawns a line of particle or RingSpawner which spawns a ring of particles. to make your own custom Spawner types, implement the Spawner interface and register its type to the ParticleAnimationRegistries.Keys.SPAWNER_TYPES. to spawn particles and adding them to the animation processor, call ParticleSpawnSink#accept from within the Spawners' spawn method.

Elements

each element sequentially processes each spawned particle for a given amount of time. these elements get access to each particles' ParticleConfig which exposes position, velocity, color as well as age and lifetime. those can be modified via custom AnimtionElements registered to the ParticleAnimationRegistries.Keys.MODIFIER_TYPES.

Finalizers

once each element has been processed on a particle, the particle finalizer is executed on that particle. this finalizer gets access to the particles ParticleConfig allowing for a wide range of possibilities for the finalizer to modify the particle before transferring it to the vanilla particle processor. custom finalizers must be registered to the ParticleAnimationRegistries.Keys.FINALIZER_TYPES.

Terminators

many particle animations should not run indefinitely. for that reason terminators have been introduced to specify when a particle animation should be removed. these can be entity bound (when an entity is removed, the animations bound to it should also be removed in order to ensure the animation doesn't crash), time bound (the animation lasts a certain amount of time) or custom, for which a registration to the ParticleAnimationRegistries.Keys.TERMINATOR_TYPES has to be made. all particles that were currently processed by the animation will be finalized and submitted for vanilla behavior to continue.

Animation Presets

animations that are often used can be prepared as a preset. presets are generalized particle animation builders. presets are JSON based and can be located both client and serverside. they can be baked by creating a ParticleAnimationPresetContext and calling ServerParticleAnimationManager#usePresetOnPlayer for server-sided presets or ClientParticleAnimationManager#usePreset for client-sided presets.

Custom Particles

the module also provides a few custom particles. those include a lightning particle that is spanned between 2 defined positions and a damage indicator particle that can be configured to show damage dealt to entities.