# Particles

Heads can emit particle effects via the [PlayerParticles](https://www.spigotmc.org/resources/playerparticles.117229/) plugin. Particle definitions are stored per-head in `heads.yml`. Each head can have multiple particle effects active simultaneously.

**Requirements:** PlayerParticles 8.12+ must be installed. If missing, the `particles` section is silently ignored and heads spawn without particles.

* Effect list: [Javadoc](https://javadoc.rosewooddev.io/PlayerParticles/dev/esophose/playerparticles/particles/ParticleEffect.html)
* Style list: [Javadoc](https://javadoc.rosewooddev.io/PlayerParticles/dev/esophose/playerparticles/styles/DefaultStyles.html)

#### Enabling particles

```yaml
particles:
  enable: true          # false disables all particles for this head
  list:
    <name>:             # Unique name — can be anything
      effect: <EFFECT>  # ParticleEffect enum name
      style: <STYLE>    # ParticleStyle enum name
```

#### Choosing effects and styles

The `effect` and `style` fields accept names from the PlayerParticles API. Run `/pp help` in-game for the full list.

Common effects: `FLAME`, `DUST`, `NOTE`, `DUST_COLOR_TRANSITION`, `ENTITY_EFFECT`, `PORTAL`, `ENCHANT`, `HEART`, `LAVA`.

Common styles: `NORMAL`, `RINGS`, `SPHERE`, `SPIRAL`, `VORTEX`, `WINGS`, `BEAM`.

#### Simple effects (no color)

Effects like `FLAME`, `HEART`, `PORTAL`, and `ENCHANT` need no extra data:

```yaml
particles:
  enable: true
  list:
    flame_rings:
      effect: FLAME
      style: RINGS
```

#### Colored effects

`DUST`, `ENTITY_EFFECT`, and similar effects accept an RGB color via `color`:

```yaml
particles:
  enable: true
  list:
    red_dust:
      effect: DUST
      style: RINGS
      color: "255,50,50"
```

#### Color transition effects

`DUST_COLOR_TRANSITION` blends between two colors. Supply both `color` (start) and `to_color` (end):

```yaml
particles:
  enable: true
  list:
    rainbow:
      effect: DUST_COLOR_TRANSITION
      style: SPHERE
      color: "255,50,50"
      to_color: "50,50,255"
```

#### Note effect

`NOTE` accepts an integer `note` value (0–24):

```yaml
particles:
  enable: true
  list:
    chime:
      effect: NOTE
      style: NORMAL
      note: 12
```

#### Multiple particles on one head

Define multiple named entries under `list` to layer effects:

```yaml
particles:
  enable: true
  list:
    flame_base:
      effect: FLAME
      style: RINGS
    sparkle:
      effect: ENCHANT
      style: SPIRAL
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.hyronic.dev/server-setups/mcmmo-survival/plugin-mavrotatingheads/particles.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.