Behaviors

A behavior is a reusable rule that reacts to something happening to an airdrop. Each one is:

TRIGGER  →  (optional) CONDITIONS  →  ACTIONS

You define behaviors once in behaviors.yml, then assign them to any airdrop from the in-game editor’s Behaviors button (it opens a selector where you toggle each one on/off). This replaced the old broadcast-*, commands-on-airdrop-* and explosion-on-drop-spawn options — those are migrated into behaviors automatically.

After editing behaviors.yml, run /airdrops reload to apply it.

Anatomy of a behavior

format-version: 1

behaviors:

  warn-unlock-5s:
    description: "Warns everyone 5 seconds before the airdrop unlocks"
    trigger: TICK
    conditions:
      - "%locked_seconds% == 5"
    actions:
      - type: message
        all: true
        text: "%prefix% &e%airdrop_name% &7opens in &c5 &7seconds!"
      - type: sound
        all: true
        sound: BLOCK_NOTE_BLOCK_PLING

description (optional) — a single line or a list of lines shown on the behavior’s button in the selector. Plain text, always yellow (color codes ignored).
trigger — when it runs (see below).
conditions (optional) — string expressions evaluated before the actions; if any fails, the deny-actions run instead (if present).
actions — what happens when the conditions pass.
deny-actions (optional) — what happens when a condition fails.
default: true (optional) — assigns the behavior to every airdrop automatically (it becomes the default of the Behaviors property). Any airdrop can still remove it from its own selector.

Triggers

Trigger	Fires when…
`SPAWN`	the airdrop block is placed in the world.
`DESPAWN`	the airdrop despawns (timed out or cleared).
`UNLOCK`	the unlock countdown reaches zero.
`START_UNLOCKING`	a player starts the unlock countdown by interacting.
`FIRST_OPEN`	the first time any player opens the airdrop.
`OPEN`	every time a player opens the airdrop inventory.
`OPEN_DENIED`	a player tries to open it while it’s still locked.
`TICK`	once per second, for every live airdrop (countdowns, animations).
`RESTORE`	a live airdrop is restored from the database after a restart.

Actions

Each action is a list entry with a type plus its parameters. Most player-facing actions accept all: true to target everyone online instead of just the triggering player.

`type`	Parameters	Description
`message`	`text:"..."` or `lang:"Messages.key"`, `all:`	Sends a chat message. `lang` pulls a line from `messages.yml`.
`title`	`title:` `subtitle:` `fade-in:` `stay:` `fade-out:` `all:`	Shows a title/subtitle (times in ticks).
`actionbar`	`text:` `all:`	Sends an action-bar message.
`sound`	`sound:` `volume:1.0` `pitch:1.0` `all:`	Plays a sound (Bukkit sound name).
`console`	`command:"eco give %player% 100"`	Runs a command from the console.
`player`	`command:"spawn"`	Runs a command as the triggering player.
`set_block`	`material:LIME_WOOL`	Changes the airdrop block’s material.
`effect`	`name:"my_effect"` `stop:false`	Starts (or stops) an effect defined in `effects.yml`.
`explosion`	`power:4.0` `set-fire:false` `break-blocks:false`	A real explosion. Damages nearby players — purely for impact, not cosmetics.
`webhook`	`url:` plus Discord or generic fields (below)	Sends an HTTP webhook, asynchronously.

Need cosmetics, not damage? Use the effect action with a particle effect — the explosion action actually hurts players and can break blocks.

Webhook action

For Discord, set url and optionally username, avatar-url, content, and an embed block:

  discord-on-spawn:
    trigger: SPAWN
    actions:
      - type: webhook
        url: "https://discord.com/api/webhooks/XXXX/YYYY"
        username: "UltimateAirdrops"
        embed:
          title: "%airdrop_name% has landed!"
          description: "An airdrop just spawned in the world."
          color: "#FFD700"
          fields:
            - name: "Coordinates"
              value: "%x_coord%, %y_coord%, %z_coord%"
              inline: true
            - name: "Players online"
              value: "%players_online%"
              inline: true

For non-Discord endpoints, send a raw payload instead: body:"<raw payload>" and content-type:"application/json".

Conditions

Conditions are string expressions evaluated before the actions. They support placeholders (below) and these forms:

Form	Example
Numeric / string compare	`"%locked_seconds% == 5"` — operators: `==` `!=` `>` `<` `>=` `<=`
Contains	`"%airdrop_name% contains Rare"` (or `!contains`)
Boolean	`"%airdrop_locked%"` / `"!%airdrop_locked%"`

If multiple conditions are listed, all must pass.

Placeholders

Available inside behavior text and conditions:

Placeholder	Meaning
`%airdrop_name%` `%airdrop_id%`	The airdrop’s name / id.
`%player%`	The triggering player’s name.
`%x_coord%` `%y_coord%` `%z_coord%`	The airdrop’s real coordinates.
`%max_corner_x_coord%` `%max_corner_z_coord%`	Max corner of the public (fuzzy) location.
`%min_corner_x_coord%` `%min_corner_z_coord%`	Min corner of the public location.
`%locked_time_left%` `%time_left%`	Formatted countdowns (unlock / despawn).
`%locked_seconds%` `%despawn_seconds%`	Raw second counts (for conditions).
`%players_online%`	Players currently online.
`%airdrop_locked%` `%airdrop_opened%`	`true` / `false` state flags.

PlaceholderAPI placeholders also work in behaviors that have a triggering player. [PlaceholderAPI]

Built-in sound behaviors

Four behaviors — sound-open, sound-open-locked, sound-start-unlocking, sound-unlock — are registered automatically and on by default. To retune one, define an entry in behaviors.yml with the same name; it overrides the built-in. Keep default: true to stay on by default.

  sound-open:
    trigger: OPEN
    default: true
    actions:
      - type: sound
        sound: ENTITY_PLAYER_LEVELUP
        volume: 1.0
        pitch: 1.0

More examples

  # A title for everyone when the airdrop lands
  title-on-spawn:
    trigger: SPAWN
    actions:
      - type: title
        all: true
        title: "&e%airdrop_name%"
        subtitle: "&7has landed!"
        fade-in: 10
        stay: 50
        fade-out: 10

  # Flash the block lime in the last 2 seconds of the lock
  flash-while-locked:
    trigger: TICK
    conditions:
      - "%airdrop_locked%"
      - "%locked_seconds% == 2"
    actions:
      - type: set_block
        material: LIME_WOOL

  # Play an effects.yml effect when the airdrop unlocks
  unlock-flare-fx:
    trigger: UNLOCK
    actions:
      - type: effect
        name: unlock-flare

  # A real explosion on spawn (damages players, no block damage)
  explosion-on-spawn:
    trigger: SPAWN
    actions:
      - type: explosion
        power: 4.0
        set-fire: false
        break-blocks: false

Custom actions (developers)

The action list is extensible. Third-party plugins can register their own ActionType through the API so it becomes usable as a type: in behaviors.yml.