feat: add activation range to player close by activity

Author: steveb05

extensions/EntityExtension/src/main/kotlin/com/typewritermc/entity/entries/activity/PlayerCloseByActivity.kt

@@ -10,6 +10,7 @@ import com.typewritermc.core.utils.point.distanceSqrt
 import com.typewritermc.engine.paper.entry.entity.*
 import com.typewritermc.engine.paper.entry.entries.EntityActivityEntry
 import com.typewritermc.engine.paper.entry.entries.GenericEntityActivityEntry
+import com.typewritermc.engine.paper.logger
 import com.typewritermc.engine.paper.utils.isLookable
 import java.time.Duration
 import java.util.*
@@ -24,13 +25,16 @@ import java.util.*
  * The `PlayerCloseByActivityEntry` is an activity that activates child activities when a viewer is close by.
  *
  * The activity will only activate when the viewer is within the defined range.
+ * If the activationRange is set, the activity will only activate when the viewer enters this smaller range after it has been deactivated.
  *
  * When the maximum idle duration is reached, the activity will deactivate.
  * If the maximum idle duration is set to 0, then it won't use the timer.
  *
  * ## How could this be used?
  * When the player has to follow the NPC and walks away, let the NPC wander around (or stand still) around the point the player walked away. When the player returns, resume its path.
  *
+ * If the activationRange is set, it can prevent the entity from repeatedly activating and deactivating when the player is at the edge of the range, or allow the player to get closer to the npc before it starts walking again.
+ *
  * When the npc is walking, and a player comes in range Stand still.
  */
 class PlayerCloseByActivityEntry(
@@ -39,6 +43,8 @@ class PlayerCloseByActivityEntry(
     @Help("The range in which the player has to be close by to activate the activity.")
     @Default("10.0")
     val range: Double = 10.0,
+    @Help("Optional range in which the player has to enter to activate the activity. Must be smaller than the main range.")
+    val activationRange: Optional<Double> = Optional.empty(),
     @Help("The maximum duration a player can be idle in the same range before the activity deactivates.")
     @Default("30000")
     val maxIdleDuration: Duration = Duration.ofSeconds(30),
@@ -51,8 +57,18 @@ class PlayerCloseByActivityEntry(
         context: ActivityContext,
         currentLocation: PositionProperty
     ): EntityActivity<in ActivityContext> {
+        val effectiveActivationRange = activationRange
+            .filter { it < range }
+            .orElseGet {
+                if (activationRange.isPresent) {
+                    logger.warning("Activation range (${activationRange.get()}) must be smaller than the main range ($range)")
+                }
+                range
+            }
+
         return PlayerCloseByActivity(
             range,
+            effectiveActivationRange,
             maxIdleDuration,
             closeByActivity,
             idleActivity,
@@ -63,12 +79,14 @@ class PlayerCloseByActivityEntry(
 
 class PlayerCloseByActivity(
     private val range: Double,
+    private val activationRange: Double,
     private val maxIdleDuration: Duration,
     private val closeByActivity: Ref<out EntityActivityEntry>,
     private val idleActivity: Ref<out EntityActivityEntry>,
     startLocation: PositionProperty,
 ) : SingleChildActivity<ActivityContext>(startLocation) {
     private var trackers = mutableMapOf<UUID, PlayerLocationTracker>()
+    private var isActive = false
 
     override fun currentChild(context: ActivityContext): Ref<out EntityActivityEntry> {
         val closeByPlayers = context.viewers
@@ -86,7 +104,16 @@ class PlayerCloseByActivity(
                 .update(player.location.toProperty())
         }
 
-        val isActive = trackers.any { (_, tracker) -> tracker.isActive(maxIdleDuration) }
+        val trackerActive = trackers.any { (_, tracker) -> tracker.isActive(maxIdleDuration) }
+
+        isActive = when {
+            isActive -> trackerActive
+            trackerActive -> trackers.any { (_, tracker) ->
+                tracker.isInActivationRange(currentPosition, activationRange, maxIdleDuration)
+            }
+            else -> false
+        }
+
         return if (isActive) {
             closeByActivity
         } else {
@@ -108,5 +135,16 @@ class PlayerCloseByActivity(
             if (maxIdleDuration.isZero) return true
             return System.currentTimeMillis() - lastSeen < maxIdleDuration.toMillis()
         }
+
+        fun isInActivationRange(
+            entityPosition: PositionProperty,
+            activationRange: Double,
+            maxIdleDuration: Duration
+        ): Boolean {
+            if (!isActive(maxIdleDuration)) return false
+
+            val distanceSq = location.distanceSqrt(entityPosition) ?: Double.MAX_VALUE
+            return distanceSq < activationRange * activationRange
+        }
     }
 }