Clarify mob persistence API

paper-api/src/main/java/org/bukkit/entity/LivingEntity.java

@@ -720,20 +720,28 @@ default boolean addPotionEffect(@NotNull PotionEffect effect, boolean force) {
     public boolean hasLineOfSight(@NotNull Location location);
 
     /**
-     * Returns if the living entity despawns when away from players or not.
+     * Gets whether this living entity is allowed to be removed when far away.
      * <p>
-     * By default, animals are not removed while other mobs are.
+     * For mobs, this is the inverse of {@link Mob#isPersistenceRequired()}.
+     * A return value of {@code true} does not guarantee that the mob will
+     * despawn, as other conditions may prevent despawning.
      *
-     * @return true if the living entity is removed when away from players
+     * @return true if this living entity is allowed to be removed when far away
+     * @deprecated use {@link Mob#isPersistenceRequired()} for mobs
      */
+    @Deprecated(since = "26.3")
     public boolean getRemoveWhenFarAway();
 
     /**
-     * Sets whether or not the living entity despawns when away from players
-     * or not.
+     * Sets whether this living entity is allowed to be removed when far away.
+     * <p>
+     * For mobs, this is the inverse of
+     * {@link Mob#setPersistenceRequired(boolean)}.
      *
-     * @param remove the removal status
+     * @param remove whether this living entity is allowed to be removed
+     * @deprecated use {@link Mob#setPersistenceRequired(boolean)} for mobs
      */
+    @Deprecated(since = "26.3")
     public void setRemoveWhenFarAway(boolean remove);
 
     /**

paper-api/src/main/java/org/bukkit/entity/Mob.java

@@ -16,6 +16,25 @@
  */
 @NullMarked
 public interface Mob extends LivingEntity, Lootable, Leashable {
+    /**
+     * Gets whether this mob has been marked as persistent.
+     * <p>
+     * Persistent mobs are not removed by the normal distance-based
+     * despawning process.
+     *
+     * @return true if this mob is persistent
+     */
+    boolean isPersistenceRequired();
+
+    /**
+     * Sets whether this mob has been marked as persistent.
+     * <p>
+     * Persistent mobs are not removed by the normal distance-based
+     * despawning process.
+     *
+     * @param persistenceRequired whether this mob should be persistent
+     */
+    void setPersistenceRequired(boolean persistenceRequired);
 
     /**
      * Check if a mob should be despawned when the world is set to peaceful difficulty.

paper-server/src/main/java/org/bukkit/craftbukkit/entity/CraftMob.java

@@ -16,6 +16,16 @@
 
 public abstract class CraftMob extends CraftLivingEntity implements Mob, io.papermc.paper.entity.PaperLeashable { // Paper - Leashable API
 
+    @Override
+    public boolean isPersistenceRequired() {
+        return this.getHandle().isPersistenceRequired();
+    }
+
+    @Override
+    public void setPersistenceRequired(boolean persistent) {
+        this.getHandle().persistenceRequired = persistent;
+    }
+
     private final com.destroystokyo.paper.entity.PaperPathfinder paperPathfinder; // Paper - Mob Pathfinding API
 
     public CraftMob(CraftServer server, net.minecraft.world.entity.Mob entity) {