![[IMG]](//proxy.spigotmc.org/9dea725f252df5d4990df0c13384f5573cad6fa5/68747470733a2f2f63646e2e6a7364656c6976722e6e65742f6a6f79706978656c732f6173736574732f362e352f706e672f756e69636f64652f36342f323639392e706e67)
Particles — Event-based Particle Effects for Your Server
Particles is a lightweight, version-safe particle engine that hooks into common player and block events.
It lets you define what happens on join, chat, command, block break, death, flight, etc. – all from a few simple YAML files, with proper support from 1.8 up to 1.21.x in a single jar.
No NMS, no reflection hell, no “this effect only works on 1.19” surprises – just clean, mapped particle templates that behave across old and new versions.
⚠ Early Version – Actively Improved ⚠
Particles is still under active development (v0.x).
Effect templates, mappings and presets are evolving based on real server usage.
Bugs, weird visual cases or missing mappings may exist – but they are being fixed quickly as feedback comes in.
![[IMG]](//proxy.spigotmc.org/fb95e4a883ad2509b3b9ed76d0b043057a578c77/68747470733a2f2f63646e2e6a7364656c6976722e6e65742f6a6f79706978656c732f6173736574732f362e352f706e672f756e69636f64652f36342f323730352e706e67)
Core Concept & Version Safety
Particles is built around one idea:
“Use universal particle keys in your configs, then map them to real Particle/Effect enums per version.”
Under the hood:
- Single jar for 1.8 – 1.21.x
- 1.8 & other legacy: uses a LegacyParticleAdapter based on Effect.
- 1.9+ modern servers: uses Particle API where available.
- MinecraftVersion detection chooses the right adapter automatically.
- If a mapping is missing or invalid, it falls back to a safe particle defined in config.yml instead of crashing the server.
You don’t need separate jars or version branches – just update the mappings if you want to tweak visuals per version.
![[IMG]](//proxy.spigotmc.org/45320c50817f39210b887f1c53fc227515a7a811/68747470733a2f2f63646e2e6a7364656c6976722e6e65742f6a6f79706978656c732f6173736574732f362e352f706e672f756e69636f64652f36342f323732382e706e67)
Event-Driven Particle System
Out of the box, Particles can react to a wide range of events, for example:
- Player events
- join / quit / kick
- chat & command
- death & respawn
- teleport & portal
- interact (block/entity), shear, fish
- toggle flight (perfect for “wings” effects), sneak, sprint
- item consume, drop, pickup, held changes
- Inventory events
- open / close
- click / drag
- Combat & projectiles
- generic damage
- damage by entity (hit effects)
- projectile launch / hit (arrow trails, impact bursts)
- Block events
- block break – dust burst at the broken block
- block place – subtle glow on the placed block
Each event references a named template in particles.yml, so you can make block breaking look like stone dust, flight look like wings, chat messages look like tiny pops above a player, etc.
YAML-Driven Customisation (No Code Required)
Everything is controlled via three simple YAML files:
![[IMG]](//proxy.spigotmc.org/b38e833ad65df743bba7ddb6bc32fe271f78c940/68747470733a2f2f63646e2e6a7364656c6976722e6e65742f6a6f79706978656c732f6173736574732f362e352f706e672f756e69636f64652f36342f303033312d323065332e706e67)
config.yml – global toggles & fallback
- settings.enabled – master on/off switch.
- settings.debug – log particle resolution & errors for testing.
- settings.fallback-particle – global fallback particle name for missing mappings.
- events.* – per-event enable/disable (e.g. player_chat, block_break, projectile_launch).
![[IMG]](//proxy.spigotmc.org/9b47488b85c8d6345428edcb4f12e41c3fa37b7c/68747470733a2f2f63646e2e6a7364656c6976722e6e65742f6a6f79706978656c732f6173736574732f362e352f706e672f756e69636f64652f36342f303033322d323065332e706e67)
particles.yml – event templates
Each event key has a particle template:
- key: universal particle key (e.g. player.aura, block.break_dust, wings).
- count: how many particles to spawn.
- offsetX / offsetY / offsetZ: spread around the origin.
- extra: speed / extra parameter for the particle.
- directional: hint flag for “directional” particles (used by the adapter).
You can create completely new templates, re-use keys across events, or disable any effect you don’t like.
![[IMG]](//proxy.spigotmc.org/bba6f2a91049e33c441ea50ede2a7d6422b511d1/68747470733a2f2f63646e2e6a7364656c6976722e6e65742f6a6f79706978656c732f6173736574732f362e352f706e672f756e69636f64652f36342f303033332d323065332e706e67)
particles_map.yml – version mappings
Maps universal keys → version-specific enum tokens:
player.aura:
V1_9: VILLAGER_HAPPY
V1_12: VILLAGER_HAPPY
V1_13: VILLAGER_HAPPY
V1_21: VILLAGER_HAPPY
block.break_dust:
V1_9: BLOCK_CRACK
V1_12: BLOCK_CRACK
V1_13: BLOCK
V1_21: BLOCK
This lets you fix or optimise visuals per version without changing any Java code.
![[IMG]](//proxy.spigotmc.org/dfb94a8c7cbc00389ddcf6d347e51f6b882e5b57/68747470733a2f2f63646e2e6a7364656c6976722e6e65742f6a6f79706978656c732f6173736574732f362e352f706e672f756e69636f64652f36342f31663965302e706e67)
Safe Fallbacks & Debugging
UniversalParticles is designed to fail safely:
- Invalid particle enum names? → Ignored, falls back instead of throwing.
- Missing map keys? → Uses fallback-particle from config.
- Exceptions during spawn? → Caught and logged as a single console error, not a spam flood.
- Optional debug logging:
- See which event fired, which universal key was resolved, and which token got used.
You get visibility without drowning your console.
⚙ Commands & Permissions
- /upart reload – reloads:
- config.yml
- particles.yml
- particles_map.yml
Permission:
- upart.reload – required for /upart reload (default: OP).
![[IMG]](//proxy.spigotmc.org/ff3bd3819e3822ccc8b6f61c2d3cf9e366bc84ec/68747470733a2f2f63646e2e6a7364656c6976722e6e65742f6a6f79706978656c732f6173736574732f362e352f706e672f756e69636f64652f36342f31663965392e706e67)
Integration Ideas
UniversalParticles is meant to play nicely with your existing setup:
- Authentication plugins (e.g. AuthmePlus)
- special effects on successful login, premium switch, captcha solve, etc.
- Mini-games (e.g. ProtectTheCore, BalloonEnvoy)
- kill effects, core damage bursts, envoy hits, region-enter visuals.
- Essentials-style cores (e.g. CryEssentials)
- warps, homes, teleports, /spawn, staff tools can all have visual feedback.
Because everything is event-driven and YAML-based, you can make your server feel “alive” without touching a single line of Java.
![[IMG]](//proxy.spigotmc.org/158c58071463ec3fa8f760ed068207ce75b58ea6/68747470733a2f2f63646e2e6a7364656c6976722e6e65742f6a6f79706978656c732f6173736574732f362e352f706e672f756e69636f64652f36342f31663463632e706e67)
Summary
UniversalParticles gives you:
- A version-safe particle engine for 1.8 – 1.21.x
- Clean, event-driven effects for common player, combat and block actions
- Fully configurable YAML templates and mappings
- Safe fallbacks and easy debugging
Perfect if you want your server to feel more responsive and modern, without bolting on yet another massive visual plugin.
LostDev discord server:
✱
https://discord.gg/6S6jxC5h67
(Join for more info, or plugins!)
Code (YAML):
####################################################################################
# Particles - config.yml #
####################################################################################
settings
:
enabled
: true
debug
: false
# If no valid particle is found for the current MC version, this will be used:
fallback-particle
:
"VILLAGER_HAPPY"
####################################################################################
# Event Toggles #
####################################################################################
events
:
# Player basics
player_join
: true
player_quit
: true
player_kick
: true
player_chat
: true
player_command
: true
player_move
: false
player_death
: true
player_respawn
: true
player_teleport
: true
player_interact
: true
player_interact_entity
: true
player_level_change
: true
player_exp_change
: true
player_item_consume
: true
player_item_held
: false
player_item_drop
: true
player_item_pickup
: true
player_toggle_sneak
: false
player_toggle_sprint
: false
player_toggle_flight
: true
player_bed_enter
: true
player_bed_leave
: true
player_shear_entity
: true
player_fish
: true
player_portal
: true
# Inventory
inventory_click
: false
inventory_open
: true
inventory_close
: true
inventory_drag
: false
# Damage / combat
entity_damage
: true
entity_damage_by_entity
: true
projectile_launch
: true
projectile_hit
: true
# Vehicle
vehicle_enter
: false
# Block events
block_break
: true
block_place
: true
####################################################################################
# Particles - particles.yml #
####################################################################################
# ───── Player Events ─────────────────────────────────────────────────────────────
player_join
:
key
:
"player.aura"
count
: 20
offsetX
: 0.5
offsetY
: 0.7
offsetZ
: 0.5
extra
: 0.01
directional
: false
player_quit
:
key
:
"player.poof"
count
: 15
offsetX
: 0.4
offsetY
: 0.5
offsetZ
: 0.4
extra
: 0.01
directional
: false
player_kick
:
key
:
"player.poof_strong"
count
: 25
offsetX
: 0.5
offsetY
: 0.6
offsetZ
: 0.5
extra
: 0.02
directional
: false
player_chat
:
key
:
"chat.pop"
count
: 8
offsetX
: 0.3
offsetY
: 0.6
offsetZ
: 0.3
extra
: 0.0
directional
: false
player_command
:
key
:
"chat.command"
count
: 10
offsetX
: 0.3
offsetY
: 0.6
offsetZ
: 0.3
extra
: 0.0
directional
: false
player_move
:
key
:
"trail.step"
count
: 3
offsetX
: 0.2
offsetY
: 0.0
offsetZ
: 0.2
extra
: 0.0
directional
: false
player_death
:
key
:
"player.death_burst"
count
: 35
offsetX
: 0.7
offsetY
: 0.7
offsetZ
: 0.7
extra
: 0.03
directional
: false
player_respawn
:
key
:
"player.respawn_burst"
count
: 28
offsetX
: 0.6
offsetY
: 0.6
offsetZ
: 0.6
extra
: 0.02
directional
: false
player_teleport
:
key
:
"teleport.swirl"
count
: 22
offsetX
: 0.6
offsetY
: 0.9
offsetZ
: 0.6
extra
: 0.02
directional
: false
player_interact
:
key
:
"click.spark"
count
: 6
offsetX
: 0.3
offsetY
: 0.4
offsetZ
: 0.3
extra
: 0.01
directional
: false
player_interact_entity
:
key
:
"click.spark_entity"
count
: 8
offsetX
: 0.3
offsetY
: 0.4
offsetZ
: 0.3
extra
: 0.01
directional
: false
player_level_change
:
key
:
"player.levelup"
count
: 18
offsetX
: 0.5
offsetY
: 0.7
offsetZ
: 0.5
extra
: 0.02
directional
: false
player_exp_change
:
key
:
"player.xp"
count
: 10
offsetX
: 0.3
offsetY
: 0.5
offsetZ
: 0.3
extra
: 0.02
directional
: false
player_item_consume
:
key
:
"consume.bite"
count
: 10
offsetX
: 0.3
offsetY
: 0.8
offsetZ
: 0.3
extra
: 0.02
directional
: false
player_item_held
:
key
:
"hand.glow"
count
: 5
offsetX
: 0.2
offsetY
: 0.5
offsetZ
: 0.2
extra
: 0.0
directional
: false
player_item_drop
:
key
:
"item.drop"
count
: 8
offsetX
: 0.3
offsetY
: 0.3
offsetZ
: 0.3
extra
: 0.0
directional
: false
player_item_pickup
:
key
:
"item.pickup"
count
: 8
offsetX
: 0.3
offsetY
: 0.3
offsetZ
: 0.3
extra
: 0.0
directional
: false
player_toggle_sneak
:
key
:
"trail.step"
count
: 4
offsetX
: 0.2
offsetY
: 0.0
offsetZ
: 0.2
extra
: 0.0
directional
: false
player_toggle_sprint
:
key
:
"trail.speed"
count
: 6
offsetX
: 0.3
offsetY
: 0.0
offsetZ
: 0.3
extra
: 0.01
directional
: true
player_toggle_flight
:
key
:
"wings"
count
: 20
offsetX
: 0.7
offsetY
: 0.7
offsetZ
: 0.7
extra
: 0.03
directional
: true
player_bed_enter
:
key
:
"sleep.dust"
count
: 10
offsetX
: 0.5
offsetY
: 0.5
offsetZ
: 0.5
extra
: 0.02
directional
: false
player_bed_leave
:
key
:
"sleep.poof"
count
: 10
offsetX
: 0.5
offsetY
: 0.5
offsetZ
: 0.5
extra
: 0.02
directional
: false
player_shear_entity
:
key
:
"shear.fuzz"
count
: 12
offsetX
: 0.4
offsetY
: 0.4
offsetZ
: 0.4
extra
: 0.01
directional
: false
player_fish
:
key
:
"fishing.splash"
count
: 10
offsetX
: 0.3
offsetY
: 0.2
offsetZ
: 0.3
extra
: 0.01
directional
: false
player_portal
:
key
:
"portal.swirl"
count
: 30
offsetX
: 0.8
offsetY
: 1.0
offsetZ
: 0.8
extra
: 0.04
directional
: false
# ───── Inventory Events ──────────────────────────────────────────────────────────
inventory_open
:
key
:
"inv.open"
count
: 10
offsetX
: 0.4
offsetY
: 0.4
offsetZ
: 0.4
extra
: 0.01
directional
: false
inventory_close
:
key
:
"inv.close"
count
: 10
offsetX
: 0.4
offsetY
: 0.4
offsetZ
: 0.4
extra
: 0.01
directional
: false
inventory_click
:
key
:
"inv.click"
count
: 4
offsetX
: 0.2
offsetY
: 0.2
offsetZ
: 0.2
extra
: 0.0
directional
: false
inventory_drag
:
key
:
"inv.drag"
count
: 4
offsetX
: 0.2
offsetY
: 0.2
offsetZ
: 0.2
extra
: 0.0
directional
: false
# ───── Damage & Combat ───────────────────────────────────────────────────────────
entity_damage
:
key
:
"hit.spark"
count
: 10
offsetX
: 0.4
offsetY
: 0.8
offsetZ
: 0.4
extra
: 0.02
directional
: true
entity_damage_by_entity
:
key
:
"hit.crit"
count
: 15
offsetX
: 0.4
offsetY
: 0.8
offsetZ
: 0.4
extra
: 0.03
directional
: true
# ───── Projectiles ───────────────────────────────────────────────────────────────
projectile_launch
:
key
:
"projectile.trail"
count
: 8
offsetX
: 0.3
offsetY
: 0.3
offsetZ
: 0.3
extra
: 0.01
directional
: true
projectile_hit
:
key
:
"projectile.hit"
count
: 12
offsetX
: 0.4
offsetY
: 0.4
offsetZ
: 0.4
extra
: 0.02
directional
: false
# ───── Block Events ──────────────────────────────────────────────────────────────
block_break
:
key
:
"block.break_dust"
count
: 12
offsetX
: 0.5
offsetY
: 0.5
offsetZ
: 0.5
extra
: 0.02
directional
: false
block_place
:
key
:
"block.place_glow"
count
: 10
offsetX
: 0.4
offsetY
: 0.4
offsetZ
: 0.4
extra
: 0.02
directional
: false
####################################################################################
# Universal Particle Map #
####################################################################################
# ───── Player aura / core ────────────────────────────────────────────────────────
player.aura
:
V1_9
: VILLAGER_HAPPY
V1_12
: VILLAGER_HAPPY
V1_13
: VILLAGER_HAPPY
V1_21
: VILLAGER_HAPPY
player.poof
:
V1_9
: CLOUD
V1_12
: CLOUD
V1_13
: CLOUD
V1_21
: CLOUD
player.poof_strong
:
V1_9
: EXPLOSION_NORMAL
V1_12
: EXPLOSION_NORMAL
V1_13
: EXPLOSION_NORMAL
V1_21
: EXPLOSION_NORMAL
player.levelup
:
V1_9
: FIREWORKS_SPARK
V1_12
: FIREWORKS_SPARK
V1_13
: FIREWORKS_SPARK
V1_21
: FIREWORKS_SPARK
player.xp
:
V1_9
: SPELL_INSTANT
V1_12
: SPELL_INSTANT
V1_13
: INSTANT_EFFECT
V1_21
: INSTANT_EFFECT
player.death_burst
:
V1_9
: SMOKE_LARGE
V1_12
: SMOKE_LARGE
V1_13
: LARGE_SMOKE
V1_21
: LARGE_SMOKE
player.respawn_burst
:
V1_9
: SPELL_WITCH
V1_12
: SPELL_WITCH
V1_13
: WITCH
V1_21
: WITCH
# ───── Chat / command ───────────────────────────────────────────────────────────
chat.pop
:
V1_9
: REDSTONE
V1_12
: REDSTONE
V1_13
: REDSTONE
V1_21
: REDSTONE
chat.command
:
V1_9
: NOTE
V1_12
: NOTE
V1_13
: NOTE
V1_21
: NOTE
# ───── Trails ───────────────────────────────────────────────────────────────────
trail.step
:
V1_9
: FOOTSTEP
V1_12
: FOOTSTEP
V1_13
: FOOTSTEP
V1_21
: FOOTSTEP
trail.speed
:
V1_9
: CLOUD
V1_12
: CLOUD
V1_13
: CLOUD
V1_21
: CLOUD
# ───── Teleport / portal ────────────────────────────────────────────────────────
teleport.swirl
:
V1_9
: PORTAL
V1_12
: PORTAL
V1_13
: PORTAL
V1_21
: PORTAL
portal.swirl
:
V1_9
: PORTAL
V1_12
: PORTAL
V1_13
: PORTAL
V1_21
: PORTAL
# ───── Inventory ────────────────────────────────────────────────────────────────
inv.open
:
V1_9
: SPELL_MOB
V1_12
: SPELL_MOB
V1_13
: ENTITY_EFFECT
V1_21
: ENTITY_EFFECT
inv.close
:
V1_9
: SPELL_MOB
V1_12
: SPELL_MOB
V1_13
: ENTITY_EFFECT
V1_21
: ENTITY_EFFECT
inv.click
:
V1_9
: CRIT
V1_12
: CRIT
V1_13
: CRIT
V1_21
: CRIT
inv.drag
:
V1_9
: CRIT_MAGIC
V1_12
: CRIT_MAGIC
V1_13
: ENCHANTED_HIT
V1_21
: ENCHANTED_HIT
# ───── Damage / combat ─────────────────────────────────────────────────────────-
hit.spark
:
V1_9
: CRIT
V1_12
: CRIT
V1_13
: CRIT
V1_21
: CRIT
hit.crit
:
V1_9
: CRIT_MAGIC
V1_12
: CRIT_MAGIC
V1_13
: ENCHANTED_HIT
V1_21
: ENCHANTED_HIT
# ───── Items ────────────────────────────────────────────────────────────────────
item.drop
:
V1_9
: CLOUD
V1_12
: CLOUD
V1_13
: CLOUD
V1_21
: CLOUD
item.pickup
:
V1_9
: SPELL
V1_12
: SPELL
V1_13
: SPELL
V1_21
: SPELL
hand.glow
:
V1_9
: SPELL_MOB
V1_12
: SPELL_MOB
V1_13
: ENTITY_EFFECT
V1_21
: ENTITY_EFFECT
consume.bite
:
V1_9
: HAPPY_VILLAGER
V1_12
: HAPPY_VILLAGER
V1_13
: VILLAGER_HAPPY
V1_21
: VILLAGER_HAPPY
# ───── Fishing / water ──────────────────────────────────────────────────────────
fishing.splash
:
V1_9
: WATER_SPLASH
V1_12
: WATER_SPLASH
V1_13
: SPLASH
V1_21
: SPLASH
# ───── Sleep / bed ──────────────────────────────────────────────────────────────
sleep.dust
:
V1_9
: SPELL
V1_12
: SPELL
V1_13
: SPELL
V1_21
: SPELL
sleep.poof
:
V1_9
: CLOUD
V1_12
: CLOUD
V1_13
: CLOUD
V1_21
: CLOUD
# ───── Projectiles ──────────────────────────────────────────────────────────────
projectile.trail
:
V1_9
: SMOKE_NORMAL
V1_12
: SMOKE_NORMAL
V1_13
: SMOKE
V1_21
: SMOKE
projectile.hit
:
V1_9
: BLOCK_CRACK
V1_12
: BLOCK_CRACK
V1_13
: BLOCK
V1_21
: BLOCK
# ───── Misc / extra ─────────────────────────────────────────────────────────────
click.spark
:
V1_9
: REDSTONE
V1_12
: REDSTONE
V1_13
: REDSTONE
V1_21
: REDSTONE
click.spark_entity
:
V1_9
: NOTE
V1_12
: NOTE
V1_13
: NOTE
V1_21
: NOTE
shear.fuzz
:
V1_9
: CLOUD
V1_12
: CLOUD
V1_13
: CLOUD
V1_21
: CLOUD
wings
:
V1_9
: CLOUD
V1_12
: CLOUD
V1_13
: CLOUD
V1_21
: CLOUD
block.break_dust
:
V1_9
: BLOCK_CRACK
V1_12
: BLOCK_CRACK
V1_13
: BLOCK
V1_21
: BLOCK
block.place_glow
:
V1_9
: SPELL_MOB
V1_12
: SPELL_MOB
V1_13
: ENTITY_EFFECT
V1_21
: ENTITY_EFFECT
![[IMG]](//proxy.spigotmc.org/72698510440d1dd87de00114559f154f5ce5f250/68747470733a2f2f6275696c7462796269742e636f6d2f6174746163686d656e74732f6372797468782d706e672e313132363239352f3f7072657365743d66756c6c7231)