Bukkit/Bukkit — pull request #687 by YLivay (2012-10-04 17:53:08+00:00)
Title: PlayerConsumeEvent - for food, potions or any other form of item consumption.

PlayerConsumeEvent:
----
### Purpose:
This event was created to handle the event when a player _finishes_ eating, drinking, using a potion or whatever sort of item consumption action he performed.
It comes after _PlayerInteractEvent_ and before the item's effects are applied and is cancellable.

### Usage:
The event contains a reference to the triggering _Player_ and a __clone__ of the _ItemStack_ that's involved in the consumption event. The reason I pass in a clone is that I don't think this is the place to modify an item that has been used up till now. It makes no sense that the pork chop you've been nibbling on would magically turn into a chicken leg and then be consumed.
The event can be cancelled so the item's effects will not be applied and the item will remain in the player's inventory. For any other information, refer to the javadocs.

### Relevance:
As it is now, the most common (and possibly easiest) way to detect such event is using _PlayerInteractEvent_ and putting up a delayed check to see if the item has been successfully consumed.
This method is not accurate, takes alot of manual case by case handling and overall is a waste of time and effort. For food you would have to check the food levels/saturation and hope it didn't change unexpectedly, and for potions its even worse, you might have to check the applied effects, or the empty glass bottle which you get after using it.

### Implementation:
Implementing this event is simple. Each _HumanEntity_ object has a method for when it finishes consuming an item. In this method the item's usage effects are applied and the new result item is returned. All you have to do is intercept it. This method is called for every type of item usage, therefor the generic name _PlayerConsumeEvent_ and not just _PlayerEatEvent_ or _PlayerPotionDrinkEvent_.

### Efficiency:
There's no reason to discuss the efficiency of such a small feature, but its the only place I can stress how much this simple event can help plugin developers avoid the hell of using the hackish way around using _PlayerInteractEvent_. It saved me around 300 lines of code (I'm very strict about my plugin's accuracy).

This is my first pull request to Bukkit, so be nice :)