Effects

An effect is a reusable visual: a laser or a particle shape. You define effects once in effects.yml, then use them in two ways:

Ambient — assign them to an airdrop from the editor’s Effects button so they play for the airdrop’s whole lifetime.
On-demand — start or stop them from a behavior’s effect action, e.g. a one-shot burst the moment the airdrop is opened.

Effects are purely cosmetic — to actually damage players or break blocks, use the explosion action in a behavior, not an effect.

Particles are sent with the long-distance flag, so they stay visible from far away (no client particle-distance limit) — the same reach the laser has. After editing effects.yml, run /airdrops reload.

Anatomy of an effect

format-version: 1

effects:

  spawn-helix:
    description: "A spinning flame helix around the airdrop"
    type: helix
    particle: FLAME
    radius: 1.2
    height: 4.0
    turns: 3
    points: 18
    speed: 0.15
    period: 1
    offset-y: 0.2

description (optional) — single line or list, shown on the effect’s button in the selector. Plain text, always yellow.
type — the effect type (see below). Determines which extra options apply.

Common particle options

These apply to every particle shape (circle, helix, sphere, point, torus, etc.):

Option	Default	Description
`particle`	—	Particle name, e.g. `FLAME`, `SOUL_FIRE_FLAME`, `HAPPY_VILLAGER`, `DUST`.
`color`	—	`"#RRGGBB"` — only the `DUST` / `REDSTONE` particle is colored.
`size`	`1.0`	Dust size.
`count`	`1`	Particles spawned per point.
`period`	`1`	Ticks between renders (higher = cheaper but choppier).
`offset-y`	`1.0`	Height above the airdrop block, in blocks.
`speed`	`0`	Radians the shape rotates per tick (`0` = static).
`duration`	`-1`	Ticks before the effect ends. `-1` = until despawn, `0` = one-shot.

Effect types

Each type adds its own options on top of the common ones:

`type`	Own options	Description
`laser`	`laser-type: GUARDIAN \| CRYSTAL`, `view-distance`, `height`	The classic beam pointing at the sky.
`point`	(common only)	A single particle point.
`circle`	`radius`, `points`	A flat ring.
`helix`	`radius`, `height`, `turns`, `points` (per turn)	A spiral.
`sphere`	`radius`, `points`	A particle sphere.
`torus`	`radius` (major), `tube` (minor), `points` (`speed` = spin)	A spinning donut.
`writhing_helix`	`radius`, `height`, `points` (`speed` = writhe rate)	A squirming column.
`expanding_circle`	`radius` (start), `end-radius`, `points` (`speed` = blocks/tick)	A ring that pulses outward.
`random`	`radius`, `points`	A random particle cloud.
`burst`	`spread`, `particle-speed`, `count`	A native particle explosion.

Lasers

Lasers are the simplest effect — a beam shooting up from the airdrop so players can spot it across the map. Two styles:

  laser:
    description: "A guardian beam pointing to the sky"
    type: laser
    laser-type: GUARDIAN
    view-distance: 300

  beacon:
    description: "An end-crystal beam pointing to the sky"
    type: laser
    laser-type: CRYSTAL
    view-distance: 300

The old laser-* config options are migrated into effects automatically.

Ambient effects

Assign these from the Effects button so they play for the airdrop’s whole life:

  ground-ring:
    description: "A slow ring of happy particles on the ground"
    type: circle
    particle: HAPPY_VILLAGER
    radius: 2.0
    points: 40
    speed: 0.05
    period: 4
    offset-y: 0.1

  aura:
    description: "A rotating coloured sphere around the airdrop"
    type: sphere
    particle: DUST
    color: "#33AAFF"
    size: 1.2
    radius: 1.4
    points: 120
    speed: 0.08
    period: 2
    offset-y: 1.2

  halo:
    description: "A spinning coloured donut hovering over the airdrop"
    type: torus
    particle: DUST
    color: "#FFAA00"
    radius: 1.4
    tube: 0.35
    points: 22
    speed: 0.07
    offset-y: 2.2

On-demand effects

Give these duration: 0 (one-shot) or a short duration, and trigger them from a behavior’s effect action — perfect for a flare on unlock or a burst on open:

  # effects.yml
  unlock-flare:
    type: helix
    particle: DUST
    color: "#FFD24A"
    radius: 0.3
    height: 2.5
    turns: 5
    points: 12
    speed: 0.35
    duration: 20
    offset-y: 0.2

  flame-burst:
    type: burst
    particle: FLAME
    spread: 0.6
    particle-speed: 0.15
    count: 40
    duration: 0
    offset-y: 0.6

  # behaviors.yml — play the flare when the airdrop unlocks
  unlock-flare-fx:
    trigger: UNLOCK
    actions:
      - type: effect
        name: unlock-flare

To stop an ambient effect early from a behavior, use stop: true:

      - type: effect
        name: aura
        stop: true