[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.
+     *
+     * @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.
+     *
+     * @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, 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.
+     *
+     * @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);
+
+    /**
+     * 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.
+     *
+     * @param breeding whether the animal should try to breed.
+     */
+    public void setBreeding(boolean breeding);
+
+    /**
+    * Instantly breeds this animal with another.
+    * Will spawn a baby animal at this animal's location.
+    * The input animal must be of the same entity type as this animal.
+    * Both this animal and the input animal will be unable to breed natural
+    * for a short period of time.
+    * Returns the baby entity created, or null if the event was cancelled.
+    *
+    * @param animal the animal to breed with.
+    */
+    public Ageable breedWith(Animals animal);
+}

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

@@ -0,0 +1,108 @@
+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 entityTwo;
+    private final Ageable baby;
+    private Player breeder;
+    private boolean cancelled;
+    private int XP;
+
+    public EntityBreedEvent(final Animals entity, final Animals entityTwo, final Player breeder, final Ageable baby, final int XP) {
+        super(entity);
+        this.entityTwo = entityTwo;
+        this.breeder = breeder;
+        this.baby = baby;
+        this.XP = XP;
+    }
+
+    @Override
+    public Animals getEntity() {
+        return (Animals) entity;
+    }
+
+    /**
+    * Returns the living entity that the main entity has bred with.
+    *
+    * @return the living entity that was bred with.
+    */
+    public Animals getBredWith() {
+        return entityTwo;
+    }
+
+    /**
+    * Returns the (currently unspawned) baby entity.
+    *
+    * @return the baby entity.
+    */
+    public Ageable getBaby() {
+        return baby;
+    }
+
+    /**
+    * Gets the player that started the breeding, if any.
+    * If breeding was induced by plugin, may return null.
+    *
+    * @returns the breeder player, or null if none.
+    */
+    public Player getBreeder() {
+        return breeder;
+    }
+
+    /**
+    * Sets the player that is considered to have started the breeding,
+    * if any.
+    * The player set will receive potential rewards for breeding,
+    * (EG: an achievement).
+    * Set the player null to give nobody the reward.
+    *
+    * @param player the new breeder player, or null for none.
+    */
+    public void setBreeder(Player player) {
+        breeder = player;
+    }
+
+    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;
+    }
+}