---
description: >-
  This page explains how to configure a Particle Display using a YAML
  configuration file in your plugin. You can customize particle type, color,
  movement, size, rotation, and more.
---

# Particle Display

***

### 🔧 Basic Example

```yaml
particle:
  type: FLAME
  count: 10
  extra: 0.1
  force: true
  offset: 0.2, 0.5, 0.2
  direction: 0, 1, 0
  size: 1
  color: 255, 100, 50
```

***

### ⚙️ Configuration Options

#### `type`

Defines the type of particle to use. All available types can be found [here](https://github.com/CryptoMorin/XSeries/blob/master/core/src/main/java/com/cryptomorin/xseries/particles/XParticle.java).\
Example:

```yaml
type: FLAME
```

***

#### `count`

How many particles appear each time it's shown.\
Example:

```yaml
count: 20
```

***

#### `extra`

Controls how fast or wide the particles spread. The meaning depends on the particle type.\
Example:

```yaml
extra: 0.01
```

***

#### `force`

If `true`, the particles are always shown to players even at a long distance.\
Example:

```yaml
force: true
```

***

#### `offset`

Controls how much the particles move randomly when they appear.\
You can use one number (applied to all directions):

```yaml
offset: 0.3
```

Or use three numbers (for X, Y, Z separately):

```yaml
offset: 0.2, 0.5, 0.2
```

***

#### `direction`

Sets a fixed direction in which particles move.\
Example (upward):

```yaml
direction: 0, 1, 0
```

***

#### `size`

Controls the size of particles (for certain particles like colored ones).\
Example:

```yaml
size: 1.2
```

***

### 🎨 Color Options

You can use this to add color to your particles (like REDSTONE or DUST).

#### `color`

You can provide:

* **1 color** → Normal colored particle
* **2 colors** → Transition between two colors
* **3 values** → RGB values (Red, Green, Blue)
* **6 values** → Two RGB colors for a smooth transition

Examples:

**Single Color**

```yaml
color: 255, 0, 0   # Red
```

**Color Transition**

```yaml
color: 255, 0, 0, 0, 0, 255   # Red to Blue
```

***

### ⛏️ Material Types (Block or Item)

#### `blockdata`

Use a block name to show particles related to that block (e.g., BLOCK\_CRACK).

```yaml
blockdata: STONE
```

***

#### `itemstack`

Use an item name to show particles with item visuals (e.g., ITEM\_CRACK).

```yaml
itemstack: DIAMOND_SWORD
```

***

#### `materialdata`

Old-style block format (not commonly needed).

```yaml
materialdata: GRASS_BLOCK
```

***

### 🔄 Rotations (Advanced)

You can rotate your particle group using rotation groups. Each group can have one or more rotations.

Example:

```yaml
rotations:
  group-1:
    0:
      angle: 3.14
      vector: "Y"
    1:
      angle: 2
      vector: "1, 0, 0"
  group-2:
    0:
      angle: 1.6
      vector: "0, 1, 0"
```

* `angle` – How much to rotate in radians (π ≈ 3.14).
* `vector` – The axis to rotate around. You can use:
  * Letters: `X`, `Y`, or `Z`
  * Custom vector: `"1, 0, 0"` means rotate around the X-axis

***

### 🧪 Tips

* For colored particles like REDSTONE, set the `color` and `size`.
* If using DUST\_TRANSITION, use **6 color values** for smooth color blending.
* Make sure the `type` supports the extra data you define (e.g., color or block).

***

### 🧾 Full Example

```yaml
particle:
  type: REDSTONE
  count: 15
  extra: 0.01
  force: false
  offset: 0.2, 0.2, 0.2
  direction: 0, 1, 0
  size: 1.0
  color: 255, 0, 0, 0, 0, 255
  rotations:
    spin:
      0:
        angle: 1.57
        vector: Y
```
