Custom Particle Configuration

This guide explains how to use the YAML configuration files to create custom effects, cosmetics, and animations.

Structure of a Config File

Each cosmetic/effect configuration file consists of a base identity, a gui display section, general settings, an animation behavior, and multiple particle layers.

1. Base Identity & GUI Settings

The root key name acts as the unique identifier, while the gui section configures how the effect appears inside the selection menus.

name: "ABYSSAL_MATRIX"
 
gui:
  slot: 21                          # Slot position in the GUI menu
  item: "OBSIDIAN"                  # Material icon used in the GUI
  name: "&8&lAbyssal Matrix Cube"   # Display name with color codes
  custom_model_data: 1001           # Optional custom model data for the icon
  nbt: "legendary"                  # Optional NBT tag for the icon
 
  description:                      # Lore text lines for the item
    - "&7A corrupted dark energy cube that"
    - "&7continuously leaks cosmic void energy."

2. The `settings` Section

Defines the core operational parameters of the effect and access permissions.

settings:
  delay: 0.2                       # Seconds between spawn cycles (supports decimals)
  radius: 1.2                      # Base radius or overall scale of the effect
  count: 3                         # General particle density multiplier
 
  # Optional: Absolute bounds (overrides radius when enabled)
  offset:
    min: { x: -1.0, y: 0.0, z: -1.0 }
    max: { x: 1.0, y: 2.0, z: 1.0 }
 
  # Permission required to use this cosmetic
  permission: "particleplus.cosmetic.chrono"
 
  # Dimension restrictions (optional)
  allowed_dimensions:
    - "world"
    - "world_nether"

Setting	Description
`delay`	How often particles refresh/spawn (in seconds). Supports decimals (e.g. `0.2` = 5 times per second).
`radius`	Base radius or overall scale of the effect (only used if `offset` is not defined).
`count`	General particle density multiplier per spawn cycle.
`offset`	Absolute bounding box (`min/max`) — overrides `radius` when defined.
`permission`	Permission node required to use the cosmetic.
`allowed_dimensions`	List of world names where this effect is allowed (empty = all worlds).

Animation Settings

The animation section defines the geometric shape and movement behavior of the particles around the player or entity.

animation:
  type: HELIX
 
  # General positioning
  y-offset: 0.3
 
  # Rotation
  rotate: true
  rotate-speed: 3.5
 
  # Shape-specific settings
  filled: false
  points: 20
  spiral-height: 2.4
  helix-arms: 2
  orbit-count: 3
 
  # Bobbing movement (only works with RING)
  bob: true
  bob-speed: 0.08
  bob-height: 0.4

Note: If animation is not defined or type: RANDOM is used, the effect will spawn particles randomly within the defined radius/bounds (legacy behavior).

Supported Animation Types

Type	Description
`RANDOM`	Random scattering within radius/bounds (default, no shape).
`RING`	Circular ring around the entity.
`SPIRAL`	Single-strand vertical vortex spiral effect.
`HELIX`	Multi-strand rotating helix animation.
`CUBE`	Cube-shaped particle structure (hollow or filled).
`SPHERE`	Sphere or orb effect (hollow or filled).
`ORBIT`	Independent rotating orbiting particles.
`SPIN`	Fast rotating horizontal ring (higher rotate-speed).
`VORTEX`	Funnel-shaped vortex that narrows towards the top.
`WHIRL`	Chaotically swirling particles in a spherical volume.
`WHIRLWIND`	Rising tornado-like spiral that expands upwards.
`QUADHELIX`	Four intertwined DNA-style helix strands.
`PULSE`	Expanding and contracting spherical pulse.
`CELEBRATION`	Firework-like burst of particles.
`INVOCATION`	Rising ring effect from the player’s feet.
`POPPER`	Small random pops scattered around.
`THICK`	Dense cloud of particles (higher count multiplier).
`COMPANION`	Single particle orbiting the player.
`TWINS`	Two symmetrical orbiting particles.
`OVERHEAD`	Single particle floating above the player’s head.
`FEET`	Single particle at the player’s feet.
`POINT`	Single static particle at the exact location.
`NORMAL`	Same as `RANDOM` (included for consistency).
`ICOSPHERE`	Icosahedron-based geodesic sphere (smooth round shape).
`OUTLINE`	Particle outline of the player’s hitbox.
`RINGS`	Multiple horizontal rings stacked vertically.
`HALO`	A glowing halo above the player’s head.
`WINGS`	Wing-shaped particle formation behind the player.
`BEAM`	Vertical column of particles from feet to overhead.
`CHAINS`	Interconnected chain links circling the player.

