ref: kdoc

Author: emyfops

common/src/main/kotlin/com/lambda/config/groups/RotationSettings.kt

@@ -9,18 +9,28 @@ class RotationSettings(
     c: Configurable,
     vis: () -> Boolean = { true },
 ) : IRotationConfig {
+    /**
+     * The rotation mode
+     */
     override var rotationMode by c.setting(
         "Mode",
         RotationMode.SYNC,
         "SILENT - server-side rotation, SYNC - server-side rotation; client-side movement, LOCK - Lock camera",
         vis
     )
 
+    /**
+     * How many ticks to keep the rotation before resetting
+     */
     override val keepTicks by c.setting("Keep Rotation", 3, 0..10, 1, "Ticks to keep rotation", " ticks", vis)
+
+    /**
+     * How many ticks to wait before resetting the rotation
+     */
     override val resetTicks by c.setting("Reset Rotation", 3, 1..10, 1, "Ticks before rotation is reset", " ticks", vis)
 
     /**
-     * If true, rotation will be instant without any transition. If false, rotation will transition over time.
+     * Whether the rotation is instant
      */
     var instant by c.setting("Instant Rotation", true, "Instantly rotate", vis)
 
@@ -51,8 +61,8 @@ class RotationSettings(
     ) { vis() && !instant }
 
     /**
-     * We always have to pass turn speed to the interpolator, because player's yaw could be out of -180..180 range and
-     * Thus we cant simply assign new angles to the player's rotation without getting flagged by Grim's AimModulo360 check
+     * We must always provide turn speed to the interpolator because the player's yaw might exceed the -180 to 180 range.
+     * Therefore, we cannot simply assign new angles to the player's rotation without getting flagged by Grim's AimModulo360 check.
      */
     override val turnSpeed get() = if (instant) 180.0 else abs(mean + spread * nextRandom())
 
@@ -64,4 +74,4 @@ class RotationSettings(
 
         return sqrt(-2.0 * ln(u1)) * cos(2.0 * PI * u2)
     }
-}
+}

common/src/main/kotlin/com/lambda/config/groups/Targeting.kt

@@ -13,24 +13,78 @@ import net.minecraft.entity.LivingEntity
 import net.minecraft.entity.mob.MobEntity
 import net.minecraft.entity.passive.PassiveEntity
 
