From 6c75204dda0bb7c44b8149d55276adfb63ce0be8 Mon Sep 17 00:00:00 2001
From: Bukkit/Spigot <noreply+git-bukkit@papermc.io>
Date: Tue, 26 Dec 2023 07:39:31 +1100
Subject: [PATCH] SPIGOT-6399, SPIGOT-7344: Clarify collidable behavior for
 player entities

By: DerFrZocker <derrieple@gmail.com>
---
 .../java/org/bukkit/entity/LivingEntity.java  | 27 +++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/paper-api/src/main/java/org/bukkit/entity/LivingEntity.java b/paper-api/src/main/java/org/bukkit/entity/LivingEntity.java
index 7c82644de3..7879082361 100644
--- a/paper-api/src/main/java/org/bukkit/entity/LivingEntity.java
+++ b/paper-api/src/main/java/org/bukkit/entity/LivingEntity.java
@@ -17,6 +17,8 @@ import org.bukkit.inventory.ItemStack;
 import org.bukkit.potion.PotionEffect;
 import org.bukkit.potion.PotionEffectType;
 import org.bukkit.projectiles.ProjectileSource;
+import org.bukkit.scoreboard.Scoreboard;
+import org.bukkit.scoreboard.Team;
 import org.bukkit.util.RayTraceResult;
 import org.bukkit.util.Vector;
 import org.jetbrains.annotations.NotNull;
@@ -561,6 +563,14 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      * <p>
      * Exemptions to this rule can be managed with
      * {@link #getCollidableExemptions()}
+     * <p>
+     * Note that the client may predict the collision between itself and another
+     * entity, resulting in this flag not working for player collisions. This
+     * method should therefore only be used to set the collision status of
+     * non-player entities.
+     * <p>
+     * To control player collisions, use {@link Team.Option#COLLISION_RULE} in
+     * combination with a {@link Scoreboard} and a {@link Team}.
      *
      * @param collidable collision status
      */
@@ -575,6 +585,15 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      * Please note that this method returns only the custom collidable state,
      * not whether the entity is non-collidable for other reasons such as being
      * dead.
+     * <p>
+     * Note that the client may predict the collision between itself and another
+     * entity, resulting in this flag not being accurate for player collisions.
+     * This method should therefore only be used to check the collision status
+     * of non-player entities.
+     * <p>
+     * To check the collision behavior for a player, use
+     * {@link Team.Option#COLLISION_RULE} in combination with a
+     * {@link Scoreboard} and a {@link Team}.
      *
      * @return collision status
      */
@@ -592,6 +611,14 @@ public interface LivingEntity extends Attributable, Damageable, ProjectileSource
      * entity is in this set then it will still collide with it.
      * <p>
      * Note these exemptions are not (currently) persistent.
+     * <p>
+     * Note that the client may predict the collision between itself and another
+     * entity, resulting in those exemptions not being accurate for player
+     * collisions. This method should therefore only be used to exempt
+     * non-player entities.
+     * <p>
+     * To exempt collisions for a player, use {@link Team.Option#COLLISION_RULE}
+     * in combination with a {@link Scoreboard} and a {@link Team}.
      *
      * @return the collidable exemption set
      */