Skin Particles

Skin Particles

SkinEngine can add real particle effects to your skins while players are actually using them in-game. That means particles are not just a cosmetic note inside a config file. They are part of live gameplay.

A skin can use particles when a player fights with a weapon, breaks or transforms blocks with a tool, shoots a bow, crossbow, or trident, casts a fishing rod, blocks with a shield, glides with a skinned elytra, or wears skinned armor.

[!INFO] SkinEngine supports all Minecraft particles. You can find the full list on Spigot API.

For particles to appear at all, three things must be true:

• particles must be enabled in the main plugin config
• the item or armor piece must really have a SkinEngine skin on it
• that skin must define a particle effect

Where to set particles

You can attach a particle effect to an item category inside the skin file, or to the armor section for armor-wide effects.

In practice, item particles are used for event-based effects such as hits, shots, casts, and blocks. Armor particles are better for aura-like effects that follow the player over time.

Here is a simple example:

content:
  items:
    sword:
      resources:
        main: "sword.png"
      particle: CRIT

  armor:
    layer_1: "armor_layer_1.png"
    layer_2: "armor_layer_2.png"
    particle: DUST

[!WARNING] If your server version does not support a particle, SkinEngine cannot use it. Always match your skin setup to the version your server actually uses.

The simple way and the detailed way

There are two normal ways to define a particle.

The first is the short form. This is the easiest option, and it is usually the best place to start. You only write the particle name, and SkinEngine fills in the rest with its built-in defaults.

particle: CRIT

The second is the full form. Use this when you want to control how strong the effect looks, how spread out it is, or when the chosen particle needs extra data such as a color, a material, or a target.

particle:
  effect: DUST
  count: 4
  offset: 0.2
  extra: 0.01
  data:
    color: "#8FE9FF"
    size: 1.2

In the full form, you can control:

• the particle type itself
• how many particles are spawned
• how far they can spread on each axis
• the extra value used by that particle
• any special data the selected particle needs

If you use offset, SkinEngine treats it as the shared value for all three axes, unless you choose to override individual axes separately.

Default behavior

If you use the short form, or if you leave optional values out, SkinEngine falls back to built-in defaults.

For item particles, the default is a slightly more visible effect: six particles, light spread on all axes, and a small extra value.

For armor particles, the default is lighter and tighter: two particles, a bit more height, and no extra value.

What happens in-game

Different skin categories use particles in different ways.

Tools

Tool particles are used by:

• sword
• mace
• axe
• pickaxe
• shovel
• hoe
• spear

These particles can appear when the player hits an entity, breaks a block, strips logs with an axe, turns dirt into farmland with a hoe, or makes a dirt path with a shovel.

Bows and crossbows

Bow and crossbow particles do not stay on the item. Instead, they follow the fired projectile as a trail.

SkinEngine checks the projectile every two ticks and stops tracking it when it hits something, becomes invalid, lands on the ground, or lives too long. The current lifetime limit is 200 ticks, and the plugin tracks up to 128 projectiles at once.

Tridents

Trident particles also use projectile trail tracking.

If the held trident has a SkinEngine particle configured, the plugin follows the thrown trident in flight using the same projectile tracking limits as bows and crossbows.

Fishing rods

Fishing rod particles follow the hook while the player is in the real FISHING cast state.

Shields

Shield particles appear when a player truly blocks incoming damage with the shield raised.

SkinEngine checks the off-hand first, then the main hand, and spawns the effect on the correct side of the player model.

Elytras

Elytra particles are handled as glide trails.

If the player is currently gliding with a skinned elytra that has a particle configured, SkinEngine spawns the effect behind both wings on a repeating two-tick task.

Armor

Armor particles are handled separately from item particles. They come from the armor section of the skin file and are emitted around the player on a repeating task.

The update speed is controlled by the armor particle interval setting in config.yml. The default interval is 10 ticks.

If a player wears multiple skinned armor pieces with particle effects, SkinEngine chooses one skin to represent. The skin worn on the highest number of armor pieces wins. If that count is tied, the priority order is chestplate first, then leggings, then helmet, then boots.

Viewer range

