Bukkit

This page explains the use of "tools." A tool describes the inventory item, creature, or phenomenon which triggered a particular drop event. It can be checked using the "tool:" parameter (for syntax tips, see the Drop file page).

Valid Tools

Items

All items can be used as tools. This indicates the item was in hand when the player triggered the action.

Blocks

All blocks can be used as tools. This indicates the block was in hand, as above, though some blocks aren't normally found in players' inventories (see the Entity List for details). AIR can be used to denote an empty hand.

Creatures

Creatures can also be used as tools. This refers to the killing of some creature (or the player) by another creature, where the "tool" is defined as the creature that did the killing.

Tools can be specified with embedded data values.

Using Names

You can specify an event to only happen when triggered by a tool with a specific name attached to it. Remember that it's recommended to include colour coding in your tool names, because players can rename items via anvils! (Players cannot add colours to the items they rename.)

You can specify a name on a tool like so:

<ItemName>@!~<DisplayName>

An example would be this:

GOLD_SHOVEL@!~&9Super Shovel

If you want to combine enchantments and names, you need to specify the name last, like so:

IRON_CHESTPLATE@!THORNS#1~Thorny Shirt

If you want to specify a name alone, you can use just "~" without the "@!", but if you want to indicate an enchantment or some other extra data like damage values, you must include both "@" and "!", as "@" parses for extra data (including enchantments), and "!" parses for each enchantment.

Special Values

ANY / ALL

matches any tool (this is default behavior if "tool:" isn't specified)

PLAYER

object was destroyed/killed by some player

PLAYER@<name>

player-specific

PLAYERGROUP@<groupname>

not presently supported (as Bukkit permissions doesn't support groups)

Damage

ANY_DAMAGE

death/breakage by any DAMAGE_ types below

Applicable to Player/Creatures

DAMAGE_BURN

death by FIRE_TICK, FIRE or LAVA.

DAMAGE_FIRE

death by fire (could have been set on fire for various reasons)

DAMAGE_LAVA

death by immersion in lava (if set on fire by lava and dying then DAMAGE_FIRE applies)

DAMAGE_ENTITY_ATTACK

death by any creature, but only direct attacks; doesn't match projectiles

DAMAGE_BLOCK_EXPLOSION

death by block explosion (i.e. TNT)

DAMAGE_ENTITY_EXPLOSION

death by non-block entity explosion (i.e. creeper)

DAMAGE_CONTACT

death by block contact (i.e. cactus)

DAMAGE_DROWNING

death by drowning

DAMAGE_FALL

death from fall damage

DAMAGE_SUFFOCATION

death by suffocation (head in a block)

DAMAGE_STARVATION

player died from starvation

Applicable to Blocks

DAMAGE_WATER

destroyed by flowing water (Note: This feature is currently defunct.)

Projectiles

PROJECTILE_ARROW

death by flying arrow

PROJECTILE_FIREBALL

death by fireball; alias: PROJECTILE_FIRE

PROJECTILE_EGG

death by thrown egg ¹

PROJECTILE_FISHING_ROD

death by fishing lure ¹; alias: PROJECTILE_FISH

PROJECTILE_SNOW_BALL

death by thrown snowball ¹

ANY_PROJECTILE

death by any projectile above (or any unclassified projectile)

¹ These projectiles are normally harmless, but a separate plugin could change this behavior.

Projectiles support the optional data values @PLAYER and @DISPENSER to distinguish between projectiles fired by a player or by a dispenser.

Explosions

EXPLOSION_CREEPER

death by creeper explosion (or use some other creature name here if using a plugin that lets other creatures explode)

EXPLOSION_TNT

death by TNT explosion

EXPLOSION_FIREBALL

death by fireball explosion (ghast); alias: EXPLOSION_FIRE

ANY_EXPLOSION

death by any explosion above (or any unclassified explosion that originates from an entity)

Multiple Tools

Multiple tools can be listed in square brackets to indicate all are valid, such as tool: [DIAMOND_SWORD, GOLD_SWORD] to indicate a drop event which can be triggered using either a diamond sword or a gold sword.

Tools can also be excluded in the list by using a minus in front, eg: tool: [ANY_PICKAXE, -GOLD_PICKAXE]