Effects

An effect is a reusable visual element: a laser or a particle shape. Effects are defined once in effects.yml and used in two ways:

Ambient — assigned to an airdrop from the Effects button of the editor, playing for the airdrop’s entire lifetime.
On demand — started or stopped from a behavior’s effect action, for example as a single burst when the airdrop is opened.

An effect that defines a duration, whether one-shot or timed, is not listed in the Effects selector and can only be started from a behavior’s effect action. The selector’s information button reports how many effects are loaded and how many of them can be assigned there.

Effects are purely cosmetic. To damage players or break blocks, use the explosion action in a behavior instead.

Particles are sent with the long-distance flag, so they remain visible beyond the client’s particle-distance limit, matching the range of the laser. Changes to effects.yml are applied with /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) — a single line or a list of lines displayed on the effect’s button in the selector. Rendered as plain yellow text.
type — the effect type, which determines the additional options that apply. See the table below.

Common particle options

The following options apply to every particle shape (circle, helix, sphere, point, torus and the rest):

Option	Default	Description
`particle`	—	Particle name, for example `FLAME`, `SOUL_FIRE_FLAME`, `HAPPY_VILLAGER` or `DUST`.
`color`	—	Colour in `"#RRGGBB"` format. Only the `DUST` and `REDSTONE` particles support colouring.
`size`	`1.0`	Dust size.
`count`	`1`	Number of particles spawned per point.
`period`	`1`	Ticks between renders. Higher values reduce cost and smoothness.
`offset-y`	`1.0`	Height above the airdrop block, in blocks.
`speed`	`0`	Radians the shape rotates per tick. `0` keeps it static.
`duration`	`-1`	Ticks before the effect ends. `-1` lasts until despawn, `0` renders once.

Effect types

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

`type`	Specific options	Description
`laser`	`laser-type: GUARDIAN \| CRYSTAL`, `view-distance`, `height`	A beam pointing at the sky. Not available on Minecraft 26.2 and newer, as described below.
`point`	(common options 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` controls the spin)	A rotating torus.
`writhing_helix`	`radius`, `height`, `points` (`speed` controls the writhe rate)	An animated, irregular column.
`expanding_circle`	`radius` (initial), `end-radius`, `points` (`speed` in blocks per tick)	A ring that expands outwards.
`random`	`radius`, `points`	A randomised particle cloud.
`burst`	`spread`, `particle-speed`, `count`	A native particle explosion.

Lasers

Lasers are the simplest effect: a beam projected upwards from the airdrop, making it visible across long distances. Two styles are available:

  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 former laser-* config options are migrated into effects automatically.

Minecraft 26.2 and newer: lasers are disabled. They are rendered by GuardianBeam, whose reflection layer is not compatible with those versions, so the effect becomes a no-op instead of failing on every spawn. One warning per laser effect is logged when effects.yml is loaded, both at startup and on every /airdrops reload. All other effect types are unaffected, and a particle shape such as a tall helix or a writhing_helix can be used as a replacement.

Ambient effects

The following effects are assigned from the Effects button and play for the airdrop’s entire lifetime:

  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

Effects defined with duration: 0 (one-shot) or a short duration are started from a behavior’s effect action, for example when an airdrop is unlocked or opened:

  # 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 — plays the flare when the airdrop unlocks
  unlock-flare-fx:
    trigger: UNLOCK
    actions:
      - type: effect
        name: unlock-flare

An ambient effect can also be stopped early from a behavior with stop: true:

      - type: effect
        name: aura
        stop: true