[Bleeding] Fix Achievement and Statistic API. Fixes BUKKIT-5305

5 files changed, 532 insertions, 66 deletions

diff --git a/src/main/java/org/bukkit/Achievement.java b/src/main/java/org/bukkit/Achievement.java
index fc914d79..928b6d5d 100644
--- a/src/main/java/org/bukkit/Achievement.java
+++ b/src/main/java/org/bukkit/Achievement.java
@@ -1,49 +1,69 @@
 package org.bukkit;
 
 /**
- * Represents an achievement, which may be given to players
+ * Represents an achievement, which may be given to players.
  */
 public enum Achievement {
     OPEN_INVENTORY,
-    MINE_WOOD,
-    BUILD_WORKBENCH,
-    BUILD_PICKAXE,
-    BUILD_FURNACE,
-    ACQUIRE_IRON,
-    BUILD_HOE,
-    MAKE_BREAD,
-    BAKE_CAKE,
-    BUILD_BETTER_PICKAXE,
-    COOK_FISH,
-    ON_A_RAIL,
-    BUILD_SWORD,
-    KILL_ENEMY,
-    KILL_COW,
-    FLY_PIG,
-    SNIPE_SKELETON,
-    GET_DIAMONDS,
-    NETHER_PORTAL,
-    GHAST_RETURN,
-    GET_BLAZE_ROD,
-    BREW_POTION,
-    END_PORTAL,
-    THE_END,
-    ENCHANTMENTS,
-    OVERKILL,
-    BOOKCASE,
-    BREED_COW,
-    SPAWN_WITHER,
-    KILL_WITHER,
-    FULL_BEACON,
-    EXPLORE_ALL_BIOMES,
-    DIAMONDS_TO_YOU,
+    MINE_WOOD (OPEN_INVENTORY),
+    BUILD_WORKBENCH (MINE_WOOD),
+    BUILD_PICKAXE (BUILD_WORKBENCH),
+    BUILD_FURNACE (BUILD_PICKAXE),
+    ACQUIRE_IRON (BUILD_FURNACE),
+    BUILD_HOE (BUILD_WORKBENCH),
+    MAKE_BREAD (BUILD_HOE),
+    BAKE_CAKE (BUILD_HOE),
+    BUILD_BETTER_PICKAXE (BUILD_PICKAXE),
+    COOK_FISH (BUILD_FURNACE),
+    ON_A_RAIL (ACQUIRE_IRON),
+    BUILD_SWORD (BUILD_WORKBENCH),
+    KILL_ENEMY (BUILD_SWORD),
+    KILL_COW (BUILD_SWORD),
+    FLY_PIG (KILL_COW),
+    SNIPE_SKELETON (KILL_ENEMY),
+    GET_DIAMONDS (ACQUIRE_IRON),
+    NETHER_PORTAL (GET_DIAMONDS),
+    GHAST_RETURN (NETHER_PORTAL),
+    GET_BLAZE_ROD (NETHER_PORTAL),
+    BREW_POTION (GET_BLAZE_ROD),
+    END_PORTAL (GET_BLAZE_ROD),
+    THE_END (END_PORTAL),
+    ENCHANTMENTS (GET_DIAMONDS),
+    OVERKILL (ENCHANTMENTS),
+    BOOKCASE (ENCHANTMENTS),
+    EXPLORE_ALL_BIOMES (END_PORTAL),
+    SPAWN_WITHER (THE_END),
+    KILL_WITHER (SPAWN_WITHER),
+    FULL_BEACON (KILL_WITHER),
+    BREED_COW (KILL_COW),
+    DIAMONDS_TO_YOU (GET_DIAMONDS),
     ;
 
+    private final Achievement parent;
+
+    private Achievement() {
+        parent = null;
+    }
+
+    private Achievement(Achievement parent) {
+        this.parent = parent;
+    }
+
+    /**
+     * Returns whether or not this achievement has a parent achievement.
+     * 
+     * @return whether the achievement has a parent achievement
+     */
+    public boolean hasParent() {
+        return parent != null;
+    }
+
     /**
-     * The offset used to distinguish Achievements and Statistics.
-     *
-     * @deprecated Magic value
+     * Returns the parent achievement of this achievement, or null if none.
+     * 
+     * @return the parent achievement or null
      */
-    @Deprecated
-    public final static int STATISTIC_OFFSET = 0x500000;
+    public Achievement getParent() {
+        return parent;
+    }
 }