Animation Property Reference

Property	Description
`type`	Shape/animation type (see table above).
`y-offset`	Vertical offset from the entity's feet position + 1 block.
`rotate`	Enables rotation movement (most types).
`rotate-speed`	Rotation speed in degrees per tick (negative values reverse direction).
`filled`	Whether shapes like `CUBE` or `SPHERE` are filled or hollow.
`points`	Number of geometry points used for rendering the shape.
`spiral-height`	Total vertical height of `SPIRAL`, `HELIX`, `QUADHELIX`, `WHIRLWIND` (in blocks).
`helix-arms`	Number of simultaneous helix strands (`HELIX` only).
`orbit-count`	Number of orbiting particles (`ORBIT` only).
`bob`	Enables smooth hovering movement (`RING` only).
`bob-speed`	Speed of the bobbing motion in radians per tick.
`bob-height`	Maximum vertical floating distance (in blocks).

Layers System (`layers`)

Effects support multi-layered rendering, allowing you to combine different particle types, RGB particles, and random offsets into a single cosmetic.

layers:
  0:
    particles:
      - END_ROD
      - GLOW
 
    count: 1
 
    offset:
      min: { x: -0.05, y: -0.05, z: -0.05 }
      max: { x: 0.05, y: 0.05, z: 0.05 }
 
  1:
    rgb_particles:
      - r: 0
        g: 220
        b: 255
        size: 0.8
 
    count: 2
 
    offset:
      min: { x: -0.15, y: -0.15, z: -0.15 }
      max: { x: 0.15, y: 0.15, z: 0.15 }

Layer Properties

Property	Description
`particles`	Standard Minecraft particle types (list).
`rgb_particles`	RGB configurable particle definitions (`r`, `g`, `b`, `size`).
`count`	Number of particles rendered per spawn point (`-1` inherits from `settings.count`).
`offset`	Random positional spread around the render point (`min/max` bounding box).
`use-absolute-bounds`	Uses absolute world-space bounds instead of relative offsets.
`animation`	Per-layer animation override.

Per-Layer Animation

Each layer can have its own independent animation, overriding the global animation for that layer.

layers:
  0:
    animation:
      type: RING
      points: 16
      y-offset: 0.5
      rotate: true
      rotate-speed: 4.0
 
    particles:
      - FLAME
 
    count: 1

Behavior Rules

If a layer has its own animation, particles spawn exactly on the animation points.
If a layer has no animation, particles scatter around the global animation's current render points.
If there is no global animation, layers without animation scatter around a single center point (0,0,0).

Absolute Bounds (Advanced)

By default, offsets are relative to the animation's current rendering point.

Enabling use-absolute-bounds: true inside a layer forces particles to spawn anywhere inside a fixed 3D box surrounding the player.

layers:
  1:
    particles:
      - DRAGON_BREATH
 
    count: 1
 
    use-absolute-bounds: true
 
    offset:
      min: { x: -1.0, y: 0.2, z: -1.0 }
      max: { x: 1.0, y: 1.8, z: 1.0 }

Common Use Cases

Ambient aura effects
Smoke clouds
Floating energy fields
Chaotic magic environments

Glow Effect (Optional)

You can add a glowing outline to the player while the effect is active.

glow:
  speed: 8
 
  colors:
    - RED
    - GOLD
    - YELLOW

Property	Description
`speed`	Animation speed in ticks (only relevant when multiple colors are used).
`colors`	List of glow colors to cycle through.

Supported Glow Colors

AQUA
BLACK
BLUE
DARK_AQUA
DARK_BLUE
DARK_GRAY
DARK_GREEN
DARK_PURPLE
DARK_RED
GOLD
GRAY
GREEN
LIGHT_PURPLE
RED
WHITE
YELLOW