Particles are only sent to nearby players, not to the whole server.

That distance is controlled by the particle viewer range setting in the main plugin config. The default value is 32 blocks.

Full particle list

The table below matches the current particle enum that SkinEngine parses.

If the second column says Yes, that particle needs extra setup. Click the link to jump to the explanation further down this page.

Particles that need extra setup

Some particles need more than just their name. When that happens, SkinEngine expects a data section with the correct values. If the required data is missing, the plugin skips that particle entry instead of trying to guess what you meant.

The sections below show the exact data formats that are supported by the current SkinEngine parser.

Dust

This is used for:

• DUST

This particle needs a color. You can also give it a custom size.

Example:

particle:
  effect: DUST
  data:
    color: "#8FE9FF"
    size: 1.2

Dust color transition

This is used for:

• DUST_COLOR_TRANSITION

This version of dust blends from one color into another. You must provide both the starting color and the ending color. Size is optional.

Example:

particle:
  effect: DUST_COLOR_TRANSITION
  data:
    from: "#8FE9FF"
    to: "#FFFFFF"
    size: 1.0

Block particles

This is used for:

• BLOCK
• BLOCK_CRUMBLE
• BLOCK_MARKER
• DUST_PILLAR
• FALLING_DUST

These particles need a block material. In other words, the material must exist and it must really be a block.

Example:

particle:
  effect: BLOCK
  data:
    material: ICE

Item particles

This is used for:

• ITEM

This particle needs an item material. AIR is not valid here.

Example:

particle:
  effect: ITEM
  data:
    material: DIAMOND

Color-based particles

This is used for:

• ENTITY_EFFECT
• FLASH
• TINTED_LEAVES

These particles need a color.

Example:

particle:
  effect: ENTITY_EFFECT
  data:
    color: "143,233,255"

SkinEngine accepts colors in several readable forms:

• a hex color such as #8FE9FF
• RGB text such as "143,233,255"
• a section with red, green, blue
• a section with r, g, b

Section example:

particle:
  effect: FLASH
  data:
    color:
      red: 143
      green: 233
      blue: 255

Spell particles

This is used for:

• EFFECT
• INSTANT_EFFECT

These particles need both a color and a power value.

Example:

particle:
  effect: EFFECT
  data:
    color: "#CC8844"
    power: 0.8

Number-based particles

This is used for:

• DRAGON_BREATH
• SCULK_CHARGE
• SHRIEK

These particles need a numeric value. The first two use decimal-style values, while SHRIEK is treated as an integer.

Example:

particle:
  effect: SHRIEK
  data:
    value: 10

Trail particles

This is used for:

• TRAIL

This particle needs a target position, a color, and a duration.

The target is written as relative coordinates. The duration must be a positive number.

Example:

particle:
  effect: TRAIL
  data:
    target:
      x: 0.0
      y: 1.0
      z: 0.0
    color: "#3366FF"
    duration: 20

Vibration particles

This is used for:

• VIBRATION

This particle is the most detailed setup supported by SkinEngine. It needs an origin, a destination, and an arrival time.

The destination can point either to a relative block position or to an entity anchor. For entity-based destinations, SkinEngine currently supports OWNER and VIEWER.

Block destination example:

particle:
  effect: VIBRATION
  data:
    origin:
      x: 0.0
      y: 0.5
      z: 0.0
    destination:
      type: block
      target:
        x: 1.0
        y: 0.0
        z: 0.0
    arrival-time: 15

Entity destination example:

particle:
  effect: VIBRATION
  data:
    origin:
      x: 0.0
      y: 0.5
      z: 0.0
    destination:
      type: entity
      anchor: OWNER
    arrival-time: 15

Practical advice

If you are not sure where to begin, start with a simple particle name first and make sure the effect appears in-game before you tune anything else.

After that:

• add a full section only when you need finer control
• only add extra data when the selected particle really requires it
• keep particle counts moderate so the effect stays clean and readable
• use armor particles for persistent aura-style visuals
• use item particles for moments of action such as hits, shots, casts, shield blocks, and elytra glide trails

Related pages

• Skin Files
• Skin Categories
• Plugin Configuration