diff --git a/src/main/java/org/bukkit/Statistic.java b/src/main/java/org/bukkit/Statistic.java
index 4532123a..57df72ba 100644
--- a/src/main/java/org/bukkit/Statistic.java
+++ b/src/main/java/org/bukkit/Statistic.java
@@ -1,7 +1,7 @@
 package org.bukkit;
 
 /**
- * Represents a countable statistic, which is collected by the client
+ * Represents a countable statistic, which is tracked by the server.
  */
 public enum Statistic {
     DAMAGE_DEALT,
@@ -10,45 +10,99 @@ public enum Statistic {
     MOB_KILLS,
     PLAYER_KILLS,
     FISH_CAUGHT,
-    MINE_BLOCK(true),
-    USE_ITEM(false),
-    BREAK_ITEM(true);
+    ANIMALS_BRED,
+    TREASURE_FISHED,
+    JUNK_FISHED,
+    LEAVE_GAME,
+    JUMP,
+    DROP,
+    PLAY_ONE_TICK,
+    WALK_ONE_CM,
+    SWIM_ONE_CM,
+    FALL_ONE_CM,
+    CLIMB_ONE_CM,
+    FLY_ONE_CM,
+    DIVE_ONE_CM,
+    MINECART_ONE_CM,
+    BOAT_ONE_CM,
+    PIG_ONE_CM,
+    HORSE_ONE_CM,
+    MINE_BLOCK(Type.BLOCK),
+    USE_ITEM(Type.ITEM),
+    BREAK_ITEM(Type.ITEM),
+    CRAFT_ITEM(Type.ITEM),
+    KILL_ENTITY(Type.ENTITY),
+    ENTITY_KILLED_BY(Type.ENTITY);
 
-    private final boolean isSubstat;
-    private final boolean isBlock;
+    private final Type type;
 
     private Statistic() {
-        this(false, false);
+        this(Type.UNTYPED);
     }
 
-    private Statistic(boolean isBlock) {
-        this(true, isBlock);
+    private Statistic(Type type) {
+        this.type = type;
     }
 
-    private Statistic(boolean isSubstat, boolean isBlock) {
-        this.isSubstat = isSubstat;
-        this.isBlock = isBlock;
+    /**
+     * Gets the type of this statistic.
+     *
+     * @return the type of this statistic
+     */
+    public Type getType() {
+        return type;
     }
 
     /**
      * Checks if this is a substatistic.
      * <p>
-     * A substatistic exists in mass for each block or item, depending on
-     * {@link #isBlock()}
+     * A substatistic exists en masse for each block, item, or entitytype, depending on
+     * {@link #getType()}.
+     * <p>
+     * This is a redundant method and equivalent to checking
+     * <code>getType() != Type.UNTYPED</code>
      *
      * @return true if this is a substatistic
      */
     public boolean isSubstatistic() {
-        return isSubstat;
+        return type != Type.UNTYPED;
     }
 
     /**
-     * Checks if this is a substatistic dealing with blocks (As opposed to
-     * items)
+     * Checks if this is a substatistic dealing with blocks.
+     * <p>
+     * This is a redundant method and equivalent to checking
+     * <code>getType() == Type.BLOCK</code>
      *
-     * @return true if this deals with blocks, false if with items
+     * @return true if this deals with blocks
      */
     public boolean isBlock() {
-        return isSubstat && isBlock;
+        return type == Type.BLOCK;
+    }
+
+    /**
+     * The type of statistic.
+     *
+     */
+    public enum Type {
+        /**
+         * Statistics of this type do not require a qualifier.
+         */
+        UNTYPED,
+
+        /**
+         * Statistics of this type require an Item Material qualifier.
+         */
+        ITEM,
+
+        /**
+         * Statistics of this type require a Block Material qualifier.
+         */
+        BLOCK,
+
+        /**
+         * Statistics of this type require an EntityType qualifier.
+         */
+        ENTITY;
     }
 }
diff --git a/src/main/java/org/bukkit/entity/Player.java b/src/main/java/org/bukkit/entity/Player.java
index 7aa697d5..3c096f5b 100644
--- a/src/main/java/org/bukkit/entity/Player.java
+++ b/src/main/java/org/bukkit/entity/Player.java
@@ -323,43 +323,273 @@ public interface Player extends HumanEntity, Conversable, CommandSender, Offline
     public void updateInventory();
 
     /**
-     * Awards this player the given achievement
+     * Awards the given achievement and any parent achievements that the
+     * player does not have.
      *
      * @param achievement Achievement to award
+     * @throws IllegalArgumentException if achievement is null
      */
     public void awardAchievement(Achievement achievement);
 
     /**
-     * Increments the given statistic for this player
+     * Removes the given achievement and any children achievements that the
+     * player has.
+     *
+     * @param achievement Achievement to remove
+     * @throws IllegalArgumentException if achievement is null
+     */
+    public void removeAchievement(Achievement achievement);
+
+    /**
+     * Gets whether this player has the given achievement.
+     *
+     * @return whether the player has the achievement
+     * @throws IllegalArgumentException if achievement is null
+     */
+    public boolean hasAchievement(Achievement achievement);
+
+    /**
+     * Increments the given statistic for this player.
+     * <p>
+     * This is equivalent to the following code:
+     * <code>incrementStatistic(Statistic, 1)</code>
      *
      * @param statistic Statistic to increment
+     * @throws IllegalArgumentException if statistic is null
+     * @throws IllegalArgumentException if the statistic requires an
+     *     additional parameter
      */
-    public void incrementStatistic(Statistic statistic);
+    public void incrementStatistic(Statistic statistic) throws IllegalArgumentException;
 
     /**
-     * Increments the given statistic for this player
+     * Decrements the given statistic for this player.
+     * <p>
+     * This is equivalent to the following code:
+     * <code>decrementStatistic(Statistic, 1)</code>
+     *
+     * @param statistic Statistic to decrement
+     * @throws IllegalArgumentException if statistic is null
+     * @throws IllegalArgumentException if the statistic requires an
+     *     additional parameter
+     */
+    public void decrementStatistic(Statistic statistic) throws IllegalArgumentException;
+
+    /**
+     * Increments the given statistic for this player.
      *
      * @param statistic Statistic to increment
      * @param amount Amount to increment this statistic by
+     * @throws IllegalArgumentException if statistic is null
+     * @throws IllegalArgumentException if amount is negative
+     * @throws IllegalArgumentException if the statistic requires an
+     *     additional parameter
+     */
+    public void incrementStatistic(Statistic statistic, int amount) throws IllegalArgumentException;
+
+    /**
+     * Decrements the given statistic for this player.
+     *
+     * @param statistic Statistic to decrement
+     * @param amount Amount to decrement this statistic by
+     * @throws IllegalArgumentException if statistic is null
+     * @throws IllegalArgumentException if amount is negative
+     * @throws IllegalArgumentException if the statistic requires an
+     *     additional parameter
+     */
+    public void decrementStatistic(Statistic statistic, int amount) throws IllegalArgumentException;
+
+    /**
+     * Sets the given statistic for this player.
+     *
+     * @param statistic Statistic to set
+     * @param newValue The value to set this statistic to
+     * @throws IllegalArgumentException if statistic is null
+     * @throws IllegalArgumentException if newValue is negative
+     * @throws IllegalArgumentException if the statistic requires an
+     *     additional parameter
+     */
+    public void setStatistic(Statistic statistic, int newValue) throws IllegalArgumentException;
+
+    /**
+     * Gets the value of the given statistic for this player.
+     *
+     * @param statistic Statistic to check
+     * @return the value of the given statistic
+     * @throws IllegalArgumentException if statistic is null
+     * @throws IllegalArgumentException if the statistic requires an
+     *     additional parameter
      */
-    public void incrementStatistic(Statistic statistic, int amount);
+    public int getStatistic(Statistic statistic) throws IllegalArgumentException;
 
     /**
-     * Increments the given statistic for this player for the given material
+     * Increments the given statistic for this player for the given material.
+     * <p>
+     * This is equivalent to the following code:
+     * <code>incrementStatistic(Statistic, Material, 1)</code>
      *
      * @param statistic Statistic to increment
      * @param material Material to offset the statistic with
+     * @throws IllegalArgumentException if statistic is null
+     * @throws IllegalArgumentException if material is null
+     * @throws IllegalArgumentException if the given parameter is not valid
+     *     for the statistic
      */
-    public void incrementStatistic(Statistic statistic, Material material);
+    public void incrementStatistic(Statistic statistic, Material material) throws IllegalArgumentException;
 
     /**
-     * Increments the given statistic for this player for the given material
+     * Decrements the given statistic for this player for the given material.
+     * <p>
+     * This is equivalent to the following code:
+     * <code>decrementStatistic(Statistic, Material, 1)</code>
+     *
+     * @param statistic Statistic to decrement
+     * @param material Material to offset the statistic with
+     * @throws IllegalArgumentException if statistic is null
+     * @throws IllegalArgumentException if material is null
+     * @throws IllegalArgumentException if the given parameter is not valid
+     *     for the statistic
+     */
+    public void decrementStatistic(Statistic statistic, Material material) throws IllegalArgumentException;
+
+    /**
+     * Gets the value of the given statistic for this player.
+     *
+     * @param statistic Statistic to check
+     * @param material Material offset of the statistic
+     * @return the value of the given statistic
+     * @throws IllegalArgumentException if statistic is null
+     * @throws IllegalArgumentException if material is null
+     * @throws IllegalArgumentException if the given parameter is not valid
+     *     for the statistic
+     */
+    public int getStatistic(Statistic statistic, Material material) throws IllegalArgumentException;
+
+    /**
+     * Increments the given statistic for this player for the given material.
      *
      * @param statistic Statistic to increment
      * @param material Material to offset the statistic with
      * @param amount Amount to increment this statistic by
+     * @throws IllegalArgumentException if statistic is null
+     * @throws IllegalArgumentException if material is null
+     * @throws IllegalArgumentException if amount is negative
+     * @throws IllegalArgumentException if the given parameter is not valid
+     *     for the statistic
+     */
+    public void incrementStatistic(Statistic statistic, Material material, int amount) throws IllegalArgumentException;
+
+    /**
+     * Decrements the given statistic for this player for the given material.
+     *
+     * @param statistic Statistic to decrement
+     * @param material Material to offset the statistic with
+     * @param amount Amount to decrement this statistic by
+     * @throws IllegalArgumentException if statistic is null
+     * @throws IllegalArgumentException if material is null
+     * @throws IllegalArgumentException if amount is negative
+     * @throws IllegalArgumentException if the given parameter is not valid
+     *     for the statistic
+     */
+    public void decrementStatistic(Statistic statistic, Material material, int amount) throws IllegalArgumentException;
+
+    /**
+     * Sets the given statistic for this player for the given material.
+     *
+     * @param statistic Statistic to set
+     * @param material Material to offset the statistic with
+     * @param newValue The value to set this statistic to
+     * @throws IllegalArgumentException if statistic is null
+     * @throws IllegalArgumentException if material is null
+     * @throws IllegalArgumentException if newValue is negative
+     * @throws IllegalArgumentException if the given parameter is not valid
+     *     for the statistic
+     */
+    public void setStatistic(Statistic statistic, Material material, int newValue) throws IllegalArgumentException;
+
+    /**
+     * Increments the given statistic for this player for the given entity.
+     * <p>
+     * This is equivalent to the following code:
+     * <code>incrementStatistic(Statistic, EntityType, 1)</code>
+     *
+     * @param statistic Statistic to increment
+     * @param entityType EntityType to offset the statistic with
+     * @throws IllegalArgumentException if statistic is null
+     * @throws IllegalArgumentException if entityType is null
+     * @throws IllegalArgumentException if the given parameter is not valid
+     *     for the statistic
+     */
+    public void incrementStatistic(Statistic statistic, EntityType entityType) throws IllegalArgumentException;
+
+    /**
+     * Decrements the given statistic for this player for the given entity.
+     * <p>
+     * This is equivalent to the following code:
+     * <code>decrementStatistic(Statistic, EntityType, 1)</code>
+     *
+     * @param statistic Statistic to decrement
+     * @param entityType EntityType to offset the statistic with
+     * @throws IllegalArgumentException if statistic is null
+     * @throws IllegalArgumentException if entityType is null
+     * @throws IllegalArgumentException if the given parameter is not valid
+     *     for the statistic
+     */
+    public void decrementStatistic(Statistic statistic, EntityType entityType) throws IllegalArgumentException;
+
+    /**
+     * Gets the value of the given statistic for this player.
+     *
+     * @param statistic Statistic to check
+     * @param entityType EntityType offset of the statistic
+     * @return the value of the given statistic
+     * @throws IllegalArgumentException if statistic is null
+     * @throws IllegalArgumentException if entityType is null
+     * @throws IllegalArgumentException if the given parameter is not valid
+     *     for the statistic
+     */
+    public int getStatistic(Statistic statistic, EntityType entityType) throws IllegalArgumentException;
+
+    /**
+     * Increments the given statistic for this player for the given entity.
+     *
+     * @param statistic Statistic to increment
+     * @param entityType EntityType to offset the statistic with
+     * @param amount Amount to increment this statistic by
+     * @throws IllegalArgumentException if statistic is null
+     * @throws IllegalArgumentException if entityType is null
+     * @throws IllegalArgumentException if amount is negative
+     * @throws IllegalArgumentException if the given parameter is not valid
+     *     for the statistic
+     */
+    public void incrementStatistic(Statistic statistic, EntityType entityType, int amount) throws IllegalArgumentException;
+
+    /**
+     * Decrements the given statistic for this player for the given entity.
+     *
+     * @param statistic Statistic to decrement
+     * @param entityType EntityType to offset the statistic with
+     * @param amount Amount to decrement this statistic by
+     * @throws IllegalArgumentException if statistic is null
+     * @throws IllegalArgumentException if entityType is null
+     * @throws IllegalArgumentException if amount is negative
+     * @throws IllegalArgumentException if the given parameter is not valid
+     *     for the statistic
+     */
+    public void decrementStatistic(Statistic statistic, EntityType entityType, int amount);
+
+    /**
+     * Sets the given statistic for this player for the given entity.
+     *
+     * @param statistic Statistic to set
+     * @param entityType EntityType to offset the statistic with
+     * @param newValue The value to set this statistic to
+     * @throws IllegalArgumentException if statistic is null
+     * @throws IllegalArgumentException if entityType is null
+     * @throws IllegalArgumentException if newValue is negative
+     * @throws IllegalArgumentException if the given parameter is not valid
+     *     for the statistic
      */
-    public void incrementStatistic(Statistic statistic, Material material, int amount);
+    public void setStatistic(Statistic statistic, EntityType entityType, int newValue);
 
     /**
      * Sets the current time on the player's client. When relative is true the
diff --git a/src/main/java/org/bukkit/event/player/PlayerAchievementAwardedEvent.java b/src/main/java/org/bukkit/event/player/PlayerAchievementAwardedEvent.java
new file mode 100644
index 00000000..6e3fc3bb
--- /dev/null
+++ b/src/main/java/org/bukkit/event/player/PlayerAchievementAwardedEvent.java
@@ -0,0 +1,46 @@
+package org.bukkit.event.player;
+
+import org.bukkit.Achievement;
+import org.bukkit.entity.Player;
+import org.bukkit.event.Cancellable;
+import org.bukkit.event.HandlerList;
+
+/**
+ * Called when a player earns an achievement.
+ */
+public class PlayerAchievementAwardedEvent extends PlayerEvent implements Cancellable {
+    private static final HandlerList handlers = new HandlerList();
+    private final Achievement achievement;
+    private boolean isCancelled = false;
+
+    public PlayerAchievementAwardedEvent(Player player, Achievement achievement) {
+        super(player);
+        this.achievement = achievement;
+    }
+
+    /**
+     * Gets the Achievement being awarded.
+     * 
+     * @return the achievement being awarded
+     */
+    public Achievement getAchievement() {
+        return achievement;
+    }
+
+    public boolean isCancelled() {
+        return isCancelled;
+    }
+
+    public void setCancelled(boolean cancel) {
+        this.isCancelled = cancel;
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+}
diff --git a/src/main/java/org/bukkit/event/player/PlayerStatisticIncrementEvent.java b/src/main/java/org/bukkit/event/player/PlayerStatisticIncrementEvent.java
new file mode 100644
index 00000000..124a1bd3
--- /dev/null
+++ b/src/main/java/org/bukkit/event/player/PlayerStatisticIncrementEvent.java
@@ -0,0 +1,116 @@
+package org.bukkit.event.player;
+
+import org.bukkit.Material;
+import org.bukkit.Statistic;
+import org.bukkit.entity.EntityType;
+import org.bukkit.entity.Player;
+import org.bukkit.event.Cancellable;
+import org.bukkit.event.HandlerList;
+
+/**
+ * Called when a player statistic is incremented.
+ * <p>
+ * This event is not called for {@link org.bukkit.Statistic#PLAY_ONE_MINUTE}
+ * or movement based statistics.
+ *
+ */
+public class PlayerStatisticIncrementEvent extends PlayerEvent implements Cancellable {
+    private static final HandlerList handlers = new HandlerList();
+    protected final Statistic statistic;
+    private final int initialValue;
+    private final int newValue;
+    private boolean isCancelled = false;
+    private final EntityType entityType;
+    private final Material material;
+
+    public PlayerStatisticIncrementEvent(Player player, Statistic statistic, int initialValue, int newValue) {
+        super (player);
+        this.statistic = statistic;
+        this.initialValue = initialValue;
+        this.newValue = newValue;
+        this.entityType = null;
+        this.material = null;
+    }
+
+    public PlayerStatisticIncrementEvent(Player player, Statistic statistic, int initialValue, int newValue, EntityType entityType) {
+        super (player);
+        this.statistic = statistic;
+        this.initialValue = initialValue;
+        this.newValue = newValue;
+        this.entityType = entityType;
+        this.material = null;
+    }
+
+    public PlayerStatisticIncrementEvent(Player player, Statistic statistic, int initialValue, int newValue, Material material) {
+        super (player);
+        this.statistic = statistic;
+        this.initialValue = initialValue;
+        this.newValue = newValue;
+        this.entityType = null;
+        this.material = material;
+    }
+
+    /**
+     * Gets the statistic that is being incremented.
+     * 
+     * @return the incremented statistic
+     */
+    public Statistic getStatistic() {
+        return statistic;
+    }
+
+    /**
+     * Gets the previous value of the statistic.
+     * 
+     * @return the previous value of the statistic
+     */
+    public int getPreviousValue() {
+        return initialValue;
+    }
+
+    /**
+     * Gets the new value of the statistic.
+     * 
+     * @return the new value of the statistic
+     */
+    public int getNewValue() {
+        return newValue;
+    }
+
+    /**
+     * Gets the EntityType if {@link #getStatistic() getStatistic()} is an
+     * entity statistic otherwise returns null.
+     * 
+     * @return the EntityType of the statistic
+     */
+    public EntityType getEntityType() {
+        return entityType;
+    }
+
+    /**
+     * Gets the Material if {@link #getStatistic() getStatistic()} is a block
+     * or item statistic otherwise returns null.
+     * 
+     * @return the Material of the statistic
+     */
+    public Material getMaterial() {
+        return material;
+    }
+
+    public boolean isCancelled() {
+        return isCancelled;
+    }
+
+    public void setCancelled(boolean cancel) {
+        this.isCancelled = cancel;
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+}