Add entity knockback events

- EntityKnockbackEvent
- EntityPushedByEntityAttackEvent
- EntityKnockbackByEntityEvent

Co-authored-by: aerulion <aerulion@gmail.com>
Co-authored-by: Jake Potrebic <jake.m.potrebic@gmail.com>

paper-api/src/main/java/io/papermc/paper/event/entity/EntityKnockbackEvent.java

@@ -0,0 +1,117 @@
+package io.papermc.paper.event.entity;
+
+import com.google.common.base.Preconditions;
+import org.bukkit.entity.Entity;
+import org.bukkit.event.Cancellable;
+import org.bukkit.event.HandlerList;
+import org.bukkit.event.entity.EntityEvent;
+import org.bukkit.util.Vector;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Called when an entity receives knockback.
+ * @see EntityPushedByEntityAttackEvent
+ * @see com.destroystokyo.paper.event.entity.EntityKnockbackByEntityEvent
+ */
+@NullMarked
+public class EntityKnockbackEvent extends EntityEvent implements Cancellable {
+
+    private static final HandlerList HANDLER_LIST = new HandlerList();
+
+    private final Cause cause;
+    protected Vector knockback;
+    private boolean cancelled;
+
+    @ApiStatus.Internal
+    public EntityKnockbackEvent(final Entity entity, final EntityKnockbackEvent.Cause cause, final Vector knockback) {
+        super(entity);
+        this.cause = cause;
+        this.knockback = knockback;
+    }
+
+    /**
+     * Gets the cause of the knockback.
+     *
+     * @return the cause of the knockback
+     */
+    public EntityKnockbackEvent.Cause getCause() {
+        return this.cause;
+    }
+
+    /**
+     * Gets the knockback force that will be applied to the entity. <br>
+     * This value is read-only, changes made to it <b>will not</b> have any
+     * effect on the final knockback received. Use {@link #setKnockback(Vector)}
+     * to make changes.
+     *
+     * @return the knockback
+     */
+    public Vector getKnockback() {
+        return this.knockback.clone();
+    }
+
+    /**
+     * Sets the knockback force that will be applied to the entity.
+     *
+     * @param knockback the knockback
+     */
+    public void setKnockback(final Vector knockback) {
+        Preconditions.checkArgument(knockback != null, "knockback");
+        this.knockback = knockback.clone();
+    }
+
+    @Override
+    public boolean isCancelled() {
+        return this.cancelled;
+    }
+
+    @Override
+    public void setCancelled(final boolean cancel) {
+        this.cancelled = cancel;
+    }
+
+    @Override
+    public HandlerList getHandlers() {
+        return HANDLER_LIST;
+    }
+
+    public static HandlerList getHandlerList() {
+        return HANDLER_LIST;
+    }
+
+    /**
+     * An enum to specify the cause of the knockback.
+     */
+    public enum Cause {
+
+        /**
+         * Knockback caused by non-entity damage.
+         */
+        DAMAGE,
+        /**
+         * Knockback caused by an attacking entity.
+         */
+        ENTITY_ATTACK,
+        /**
+         * Knockback caused by an explosion.
+         */
+        EXPLOSION,
+        /**
+         * Knockback caused by the target blocking with a shield.
+         */
+        SHIELD_BLOCK,
+        /**
+         * Knockback caused by a sweeping attack.
+         */
+        SWEEP_ATTACK,
+        /**
+         * A generic push.
+         */
+        PUSH,
+        /**
+         * Knockback with an unknown cause.
+         */
+        UNKNOWN
+    }
+}

paper-api/src/main/java/io/papermc/paper/event/entity/EntityPushedByEntityAttackEvent.java

@@ -0,0 +1,67 @@
+package io.papermc.paper.event.entity;
+
+import org.bukkit.entity.Entity;
+import org.bukkit.event.Cancellable;
+import org.bukkit.util.Vector;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Fired when an entity is pushed by another entity's attack. The acceleration vector can be
+ * modified. If this event is cancelled, the entity will not get pushed.
+ * <p>
+ * Note: Some entities might trigger this multiple times on the same entity
+ * as multiple acceleration calculations are done.
+ */
+@NullMarked
+public class EntityPushedByEntityAttackEvent extends EntityKnockbackEvent implements Cancellable {
+
+    private final Entity pushedBy;
+
+    @ApiStatus.Internal
+    public EntityPushedByEntityAttackEvent(final Entity entity, final EntityKnockbackEvent.Cause cause, final Entity pushedBy, final Vector knockback) {
+        super(entity, cause, knockback);
+        this.pushedBy = pushedBy;
+    }
+
+    /**
+     * Gets the entity which pushed the affected entity.
+     *
+     * @return the pushing entity
+     */
+    public Entity getPushedBy() {
+        return this.pushedBy;
+    }
+
+    /**
+     * Gets the acceleration that will be applied to the affected entity.
+     *
+     * @return the acceleration vector
+     * @deprecated use {@link #getKnockback()}
+     */
+    @Deprecated(since = "1.20.6", forRemoval = true)
+    public Vector getAcceleration() {
+        return this.knockback; // TODO Clone in 1.21 to not instantly break what was technically already modifiable (call super.getKnockback())
+    }
+
+    /**
+     * Sets the relative acceleration that will be applied to the affected entity.
+     *
+     * @param acceleration the new acceleration vector
+     * @deprecated use {@link #setKnockback(Vector)}
+     */
+    @Deprecated(since = "1.20.6", forRemoval = true)
+    public void setAcceleration(final Vector acceleration) {
+        super.setKnockback(acceleration);
+    }
+
+    @Override
+    public boolean isCancelled() {
+        return super.isCancelled();
+    }
+
+    @Override
+    public void setCancelled(final boolean cancel) {
+        super.setCancelled(cancel);
+    }
+}