[B+C] Add a way to induce mob breeding, adds BUKKIT-5687

src/main/java/org/bukkit/entity/Animals.java

@@ -1,6 +1,121 @@
 package org.bukkit.entity;
 
+import org.bukkit.entity.Player;
+import org.bukkit.entity.Ageable;
+
 /**
  * Represents an Animal.
  */
-public interface Animals extends Ageable {}
+public interface Animals extends Ageable {
+
+    /**
+     * Determines if this animal is currently breeding.
+     * An animal is considered to be breeding when it has been given food
+     * (EG: wheat) and is looking for another animal of its species to mate
+     * with and produce a baby animal.
+     * Will return false again if the breeding attempt timed out or after the
+     * mating was successful and a baby is spawned.
+     * Will return true if the entity is actively breeding but hasn't yet had
+     * a child.
+     *
+     * @return true if it is breeding.
+     */
+    public boolean isBreeding();
+
+    /**
+     * Set whether this animal is currently trying to breed.
+     * An animal is considered to be breeding when it has been given food
+     * (EG: wheat) and is looking for another animal of its species to mate
+     * with and produce a baby animal.
+     * If 'breeding' is true, this function has the same result as given the
+     * entity its breeding food (EG: wheat).
+     * If 'breeding' is false, this function will take away any desire to
+     * breed from the entity, and even stop an in-progress mating session.
+     * Specify a non-null player to indicate that the given player was the
+     * one who induced breeding, which will give any built in or plugin
+     * created rewards (EG: an achievement) to that player when the breeding
+     * is successful.
+     * Specify a null player to simply not reward a player for successful
+     * breeding.
+     * If the first argument is true, this will force the entity to be able
+     * to breed, which will turn baby animals into adults.
+     *
+     * @param breeding whether the animal should try to breed.
+     * @param player the player that induced the breeding.
+     * @param timeout how many ticks until the breeding state automatically
+     * cancels. The default is 600.
+     */
+    public void setBreeding(boolean breeding, Player player, int timeout);
+
+    /**
+     * Set whether this animal is currently trying to breed.
+     * An animal is considered to be breeding when it has been given food
+     * (EG: wheat) and is looking for another animal of its species to mate
+     * with and produce a baby animal.
+     * If 'breeding' is true, this function has the same result as given the
+     * entity its breeding food (EG: wheat).
+     * If 'breeding' is false, this function will take away any desire to
+     * breed from the entity, and even stop an in-progress mating session.
+     * This will assume a null player, meaning that no player will be given
+     * any rewards (EG: an achievement) for a successful breeding.
+     * Specify a null player to simply not reward a player for successful
+     * breeding.
+     * If the first argument is true, this will force the entity to be able
+     * to breed, which will turn baby animals into adults.
+     *
+     * @param breeding whether the animal should try to breed.
+     * @param timeout how many ticks until the breeding state automatically
+     * cancels. The default is 600.
+     */
+    public void setBreeding(boolean breeding, int timeout);
+
+    /**
+     * Set whether this animal is currently trying to breed.
+     * An animal is considered to be breeding when it has been given food
+     * (EG: wheat) and is looking for another animal of its species to mate
+     * with and produce a baby animal.
+     * If 'breeding' is true, this function has the same result as given the
+     * entity its breeding food (EG: wheat).
+     * If 'breeding' is false, this function will take away any desire to
+     * breed from the entity, and even stop an in-progress mating session.
+     * Specify a non-null player to indicate that the given player was the
+     * one who induced breeding, which will give any built in or plugin
+     * created rewards (EG: an achievement) to that player when the breeding
+     * is successful.
+     * Specify a null player to simply not reward a player for successful
+     * breeding.
+     * This will also assume a default breed timeout of 600 ticks.
+     * If the first argument is true, this will force the entity to be able
+     * to breed, which will turn baby animals into adults.
+     *
+     * @param breeding whether the animal should try to breed.
+     * @param player the player that induced the breeding.
+     */
+    public void setBreeding(boolean breeding, Player player);
+
+    /**
+     * Set whether this animal is currently trying to breed.
+     * An animal is considered to be breeding when it has been given food
+     * (EG: wheat) and is looking for another animal of its species to mate
+     * with and produce a baby animal.
+     * If 'breeding' is true, this function has the same result as given the
+     * entity its breeding food (EG: wheat).
+     * If 'breeding' is false, this function will take away any desire to
+     * breed from the entity, and even stop an in-progress mating session.
+     * This will assume a null player, meaning that no player will be given
+     * any rewards (EG: an achievement) for a successful breeding.
+     * This will also assume a default breed timeout of 600 ticks.
+     * If the first argument is true, this will force the entity to be able
+     * to breed, which will turn baby animals into adults.
+     *
+     * @param breeding whether the animal should try to breed.
+     */
+    public void setBreeding(boolean breeding);
+
+    /**
+     * Gets the Player that last caused this animal to breed, if any.
+     *
+     * @return the breeder player, or null if none.
+     */
+    public Player getBreeder();
+}

src/main/java/org/bukkit/event/entity/EntityBreedEvent.java

@@ -0,0 +1,75 @@
+package org.bukkit.event.entity;
+
+import org.bukkit.entity.Animals;
+import org.bukkit.entity.Ageable;
+import org.bukkit.entity.Player;
+import org.bukkit.event.Cancellable;
+import org.bukkit.event.HandlerList;
+
+/**
+ * Called when an {@link Animals} breeds with another animal.
+ */
+public class EntityBreedEvent extends EntityEvent implements Cancellable {
+    private static final HandlerList handlers = new HandlerList();
+    private final Animals parentOne;
+    private final Animals parentTwo;
+    private boolean cancelled;
+    private int xp;
+
+    public EntityBreedEvent(final Animals parentOne, final Animals parentTwo, final Ageable baby, final int xp) {
+        super(baby);
+        this.parentOne = parentOne;
+        this.parentTwo = parentTwo;
+        this.xp = xp;
+    }
+
+    @Override
+    public Ageable getEntity() {
+        return (Ageable) entity;
+    }
+
+    /**
+     * Returns an array containing both parent entities.
+     * The array always has a length of 2.
+     *
+     * @return an array of both parent entities.
+     */
+    public Animals[] getParents() {
+        return new Animals[] { parentOne, parentTwo };
+    }
+
+    public boolean isCancelled() {
+        return cancelled;
+    }
+
+    public void setCancelled(boolean cancel) {
+        cancelled = cancel;
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+
+    /**
+     * Gets the amount of experience that will be dropped by this event.
+     *
+     * @return the total amount of experience.
+     */
+    public int getExperience() {
+        return xp;
+    }
+
+    /**
+     * Changes the amount of XP this event will drop.
+     *
+     * @param newXP the amount of XP to drop.
+     */
+    public void setExperience(int newXP) {
+        xp = newXP;
+    }
+}