Particle Compositions

Particle compositions are HOCON files that define visual effects for lures. Stack multiple layers with different shapes, particles, and timing to build complex effects from simple building blocks.

config/bloom/particles/
├── grass_aura.conf
├── fire_blaze.conf
└── electric_surge.conf

Three example compositions are generated on first startup. Reference them in your lure’s particle_composition field by filename (without .conf):

"particle_composition": "grass_aura"

Composition Structure

Every composition file has two fields: a playback mode and a list of layers.

playback = "LOOPING"
layers = [
  {
    shape = "circle"
    particle = "minecraft:flame"
    count = 1
    speed = 0.01
    durationTicks = 60
    offset = { x = 0.0, y = 0.0, z = 0.0 }
    params = {
      radius = 2.5
      points = 6
    }
  }
]

Playback Mode : LOOPING replays the composition continuously. ONE_SHOT plays it once and stops.

Layers : Each layer is one shape rendered with one particle type. Stack multiple layers to combine effects — a helix of flames inside a ring of sparks, for example.

Layer Fields

Every layer shares these common fields:

Field	Type	Default	Description
`shape`	String	—	Shape type (see below)
`particle`	String	—	Minecraft particle ID (e.g. `minecraft:flame`)
`count`	Int	`1`	Particles spawned per point
`speed`	Float	`0.01`	Particle speed/spread
`durationTicks`	Int	`60`	Duration of one animation cycle in ticks
`offset`	Object	`{x:0, y:0, z:0}`	Position offset from the lure center

The offset field shifts the entire shape. Use it to stack layers vertically — one ring at ground level, another floating above.

Shapes

Seven shape types are available. Each has its own parameters under the params block.

Circle

A flat ring of particles on the horizontal plane.

{
  shape = "circle"
  particle = "minecraft:happy_villager"
  count = 1
  speed = 0.01
  durationTicks = 40
  params = {
    radius = 2.0
    points = 16
  }
}

Parameter	Default	Description
`radius`	`1.0`	Circle radius
`points`	`32`	Number of points around the circle

Sphere

Particles distributed across a sphere surface.

{
  shape = "sphere"
  particle = "minecraft:end_rod"
  count = 1
  speed = 0.02
  durationTicks = 60
  params = {
    radius = 3.0
    points = 24
  }
}

Parameter	Default	Description
`radius`	`1.0`	Sphere radius
`points`	`32`	Number of points on the sphere

Helix

A spiral that winds upward.

{
  shape = "helix"
  particle = "minecraft:flame"
  count = 1
  speed = 0.01
  durationTicks = 80
  params = {
    radius = 1.5
    height = 3.0
    revolutions = 2.0
    points = 48
  }
}

Parameter	Default	Description
`radius`	`1.0`	Helix radius
`height`	`3.0`	Total height
`revolutions`	`2.0`	Number of full rotations
`points`	`32`	Points along the spiral

Ring

A torus (donut) shape with configurable thickness.

{
  shape = "ring"
  particle = "minecraft:electric_spark"
  count = 1
  speed = 0.01
  durationTicks = 40
  params = {
    radius = 2.0
    thickness = 0.3
    points = 20
  }
}

Parameter	Default	Description
`radius`	`1.0`	Ring radius
`thickness`	`0.1`	Ring thickness
`points`	`32`	Points around the ring

Cone

An upward-pointing cone from a base circle to a point.

{
  shape = "cone"
  particle = "minecraft:soul_fire_flame"
  count = 1
  speed = 0.01
  durationTicks = 60
  params = {
    baseRadius = 2.0
    height = 4.0
    points = 24
  }
}

Parameter	Default	Description
`baseRadius`	`1.0`	Cone base radius
`height`	`3.0`	Cone height
`points`	`32`	Points along the cone

Burst

An outward burst of particles from the center.

{
  shape = "burst"
  particle = "minecraft:totem_of_undying"
  count = 2
  speed = 0.05
  durationTicks = 20
  params = {
    radius = 3.0
    points = 16
  }
}

Parameter	Default	Description
`radius`	`1.0`	Burst radius
`points`	`32`	Number of burst particles

Line

A straight line between two points.

{
  shape = "line"
  particle = "minecraft:portal"
  count = 1
  speed = 0.01
  durationTicks = 40
  params = {
    startX = 0.0
    startY = 0.0
    startZ = 0.0
    endX = 0.0
    endY = 3.0
    endZ = 0.0
    points = 12
  }
}

Parameter	Default	Description
`startX/Y/Z`	`0.0`	Line start point
`endX/Y/Z`	`0.0/3.0/0.0`	Line end point
`points`	`32`	Points along the line

Complete Examples

Grass Aura

A gentle green circle with floating leaves:

playback = "LOOPING"
layers = [
  {
    shape = "circle"
    particle = "minecraft:happy_villager"
    count = 1
    speed = 0.02
    durationTicks = 60
    offset = { x = 0.0, y = 0.2, z = 0.0 }
    params = {
      radius = 2.5
      points = 8
    }
  }
  {
    shape = "helix"
    particle = "minecraft:cherry_leaves"
    count = 1
    speed = 0.01
    durationTicks = 80
    offset = { x = 0.0, y = 0.0, z = 0.0 }
    params = {
      radius = 1.0
      height = 2.5
      revolutions = 1.5
      points = 20
    }
  }
]

Fire Blaze

Flames spiraling upward with a burst base:

playback = "LOOPING"
layers = [
  {
    shape = "helix"
    particle = "minecraft:flame"
    count = 1
    speed = 0.01
    durationTicks = 60
    offset = { x = 0.0, y = 0.0, z = 0.0 }
    params = {
      radius = 1.5
      height = 3.0
      revolutions = 2.0
      points = 32
    }
  }
  {
    shape = "circle"
    particle = "minecraft:soul_fire_flame"
    count = 1
    speed = 0.02
    durationTicks = 40
    offset = { x = 0.0, y = 0.1, z = 0.0 }
    params = {
      radius = 2.0
      points = 12
    }
  }
]

Electric Surge

Sparks in a sphere with vertical bolts:

playback = "LOOPING"
layers = [
  {
    shape = "sphere"
    particle = "minecraft:electric_spark"
    count = 1
    speed = 0.03
    durationTicks = 30
    offset = { x = 0.0, y = 1.0, z = 0.0 }
    params = {
      radius = 2.0
      points = 16
    }
  }
  {
    shape = "line"
    particle = "minecraft:electric_spark"
    count = 2
    speed = 0.05
    durationTicks = 10
    offset = { x = 0.0, y = 0.0, z = 0.0 }
    params = {
      startX = 0.0
      startY = 0.0
      startZ = 0.0
      endX = 0.0
      endY = 3.0
      endZ = 0.0
      points = 8
    }
  }
]

Tips

Next Steps

Creating Lures — Reference particle compositions from your lure definitions
Configuration Reference — Global particle settings and timing