Event Configuration

Folder: plugins/ParticlePlusReloaded/events/
Each event type has its own subfolder. Inside, you place YAML files defining the effect.

Event effects trigger when specific actions occur (moving, teleporting, taking damage, etc.). They support the same animation, layer, and particle systems as player cosmetics, plus additional filtering options.

Available Event Types

Folder Name	Trigger Condition
`Move`	Player moves (walks or runs).
`Trail`	Leaves a persistent particle trail behind the player.
`Teleport`	Player teleports (using ender pearls, commands, portals).
`Hurt`	Player takes damage.
`Death`	Player dies.
`Swords`	Player attacks with a sword (left-click).
`Projectiles`	Player shoots a projectile (arrow, snowball, egg, etc.).
`BlockBreak`	Player breaks a block.
`BlockPlace`	Player places a block.

Event Configuration Structure

# Basic particle settings
particles:
  - FLAME
  - SOUL_FIRE_FLAME
 
rgb_particles:
  - r: 255
    g: 100
    b: 0
    size: 1.0
 
count: 15
radius: 1.5
 
# Cooldown in seconds (0 = no cooldown)
cooldown: 1.0
 
# Duration in ticks (0 = one-shot effect)
duration: 0
 
# Optional permission (players without it see nothing)
permission: "particleplus.event.move.fire"
 
# Optional filter for specific worlds
allowed_worlds:
  - world
  - world_nether
 
# Event-specific filters
items:                # Only for Projectiles
  - BOW
  - CROSSBOW
 
blocks:               # Only for BlockBreak / BlockPlace
  - DIAMOND_ORE
  - GOLD_BLOCK
 
# Animation and layers (same as player cosmetics)
animation:
  type: RING
  points: 16
  y-offset: 0.5
  rotate: true
 
layers:
  0:
    particles:
      - END_ROD
    count: 3

Filter Rules

`items` (Projectiles)

List of materials (e.g. EGG, ARROW, ENDER_PEARL). If empty, any projectile triggers the effect.

`blocks` (BlockBreak / BlockPlace)

List of block materials (e.g. DIAMOND_ORE, STONE). If empty, any block triggers the effect.

`allowed_worlds`

If defined, the effect only appears in those worlds. If empty or missing, all worlds are allowed.

Example Event Configs

`events/Move/fire_walk.yml`

particles:
  - FLAME
 
count: 8
radius: 0.8
cooldown: 0.2
 
animation:
  type: FEET
  y-offset: 0.1

`events/Projectiles/magic_arrow.yml`

particles:
  - SPELL_WITCH
 
rgb_particles:
  - r: 0
    g: 200
    b: 255
    size: 1.0
 
count: 10
cooldown: 0.5
duration: 10
 
items:
  - BOW
  - CROSSBOW
 
animation:
  type: SPIRAL
  points: 12
  rotate-speed: 8.0
  spiral-height: 1.5

`events/BlockBreak/diamond_break.yml`

particles:
  - SPELL_WITCH
 
count: 25
radius: 1.2
 
blocks:
  - DIAMOND_ORE
  - DEEPSLATE_DIAMOND_ORE
 
animation:
  type: CELEBRATION
  y-offset: 0.5

Placeable Particles

Folder: plugins/ParticlePlusReloaded/Placeables/
Data file: plugins/ParticlePlusReloaded/placed_particles.yml

Placeable particles are fixed-location effects that continuously render at a specific world position. These are ideal for decorative builds, magic circles, fountains, shrines, portals, or ambient environments.

Unlike player cosmetics, placeable particles are completely static and persist even after server restarts.

Creating a Placeable Template

Each YAML file inside the Placeables/ folder defines a reusable template.

The structure is almost identical to regular cosmetic configurations:

settings
animation
layers
glow
RGB particles
absolute bounds
per-layer animations

The gui section is ignored for placeables.

Example Template

File: Placeables/magic_fountain.yml

name: "MAGIC_FOUNTAIN"
 
