other breaking-related documentation

Author: beanbag44

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

@@ -37,6 +37,9 @@ import net.minecraft.item.ItemStack
 import net.minecraft.network.packet.c2s.play.PlayerActionC2SPacket
 import net.minecraft.network.packet.c2s.play.PlayerActionC2SPacket.Action
 
+/**
+ * A data class that holds all the information required to process and continue a break.
+ */
 data class BreakInfo(
     override var context: BreakContext,
     var type: BreakType,
@@ -140,16 +143,13 @@ data class BreakInfo(
         }
 
     context(_: SafeContext)
-    fun startBreakPacket() =
-        breakPacket(Action.START_DESTROY_BLOCK)
+    fun startBreakPacket() = breakPacket(Action.START_DESTROY_BLOCK)
 
     context(_: SafeContext)
-    fun stopBreakPacket() =
-        breakPacket(Action.STOP_DESTROY_BLOCK)
+    fun stopBreakPacket() = breakPacket(Action.STOP_DESTROY_BLOCK)
 
     context(_: SafeContext)
-    fun abortBreakPacket() =
-        breakPacket(Action.ABORT_DESTROY_BLOCK)
+    fun abortBreakPacket() = breakPacket(Action.ABORT_DESTROY_BLOCK)
 
     context(safeContext: SafeContext)
     private fun breakPacket(action: Action) =

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

@@ -24,12 +24,24 @@ import com.lambda.interaction.construction.context.BuildContext
 import com.lambda.interaction.request.LogContext
 import com.lambda.interaction.request.LogContext.Companion.LogContextBuilder
 import com.lambda.interaction.request.Request
+import com.lambda.interaction.request.breaking.BreakRequest.Companion.breakRequest
 import com.lambda.threading.runSafe
 import com.lambda.util.BlockUtils.blockState
 import com.lambda.util.BlockUtils.isEmpty
 import net.minecraft.entity.ItemEntity
 import net.minecraft.util.math.BlockPos
 
+/**
+ * Contains the information necessary for initializing and continuing breaks within the [BreakManager].
+ *
+ * The callbacks can be used to keep track of the break progress.
+ *
+ * The class has a private constructor to force use of the cleaner [BreakRequestDsl] builder. This is
+ * accessed through the [breakRequest] method.
+ *
+ * @param contexts A collection of [BreakContext]'s gathered from the [com.lambda.interaction.construction.simulation.BuildSimulator].
+ * @param pendingInteractions A mutable, concurrent list to store the pending actions.
+ */
 data class BreakRequest private constructor(
     val contexts: Collection<BreakContext>,
     val pendingInteractions: MutableCollection<BuildContext>,

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

@@ -42,8 +42,8 @@ import net.minecraft.entity.ItemEntity
 import net.minecraft.util.math.ChunkSectionPos
 
 /**
- * This object is designed to handle blocks that have been broken client side, yet are awaiting
- * confirmation from the server, and / or an item drop.
+ * Designed to handle blocks that are deemed broken, yet are awaiting
+ * confirmation from the server, and/or an item drop.
  *
  * @see BreakManager
  */
@@ -105,7 +105,7 @@ object BrokenBlockHandler : PostActionHandler<BreakInfo>() {
 
                 if (pending.breakConfig.breakConfirmation == BreakConfirmationMode.AwaitThenBreak
                     || (pending.type == BreakInfo.BreakType.Rebreak && !pending.breakConfig.rebreak)
-                ) {
+                    ) {
                     destroyBlock(pending)
                 }
                 pending.internalOnBreak()
@@ -121,52 +121,44 @@ object BrokenBlockHandler : PostActionHandler<BreakInfo>() {
 
         listen<EntityEvent.Update>(priority = Int.MIN_VALUE) {
             if (it.entity !is ItemEntity) return@listen
-            run {
+            val pending =
                 pendingActions.firstOrNull { info -> matchesBlockItem(info, it.entity) }
                     ?: rebreak?.let { info ->
-                        return@run if (matchesBlockItem(info, it.entity)) info
-                        else null
-                    }
-            }?.let { pending ->
-                pending.internalOnItemDrop(it.entity)
-                if (pending.callbacksCompleted) {
-                    pending.stopPending()
-                    if (lastPosStarted == pending.context.blockPos) {
-                        RebreakHandler.offerRebreak(pending)
-                    }
+                        if (matchesBlockItem(info, it.entity)) info
+                        else return@listen
+                    } ?: return@listen
+
+            pending.internalOnItemDrop(it.entity)
+            if (pending.callbacksCompleted) {
+                pending.stopPending()
+                if (lastPosStarted == pending.context.blockPos) {
+                    RebreakHandler.offerRebreak(pending)
                 }
-                return@listen
             }
         }
     }
 
     /**
-     * A modified version of the minecraft breakBlock method.
+     * A modified version of the minecraft [net.minecraft.client.world.ClientWorld.breakBlock] method.
      *
-     * Performs the actions required to display break particles, sounds, texture overlay, etc.
-     * based on the users settings.
-     *
-     * @return if the blocks state was set or not.
-     *
-     * @see net.minecraft.client.world.ClientWorld.breakBlock
+     * Performs the actions required to display breaking particles, sounds, texture overlay, etc.
+     * based on the user's settings.
      */
-    fun SafeContext.destroyBlock(info: BreakInfo): Boolean {
+    fun SafeContext.destroyBlock(info: BreakInfo) {
         val ctx = info.context
 
-        if (player.isBlockBreakingRestricted(world, ctx.blockPos, gamemode)) return false
-        if (!player.mainHandStack.canMine(ctx.cachedState, world, ctx.blockPos, player)) return false
+        if (player.isBlockBreakingRestricted(world, ctx.blockPos, gamemode)) return
+        if (!player.mainHandStack.canMine(ctx.cachedState, world, ctx.blockPos, player)) return
 
         val block = ctx.cachedState.block
-        if (block is OperatorBlock && !player.isCreativeLevelTwoOp) return false
-        if (ctx.cachedState.isEmpty) return false
+        if (block is OperatorBlock && !player.isCreativeLevelTwoOp) return
+        if (ctx.cachedState.isEmpty) return
 
         block.onBreak(world, ctx.blockPos, ctx.cachedState, player)
         val fluidState = fluidState(ctx.blockPos)
         val setState = world.setBlockState(ctx.blockPos, fluidState.blockState, 11)
         if (setState) block.onBroken(world, ctx.blockPos, ctx.cachedState)
 
         if (info.breakConfig.breakingTexture) info.setBreakingTextureStage(player, world, -1)
-
-        return setState
     }
 }

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

@@ -25,10 +25,15 @@ import com.lambda.event.listener.UnsafeListener.Companion.listenUnsafe
 import com.lambda.interaction.construction.context.BreakContext
 import com.lambda.interaction.request.breaking.BreakManager.calcBreakDelta
 import com.lambda.interaction.request.breaking.BrokenBlockHandler.destroyBlock
+import com.lambda.interaction.request.breaking.RebreakHandler.rebreak
 import com.lambda.threading.runSafeAutomated
 import com.lambda.util.player.swingHand
 import net.minecraft.util.Hand
 
+/**
+ * Designed to track the latest primary-broken [BreakInfo] in order to exploit a flaw in Minecraft's code that allows
+ * the user to break any block placed in said position using the progress from the previously broken block.
+ */
 object RebreakHandler {
     var rebreak: BreakInfo? = null
 
@@ -47,6 +52,10 @@ object RebreakHandler {
         }
     }
 
+    /**
+     * Tests to see if the [BreakInfo] can be accepted. If not, nothing happens. Otherwise,
+     * the [rebreak] is set, and the [BreakRequest.onReBreakStart] callback is invoked.
+     */
     context(safeContext: SafeContext)
     fun offerRebreak(info: BreakInfo) {
         if (!info.rebreakable) return
@@ -63,6 +72,15 @@ object RebreakHandler {
         rebreak = null
     }
 
+    /**
+     * [RebreakPotential.None] if it cannot be rebroken at all.
+     *
+     * [RebreakPotential.PartialProgress] if some progress would be added to the break.
+     *
+     * [RebreakPotential.Instant] if the block can be instantly rebroken.
+     *
+     * @return In what way this block can be rebroken.
+     */
     context(_: SafeContext)
     fun BreakInfo.getRebreakPotential() = request.runSafeAutomated {
         rebreak?.let { reBreak ->
@@ -81,6 +99,11 @@ object RebreakHandler {
         } ?: RebreakPotential.None
     }
 
+    /**
+     * Updates the current [rebreak] with a fresh [BreakContext], and attempts to rebreak the block if possible.
+     *
+     * @return A [RebreakResult] to indicate how the update has been processed.
+     */
     context(_: SafeContext)
     fun handleUpdate(ctx: BreakContext, breakRequest: BreakRequest) = breakRequest.runSafeAutomated {
         val reBreak = this@RebreakHandler.rebreak ?: return@runSafeAutomated RebreakResult.Ignored

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

@@ -27,6 +27,9 @@ import com.lambda.interaction.request.breaking.BreakInfo.BreakType.Secondary
 import com.lambda.interaction.request.breaking.BreakManager.calcBreakDelta
 import com.lambda.threading.runSafeAutomated
 
+/**
+ * A simple data class to store info about when the [BreakManager] should swap tool.
+ */
 data class SwapInfo(
     private val type: BreakInfo.BreakType,
     private val automated: Automated,
@@ -43,13 +46,18 @@ data class SwapInfo(
     companion object {
         val EMPTY = SwapInfo(Primary, AutomationConfig)
 
+        /**
+         * Calculates the contents and returns a [SwapInfo].
+         *
+         *
+         */
         context(_: SafeContext)
         fun BreakInfo.getSwapInfo() = request.runSafeAutomated {
             val breakDelta = context.cachedState.calcBreakDelta(context.blockPos, swapStack)
 
             val threshold = getBreakThreshold()
 
-            // Plus one as this is calculated before this ticks progress is calculated and the breakingTicks are incremented
+            // Plus one as this is calculated before this ticks' progress is calculated and the breakingTicks are incremented
             val breakTicks = (if (rebreakPotential.isPossible()) RebreakHandler.rebreak?.breakingTicks
                 ?: throw IllegalStateException("Rebreak BreakInfo was null when rebreak was considered possible")
             else breakingTicks) + 1 - breakConfig.fudgeFactor