rotation manager and place manager docs

Author: beanbag44

src/main/kotlin/com/lambda/interaction/request/breaking/BrokenBlockHandler.kt

@@ -43,7 +43,7 @@ import net.minecraft.util.math.ChunkSectionPos
 
 /**
  * Designed to handle blocks that are deemed broken, yet are awaiting
- * confirmation from the server, and/or an item drop.
+ * confirmation from the server and/or an item drop.
  *
  * @see BreakManager
  */

src/main/kotlin/com/lambda/interaction/request/placing/PlaceManager.kt

@@ -69,6 +69,9 @@ import net.minecraft.util.math.BlockPos
 import net.minecraft.world.GameMode
 import kotlin.math.min
 
+/**
+ * Manager designed to place blocks.
+ */
 object PlaceManager : RequestHandler<PlaceRequest>(
     0,
     TickEvent.Pre,
@@ -135,11 +138,10 @@ object PlaceManager : RequestHandler<PlaceRequest>(
     }
 
     /**
-     * If the request is fresh, local variables are populated through the [processRequest] method.
-     * It then attempts to perform as many placements within this tick as possible from the [potentialPlacements] collection.
-     *
-     * If all the [maxPlacementsThisTick] limit is reached and the user has rotations enabled, it will start rotating to
-     * the next predicted placement in the list for optimal speed.
+     * Returns immediately if [BreakManager] or [InteractionManager] have been active this tick.
+     * Otherwise, for fresh requests, [populateFrom] is called to fill the [potentialPlacements] collection.
+     * It then attempts to perform as many placements as possible from the [potentialPlacements] collection within
+     * the [maxPlacementsThisTick] limit.
      *
      * @see populateFrom
      * @see placeBlock
@@ -182,7 +184,7 @@ object PlaceManager : RequestHandler<PlaceRequest>(
 
     /**
      * Filters the [request]'s [PlaceContext]s, placing them into the [potentialPlacements] collection, and
-     * setting the maxPlacementsThisTick value.
+     * setting other configurations.
      *
      * @see isPosBlocked
      */
@@ -205,9 +207,8 @@ object PlaceManager : RequestHandler<PlaceRequest>(
     }
 
     /**
-     * A modified version of the minecraft interactBlock method, renamed to better suit its usage.
-     *
-     * @see net.minecraft.client.network.ClientPlayerInteractionManager.interactBlock
+     * A modified version of the minecraft [net.minecraft.client.network.ClientPlayerInteractionManager.interactBlock] method,
+     * renamed to better suit its usage.
      */
     private fun AutomatedSafeContext.placeBlock(placeContext: PlaceContext, request: PlaceRequest, hand: Hand): ActionResult {
         interaction.syncSelectedSlot()
@@ -224,9 +225,7 @@ object PlaceManager : RequestHandler<PlaceRequest>(
     }
 
     /**
-     * A modified version of the minecraft interactBlockInternal method.
-     *
-     * @see net.minecraft.client.network.ClientPlayerInteractionManager.interactBlockInternal
+     * A modified version of the minecraft [net.minecraft.client.network.ClientPlayerInteractionManager.interactBlockInternal] method.
      */
     private fun AutomatedSafeContext.interactBlockInternal(
         placeContext: PlaceContext,
@@ -267,9 +266,7 @@ object PlaceManager : RequestHandler<PlaceRequest>(
     }
 
     /**
-     * A modified version of the minecraft useOnBlock method.
-     *
-     * @see net.minecraft.item.Item.useOnBlock
+     * A modified version of the minecraft [net.minecraft.item.Item.useOnBlock] method.
      */
     private fun AutomatedSafeContext.useOnBlock(
         placeContext: PlaceContext,
@@ -297,9 +294,7 @@ object PlaceManager : RequestHandler<PlaceRequest>(
     }
 
     /**
-     * A modified version of the minecraft place method.
-     *
-     * @see net.minecraft.item.BlockItem.place
+     * A modified version of the minecraft [net.minecraft.item.BlockItem.place] method.
      */
     private fun AutomatedSafeContext.place(
         placeContext: PlaceContext,
@@ -396,7 +391,7 @@ object PlaceManager : RequestHandler<PlaceRequest>(
         }
 
     /**
-     * Plays the block placement sound at a given position.
+     * Plays the block placement sound at a given [pos].
      */
     fun SafeContext.placeSound(state: BlockState, pos: BlockPos) {
         val blockSoundGroup = state.soundGroup

src/main/kotlin/com/lambda/interaction/request/placing/PlacedBlockHandler.kt

@@ -29,6 +29,9 @@ import com.lambda.util.Communication.info
 import com.lambda.util.Communication.warn
 import com.lambda.util.collections.LimitedDecayQueue
 
+/**
+ * Designed to handle placements pending a response from the server.
+ */
 object PlacedBlockHandler : PostActionHandler<PlaceInfo>() {
     override val pendingActions = LimitedDecayQueue<PlaceInfo>(
         AutomationConfig.buildConfig.maxPendingInteractions,

src/main/kotlin/com/lambda/interaction/request/rotating/RotationManager.kt

@@ -33,6 +33,10 @@ import com.lambda.interaction.BaritoneManager
 import com.lambda.interaction.request.Logger
 import com.lambda.interaction.request.RequestHandler
 import com.lambda.interaction.request.rotating.Rotation.Companion.slerp
+import com.lambda.interaction.request.rotating.RotationManager.activeRequest
+import com.lambda.interaction.request.rotating.RotationManager.activeRotation
+import com.lambda.interaction.request.rotating.RotationManager.serverRotation
+import com.lambda.interaction.request.rotating.RotationManager.updateActiveRotation
 import com.lambda.interaction.request.rotating.visibilty.lookAt
 import com.lambda.module.hud.ManagerDebugLoggers.rotationManagerLogger
 import com.lambda.threading.runGameScheduled
@@ -53,6 +57,9 @@ import kotlin.math.atan2
 import kotlin.math.cos
 import kotlin.math.sin
 
+/**
+ * Manager designed to rotate the player and adjust movement input to match the camera's direction.
+ */
 object RotationManager : RequestHandler<RotationRequest>(
     1,
     TickEvent.Pre,
@@ -62,8 +69,7 @@ object RotationManager : RequestHandler<RotationRequest>(
 ), Logger {
     var activeRotation = Rotation.ZERO
     var serverRotation = Rotation.ZERO
-    @JvmStatic
-    var prevServerRotation = Rotation.ZERO
+    @JvmStatic var prevServerRotation = Rotation.ZERO
     var baritoneRequest: RotationRequest? = null
 
     var activeRequest: RotationRequest? = null
@@ -138,6 +144,12 @@ object RotationManager : RequestHandler<RotationRequest>(
         return "Loaded Rotation Manager"
     }
 
+    /**
+     * If the [activeRequest] is from an older tick or null, and the [request]'s target rotation is not null,
+     * the request is accepted and set as the [activeRequest]. The [activeRotation] is then updated.
+     *
+     * @see updateActiveRotation
+     */
     override fun AutomatedSafeContext.handleRequest(request: RotationRequest) {
         activeRequest?.let { if (it.age <= 0) return }
         if (request.target.targetRotation.value != null) {
@@ -148,6 +160,11 @@ object RotationManager : RequestHandler<RotationRequest>(
         }
     }
 
+    /**
+     * If the rotation has not been changed this tick, the [activeRequest]'s target rotation is updated, and
+     * likewise the [activeRotation]. The [activeRequest] is then updated, ticking the [RotationRequest.keepTicks]
+     * and [RotationRequest.decayTicks].
+     */
     @JvmStatic
     fun processRotations() = runSafe {
         if (activeRequest != null) activeThisTick = true
@@ -171,6 +188,11 @@ object RotationManager : RequestHandler<RotationRequest>(
         }
     }
 
+    /**
+     * Calculates and sets the optimal movement input for moving in the direction the player is facing. This
+     * is not the direction the rotation manager is rotated towards, but the underlying player rotation, typically
+     * also the camera's rotation.
+     */
     @JvmStatic
     fun redirectStrafeInputs(input: Input) = runSafe {
         if (activeRequest == baritoneRequest) return@runSafe
@@ -263,11 +285,15 @@ object RotationManager : RequestHandler<RotationRequest>(
         }
     }
 
+    /**
+     * Updates the [activeRotation]. If [activeRequest] is null, the player's rotation is used.
+     * Otherwise, the [serverRotation] is interpolated towards the [RotationRequest.target] rotation.
+     */
     private fun SafeContext.updateActiveRotation() {
         activeRotation = activeRequest?.let { request ->
             val rotationTo = if (request.keepTicks >= 0)
                 request.target.targetRotation.value
-                    ?: activeRotation // same context gets used again && the rotation is null this tick
+                    ?: activeRotation // the same context gets used again && the rotation is null this tick
             else player.rotation
 
             val speedMultiplier = if (request.keepTicks < 0) 1.0 else request.speedMultiplier