+/**
+ * Abstract class representing a targeting mechanism for entities in the game.
+ *
+ * This class provides the configuration and validation for targeting different types of entities
+ * based on player settings and entity characteristics. It allows for specifying which types of entities
+ * are targetable, the range of targeting, and various other conditions for targeting.
+ *
+ * @property owner The [Configurable] instance used to get and set configuration options for targeting.
+ * @property predicate The predicate used to determine whether the targeting settings are visible and active.
+ * @property defaultRange The default range within which entities can be targeted.
+ * @property maxRange The maximum range within which entities can be targeted.
+ */
 abstract class Targeting(
-    c: Configurable,
-    vis: () -> Boolean = { true },
+    owner: Configurable,
+    predicate: () -> Boolean = { true },
     defaultRange: Double,
     maxRange: Double
 ) : TargetingConfig {
-    override val targetingRange by c.setting("Targeting Range", defaultRange, 1.0..maxRange, 0.05) { vis() }
 
-    override val players by c.setting("Players", true) { vis() }
-    private val mobs by c.setting("Mobs", true) { vis() }
-    private val hostilesSetting by c.setting("Hostiles", true) { vis() && mobs }
-    private val animalsSetting by c.setting("Animals", true) { vis() && mobs }
+    /**
+     * The range within which entities can be targeted. This value is configurable and constrained
+     * between 1.0 and [maxRange].
+     */
+    override val targetingRange by owner.setting("Targeting Range", defaultRange, 1.0..maxRange, 0.05) { predicate() }
+
+    /**
+     * Whether players are included in the targeting scope.
+     */
+    override val players by owner.setting("Players", true) { predicate() }
+
+    /**
+     * Whether mobs are included in the targeting scope.
+     */
+    private val mobs by owner.setting("Mobs", true) { predicate() }
+
+    /**
+     * Whether hostile mobs are included in the targeting scope
+     */
+    private val hostilesSetting by owner.setting("Hostiles", true) { predicate() && mobs }
+
+    /**
+     * Whether passive animals are included in the targeting scope
+     */
+    private val animalsSetting by owner.setting("Animals", true) { predicate() && mobs }
+
+    /**
+     * Indicates whether hostile entities are included in the targeting scope.
+     */
     override val hostiles get() = mobs && hostilesSetting
+
+    /**
+     * Indicates whether passive animals are included in the targeting scope.
+     */
     override val animals get() = mobs && animalsSetting
 
-    override val invisible by c.setting("Invisible", true) { vis() }
-    override val dead by c.setting("Dead", false) { vis() }
+    /**
+     * Whether invisible entities are included in the targeting scope.
+     */
+    override val invisible by owner.setting("Invisible", true) { predicate() }
 
+    /**
+     * Whether dead entities are included in the targeting scope.
+     */
+    override val dead by owner.setting("Dead", false) { predicate() }
+
+    /**
+     * Validates whether a given entity is targetable by the player based on current settings.
+     *
+     * @param player The [ClientPlayerEntity] performing the targeting.
+     * @param entity The [LivingEntity] being evaluated.
+     * @return `true` if the entity is valid for targeting, `false` otherwise.
+     */
     open fun validate(player: ClientPlayerEntity, entity: LivingEntity) = when {
         !players && entity.isPlayer -> false
         !animals && entity is PassiveEntity -> false
@@ -42,18 +96,44 @@ abstract class Targeting(
         else -> true
     }
 
+    /**
+     * Subclass for targeting entities specifically for combat purposes.
+     *
+     * @property fov The field of view limit within which entities are considered for targeting. Configurable.
+     * @property priority The priority used to determine which entity is targeted when multiple candidates are available.
+     */
     class Combat(
-        c: Configurable,
-        vis: () -> Boolean = { true },
-    ) : Targeting(c, vis, 5.0, 16.0) {
-        val fov by c.setting("FOV Limit", 180, 5..180, 1) { vis() }
-        val priority by c.setting("Priority", Priority.DISTANCE) { vis() }
+        owner: Configurable,
+        predicate: () -> Boolean = { true },
+    ) : Targeting(owner, predicate, 5.0, 16.0) {
+
+        /**
+         * The field of view limit for targeting entities. Configurable between 5 and 180 degrees.
+         */
+        val fov by owner.setting("FOV Limit", 180, 5..180, 1) { predicate() }
+
+        /**
+         * The priority used to determine which entity is targeted. Configurable with default set to [Priority.DISTANCE].
+         */
+        val priority by owner.setting("Priority", Priority.DISTANCE) { predicate() }
 
+        /**
+         * Validates whether a given entity is targetable for combat based on the field of view limit and other settings.
+         *
+         * @param player The [ClientPlayerEntity] performing the targeting.
+         * @param entity The [LivingEntity] being evaluated.
+         * @return `true` if the entity is valid for targeting, `false` otherwise.
+         */
         override fun validate(player: ClientPlayerEntity, entity: LivingEntity): Boolean {
             if (fov < 180 && player.rotation dist player.eyePos.rotationTo(entity.pos) > fov) return false
             return super.validate(player, entity)
         }
 
+        /**
+         * Gets the best target for combat based on the current settings and priority.
+         *
+         * @return The best [LivingEntity] target, or `null` if no valid target is found.
+         */
         fun getTarget(): LivingEntity? = runSafe {
             val predicate = { entity: LivingEntity ->
                 validate(player, entity)
@@ -67,15 +147,34 @@ abstract class Targeting(
         }
     }
 
+    /**
+     * Subclass for targeting entities for ESP (Extrasensory Perception) purposes.
+     */
     class ESP(
-        c: Configurable,
-        vis: () -> Boolean = { true },
-    ) : Targeting(c, vis, 128.0, 1024.0)
+        owner: Configurable,
+        predicate: () -> Boolean = { true },
+    ) : Targeting(owner, predicate, 128.0, 1024.0)
 
+    /**
+     * Enum representing the different priority factors used for determining the best target.
+     *
+     * @property factor A lambda function that calculates the priority factor for a given [LivingEntity].
+     */
     @Suppress("Unused")
     enum class Priority(val factor: SafeContext.(LivingEntity) -> Double) {
+        /**
+         * Prioritizes entities based on their distance from the player.
+         */
         DISTANCE({ player.pos distSq it.pos }),
+
+        /**
+         * Prioritizes entities based on their health.
+         */
         HEALTH({ it.health.toDouble() }),
+
+        /**
+         * Prioritizes entities based on their angle relative to the player's field of view.
+         */
         FOV({ player.rotation dist player.eyePos.rotationTo(it.pos) })
     }
 }