Tools

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:

[email protected]!~&9Super Shovel

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

[email protected]!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
[email protected]<name>
player-specific
[email protected]<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 1
PROJECTILE_FISHING_ROD
death by fishing lure 1; alias: PROJECTILE_FISH
PROJECTILE_SNOW_BALL
death by thrown snowball 1
ANY_PROJECTILE
death by any projectile above (or any unclassified projectile)

1 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]