settings:
  delay: 0.3
  radius: 1.5
  count: 8
  permission: "particleplus.placeable.fountain"
 
animation:
  type: HELIX
  y-offset: 1.0
  rotate: true
  rotate-speed: 4.0
  helix-arms: 2
  spiral-height: 2.0
 
layers:
  0:
    particles:
      - WATER_SPLASH
      - DRAGON_BREATH
 
    count: 2
 
    offset:
      min: { x: -0.2, y: -0.2, z: -0.2 }
      max: { x: 0.2, y: 0.2, z: 0.2 }

Admin Commands

Use the following commands to manage placed particles in-game.

Command	Description
`/particleplus admin place create <name> <config>`	Creates a new placed particle at your current location.
`/particleplus admin place delete <name>`	Deletes an existing placed particle instance.

Command Arguments

Argument	Description
`<name>`	Unique identifier for the placed instance.
`<config>`	Template filename from the `Placeables/` folder (case-insensitive).

Example

/particleplus admin place create Fountain MAGIC_FOUNTAIN

How Placeables Work

All placed particles are automatically saved into placed_particles.yml.
Placed particles automatically reload after server restart or plugin reload.
Each placed particle runs independently with its own:
- animation state
- delay timer
- particle layers
- rotation logic
- render task

Mob Particles

Folder: plugins/ParticlePlusReloaded/Mobs/

Mob particle configurations define effects rendered around living entities such as zombies, skeletons, bosses, NPCs, or custom mobs.

Mob Configuration Structure

Each YAML file defines:

particle behavior
animations
layers
optional glow effects
matching rules for entities

name: "FLAME_AURA"
 
particles:
  - FLAME
 
rgb_particles:
  - r: 255
    g: 100
    b: 0
    size: 1.0
 
settings:
  delay: 0.5
  count: 15
  radius: 2.0
 
  allowed_dimensions:
    - world
    - world_nether
 
animation:
  type: SPHERE
  points: 32
  y-offset: 1.0
  rotate: true
 
layers:
  0:
    particles:
      - SOUL_FIRE_FLAME
    count: 5
 
glow:
  speed: 10
 
  colors:
    - RED
    - GOLD
 
mobs:
  - type: ZOMBIE
    name: "&4Boss Zombie"
    nbt: "is_boss"
 
  - type: WITHER_SKELETON

Mob Matching Rules

Each entry in the mobs section may contain the following fields.

Field	Description
`type`	Required entity type (`ZOMBIE`, `SKELETON`, etc.).
`name`	Optional exact custom name filter.
`nbt`	Optional NBT/scoreboard tag filter.

Matching Priority

Configs are prioritized based on specificity:

type + name + nbt
type + one filter
type only

The most specific matching config is always used.

Mob Particle Notes

Effects are visible to players within a 32 block radius.
Particles update in real-time as the mob moves.
Glow colors cycle automatically when multiple colors are configured.
Effects automatically stop when:
- the mob dies
- the entity unloads
- the chunk unloads

Item & Block Particles (Legacy)

These configuration types are still supported but are gradually being replaced by the newer and more flexible Event System.

Item Particles

Folder: plugins/ParticlePlusReloaded/items/

Item particle configs define effects that appear when a player holds a specific item.

Supported filters:

Material
Custom Name
CustomModelData
NBT tags

items:
  - material: DIAMOND_SWORD
    item_name: "&cFirebrand"
    custom_model_data: 1001
    nbt: "legendary_item"
 
settings:
  delay: 0.2
  count: 8
  radius: 1.5
 
particles:
  - FLAME
  - CRIT
 
animation:
  type: RING
  y-offset: 1.0
  rotate: true

Block Particles

Folder: plugins/ParticlePlusReloaded/blocks/

Block particle configs define effects rendered around matching blocks.

settings:
  check:
    size: 15
 
blocks:
  - DIAMOND_BLOCK
  - GOLD_BLOCK
 
particles:
  - SPELL_WITCH
 
animation:
  type: SPHERE
  points: 16
  y-offset: 0.5

Online Config Generator

You can use the official online config generator for faster configuration creation.

https://particleplus.best/editor (opens in a new tab)

API Usage