even betterer documentation

src/main/kotlin/RSLogic.kt

@@ -3,37 +3,27 @@ import java.awt.event.InputEvent
 import java.awt.event.KeyEvent
 
 /**
- * Interface for coordinating RuneScape automation routines.
- *
- * This interface provides methods for common in-game workflows like:
- *
- * - Processing actions at the bank chest
- * - Traveling between bank and crafting station
- * - Bank standing without dialogue boxes
- *
- * Implementations would integrate with a desktop automation library
- * to actually perform the in-game clicks and inputs.
- *
- * This interface allows the game-specific logic to be separated from
- * the underlying automation library.
+ * Interface for coordinating RuneScape bot actions.
  *
+ * This interface defines methods for orchestrating RuneScape gameplay like banking,
+ * traveling, and crafting. It provides the core logic needed for automating
+ * RuneScape tasks.
  */
 interface RSCoordinator {
 
     /**
-     * Perform actions at the bank chest.
+     * Handles the crafting process when standing at the bank.
      *
-     * This typically involves:
-     * 1. Clicking the chest to open bank interface
-     * 2. Pressing preset hotkey to withdraw items
-     * 3. Pressing crafting hotkey to start crafting workflow
-     * 4. Waiting for crafting duration
+     * This method takes care of the workflow when standing at the bank:
+     * - Opens the bank interface using the bank preset hotkey.
+     * - Waits for the crafting duration.
+     * - Closes the bank interface.
      *
-     * @param bankPoint Point location of bank chest to click
-     * @param bankPresetHotkey Key code for bank preset withdraw action
-     * @param craftingDialogueHotkey Key code to select crafting dialogue
-     * @param waitDurationMillis Duration in ms to wait during crafting
-     * @param waitDurationVariance Allowed variance in wait duration
+     * @param bankPoint The [Point] location of the bank on screen.
+     * @param bankPresetHotkey The hotkey used to open the bank interface.
+     * @param craftingDialogueHotkey The hotkey used to open the crafting dialogue.
+     * @param waitDurationMillis The base duration in milliseconds to wait while crafting.
+     * @param waitDurationVarianceMillis Random variance in milliseconds to add to the wait duration.
      */
     fun processAtBank(
         bankPoint: Point,
@@ -44,22 +34,20 @@ interface RSCoordinator {
     )
 
     /**
-     * Perform actions between bank and nearby station.
+     * Handles the crafting process when at a station near the bank.
      *
-     * This involves:
-     * 1. Traveling from bankPoint to stationPoint
-     * 2. Clicking station to open interface
-     * 3. Pressing dialogue key to start crafting
-     * 4. Waiting for crafting duration
-     * 5. Waiting for crafting duration
+     * This method takes care of the workflow when at the crafting station:
+     * - Travels from the bank to the station.
+     * - Waits for the crafting duration.
+     * - Travels back to the bank when done.
      *
-     * @param bankPoint Point location of bank
-     * @param craftingStationPoint Point location of crafting station
-     * @param bankPresetHotkey Key code to withdraw items
-     * @param travelDurationMillis Time in ms to travel between points
-     * @param travelDurationVariance Allowed variance in travel time
-     * @param waitDurationMillis Crafting duration
-     * @param waitDurationVariance Variance in crafting duration
+     * @param bankPoint The [Point] location of the bank.
+     * @param craftingStationPoint The [Point] location of the crafting station.
+     * @param bankPresetHotkey The hotkey to open the bank interface.
+     * @param travelDurationMillis The base travel time between bank and station.
+     * @param travelDurationVarianceMillis Random variance to add to the travel time.
+     * @param waitDurationMillis The base duration to wait while crafting.
+     * @param waitDurationVarianceMillis Random variance to add to the wait duration.
      */
     fun processAtStationNearBank(
         bankPoint: Point,
@@ -71,28 +59,31 @@ interface RSCoordinator {
         waitDurationVarianceMillis: Long
     )
 
+    /**
+     * Gets the bank location point.
+     *
+     * @return The [Point] representing the x,y screen coordinates of the bank location.
+     */
     fun getBankPoint(): Point
 }
 
-/**
- * Interface for orchestrating and coordinating RuneScape automation routines.
- *
- * This interface combines the orchestration capabilities from [Orchestrator]
- * and the RuneScape coordination capabilities from [RSCoordinator].
- *
- * An implementation would use the orchestration methods like [doLoop] to
- * define the overall workflow.
- *
- * It would use the RSCoordinator methods like [processAtBank] to
- * encapsulate common in-game actions needed for that workflow.
- *
- * By combining both capabilities, this interface provides a simple
- * way to implement full RuneScape automation routines.
- *
- */
+
 interface RSOrchestrator : Orchestrator, RSCoordinator{
 
     companion object {
+
+        /**
+         * Performs a standing crafting task loop at the bank.
+         *
+         * This handles a simple crafting loop where the player stands at the bank and crafts.
+         *
+         * It withdraws items from the bank, crafts a batch of items, deposits crafted items,
+         * and repeats.
+         *
+         * @param orchestrator The [RSOrchestrator] that will execute the actions.
+         * @param params The [StandingTaskParams] configuring the task details.
+         * @return Unit.
+         */
         fun doStandingTask(orchestrator: RSOrchestrator, params: StandingTaskParams) {
             orchestrator.doLoop(params.totalVolume, params.volumePerStep) {
                 orchestrator.processAtBank(
@@ -105,6 +96,21 @@ interface RSOrchestrator : Orchestrator, RSCoordinator{
             }
         }
 
+        /**
+         * Performs a crafting workflow loop that involves traveling between a bank and crafting station.
+         *
+         * This handles the overall workflow orchestration of:
+         * 1. Withdrawing items from the bank.
+         * 2. Traveling to the crafting station.
+         * 3. Crafting items.
+         * 4. Traveling back to the bank when inventory is empty.
+         *
+         * It will repeat this loop for the specified total volume of items to craft, doing the given volume per loop iteration.
+         *
+         * @param orchestrator The [RSOrchestrator] instance that will execute the actual actions.
+         * @param params The [TravelTaskParams] configuring the crafting loop details.
+         * @return Unit.
+         */
         fun doTravelTask(orchestrator: RSOrchestrator, params: TravelTaskParams) {
             orchestrator.doLoop(params.totalVolume, params.volumePerStep) {
                 orchestrator.processAtStationNearBank(
@@ -119,13 +125,21 @@ interface RSOrchestrator : Orchestrator, RSCoordinator{
             }
         }
 
-        fun getDefaultInstance(): RSOrchestrator{
+        fun getInstance(): RSOrchestrator{
             return RSAgent()
         }
     } //end of companion object
 
 }
 
+/**
+ * Implementation of [RSOrchestrator] using a [RobotController].
+ *
+ * This class handles executing RuneScape automation tasks by controlling
+ * the game client via image recognition and input emulation.
+ *
+ * @param automaton The [Automaton] instance used to control the game. Defaults to [RobotController].
+ */
 private class RSAgent(override val automaton: Automaton = RobotController()) : RSOrchestrator {
 
     companion object{
@@ -159,6 +173,28 @@ private class RSAgent(override val automaton: Automaton = RobotController()) : R
     /*==============================================================================================================
                                                       interface implementation
      ==============================================================================================================*/
+    /**
+     * Performs actions at the bank chest.
+     *
+     * This method handles the workflow of:
+     *
+     * 1. Opening the bank interface by left-clicking near the provided bankPoint.
+     * 2. Withdrawing the desired inventory preset using the bankPresetHotkey.
+     * 3. Opening the crafting interface using the craftingDialogueHotkey.
+     * 4. Starting the crafting workflow by pressing the default "Accept" hotkey (space).
+     * 5. Waiting for the crafting duration with some random variance.
+     *
+     * Between steps, sleeps are added to match in-game server tick rate.
+     *
+     * The bank interface is opened by left-clicking near the bank point, using
+     * wiggle to introduce some variance.
+     *
+     * @param bankPoint The Point location of the bank chest.
+     * @param bankPresetHotkey The key code for the bank preset withdraw action.
+     * @param craftingDialogueHotkey The key code to open the crafting dialogue.
+     * @param waitDurationMillis The duration in ms to wait during crafting.
+     * @param waitDurationVariance Allowed variance in the wait duration.
+     */
     override fun processAtBank(
         bankPoint: Point,
         bankPresetHotkey: Int,
@@ -182,6 +218,35 @@ private class RSAgent(override val automaton: Automaton = RobotController()) : R
         automaton.sleepWithVariance(waitDurationMillis, waitDurationVariance)
     }
 
+    /**
+     * Performs actions at a station near the bank.
+     *
+     * This handles the workflow of:
+     *
+     * 1. Moving to the bank and opening the interface
+     * 2. Withdrawing the desired inventory loadout
+     * 3. Moving to the station and opening the crafting interface
+     * 4. Starting the crafting task
+     * 5. Waiting for the crafting duration
+     *
+     * Random variance is added to the travel and wait durations.
+     *
+     * The bank interface is opened by left clicking the bank point.
+     *
+     * The preset hotkey withdraws the loadout.
+     *
+     * The station interface is opened by left clicking the station point.
+     *
+     * The crafting task is started by pressing the spacebar.
+     *
+     * @param bankPoint The Point location of the bank
+     * @param craftingStationPoint The Point location of the crafting station
+     * @param bankPresetHotkey The hotkey to withdraw bank preset loadout
+     * @param travelDurationMillis The base travel time between bank and station
+     * @param travelDurationVarianceMillis The allowed variance in travel time
+     * @param waitDurationMillis The base crafting duration
+     * @param waitDurationVarianceMillis The allowed variance in crafting duration
+     */
     override fun processAtStationNearBank(
         bankPoint: Point,
         craftingStationPoint: Point,
@@ -212,12 +277,19 @@ private class RSAgent(override val automaton: Automaton = RobotController()) : R
         automaton.sleepWithVariance(waitDurationMillis, waitDurationVarianceMillis)
     }
 
-
-
-
-    /*==============================================================================================================
-                                                      cheater functions
-     ==============================================================================================================*/
+    /**
+     * Prompts the user to position the mouse and returns that position.
+     *
+     * This method prints a prompt message, then waits for the user to position
+     * the mouse.
+     *
+     * It then returns the current mouse position as a Point after a slight delay.
+     *
+     * The delay allows the mouse to settle before sampling its position.
+     *
+     * @param prompt The message to display to prompt user to position mouse.
+     * @return The Point position of the mouse after user positions it.
+     */
     override fun promptUserForPoint(prompt: String): Point {
         println(prompt)
         countDown(5) {
@@ -230,11 +302,43 @@ private class RSAgent(override val automaton: Automaton = RobotController()) : R
         return automaton.getPointerLocation()
     }
 
+
+    /*==============================================================================================================
+                                                      cheater functions
+     ==============================================================================================================*/
+
+
+    /**
+     * Prompts the user to position the mouse and returns that position.
+     *
+     * This method prints a prompt message, then waits for the user to position
+     * the mouse.
+     *
+     * It then returns the current mouse position as a Point after a slight delay.
+     *
+     * The delay allows the mouse to settle before sampling its position.
+     *
+     * @return The Point position of the mouse after user positions it.
+     */
     override fun getBankPoint(): Point {
         return promptUserForPoint("Hold your mouse over the bank...")
     }
 
+    /**
+     * Performs a countdown loop announcing each step.
+     *
+     * This method counts down from a provided number of seconds to 0.
+     *
+     * It calls the provided [announceFn] function on each step, passing the current
+     * step number.
 
+     * A sleep of 1 second is added between each step.
+
+     * Typical usage is to print a countdown message within [announceFn].
+
+     * @param nSeconds The number of seconds to count down.
+     * @param announceFn A callback function called each step, passed step number.
+     */
     fun countDown(nSeconds: Int, announceFn: (step: Int) -> Unit) {
         for (i in nSeconds downTo 0) {
             announceFn(i)
@@ -242,6 +346,21 @@ private class RSAgent(override val automaton: Automaton = RobotController()) : R
         }
     }
 
+    /**
+     * Gets the mouse pointer location after a delay.
+     *
+     * This method uses a countdown loop to wait for the specified number of
+     * seconds, printing a countdown as it goes.
+     *
+     * After the delay, it calls the automation library's getPointerLocation()
+     * method to retrieve the current mouse pointer coordinates.
+     *
+     * The delay helps ensure any prior mouse movements have settled before
+     * sampling the location.
+     *
+     * @param delayInSeconds The number of seconds to wait before sampling pointer location.
+     * @return The mouse pointer location after the delay as a Point.
+     */
     fun getPointerLocationAfter(delayInSeconds: Int): Point {
         countDown(delayInSeconds) {
             print("\rtaking pointer snapshot in $it...")
@@ -252,12 +371,45 @@ private class RSAgent(override val automaton: Automaton = RobotController()) : R
         return automaton.getPointerLocation()
     }
 
+    /**
+     * Gets the current mouse pointer location and returns it as a val declaration string.
+     *
+     * This method uses the [getPointerLocationAfter] method to get the current
+     * mouse pointer location after a small delay.
+     *
+     * It then formats this location into a string declaring a val with the provided
+     * variable name, like:
+     *
+     * ```
+     * val myPoint = Point(123, 456)
+     * ```
+     *
+     * The delay before getting the pointer location helps ensure the mouse has
+     * settled after any prior movements.
+     *
+     * @param varName The name to use for the variable in the declaration string.
+     * @return A string declaring a val with the pointer location.
+     */
     fun getPointerLocationAsValDeclarationString(varName: String): String {
         val info = getPointerLocationAfter(5)
         return "val $varName = Point(${info.x}, ${info.y})"
     }
 
-
+    /**
+     * Moves the mouse to a point, left clicks, and sleeps.
+     *
+     * This method moves the mouse to the provided point location, left clicks
+     * at that location, sleeps for the specified duration plus a random variance.
+     *
+     * Typical usage is to provide a point where something needs to be clicked,
+     * along with a sleep duration to wait after clicking.
+     *
+     * The random variance in sleep time helps match real human actions.
+     *
+     * @param p The point location to move the mouse and left click.
+     * @param dur The base duration in ms to sleep after clicking.
+     * @param durRange The allowed variance in the sleep duration.
+     */
     fun moveMouseLeftClickAndSleep(p: Point, dur: Long, durRange: Long) {
         automaton.moveMouse(p)
         automaton.sleepWithVariance(100, 50)
@@ -266,13 +418,34 @@ private class RSAgent(override val automaton: Automaton = RobotController()) : R
         automaton.sleepWithVariance(dur, durRange)
     }
 
+    /**
+     * Sleeps for a specified number of game ticks.
+     *
+     * This method calculates the total sleep duration based on the number of ticks
+     * and the tick duration constant. It then sleeps for that amount plus a small
+     * latency padding.
+     *
+     * A random variance is also added to the sleep duration to add some less-robotic behavior.
+     *
+     * @param n The number of game ticks to sleep for.
+     */
     fun sleepForNTicks(n: Long) {
         val latencyPadding = LATENCY_PADDING_MS
         val baseWaitTime = n * TICK_DURATION_MS
         automaton.sleepWithVariance(latencyPadding + baseWaitTime, 150)
     }
 
-
+    /**
+     * Draws a star shape by moving the mouse between points.
+     *
+     * This method takes in a center point and calculates offset points around it.
+     * It then moves the mouse between each point in sequence to draw a star shape.
+     *
+     * The offset points are calculated by moving left/right and up/down from the
+     * center point by a fixed offset amount.
+     *
+     * @param p The center point of the star.
+     */
     override fun drawStar(p: Point) {
         val offset = 100
         val top = Point(p.x, p.y - offset * 2)

src/main/kotlin/Routines.kt

@@ -50,7 +50,7 @@ object Routines {
         val start = System.currentTimeMillis()
 
         //initialize the shared agent and chest point
-        val agent = RSOrchestrator.getDefaultInstance()
+        val agent = RSOrchestrator.getInstance()
         val bankPoint = agent.getBankPoint()
 
         // Loop to clean grimy herbs:
@@ -100,7 +100,7 @@ object Routines {
      *
      * It performs the actions at the bank location using the provided agent.
      */
-    fun cleanHerbs(volume: Int, agent: RSOrchestrator = RSOrchestrator.getDefaultInstance(), bankPoint: Point = agent.getBankPoint()) {
+    fun cleanHerbs(volume: Int, agent: RSOrchestrator = RSOrchestrator.getInstance(), bankPoint: Point = agent.getBankPoint()) {
         val params = StandingTaskParams(
             volume,
             CommonVolumesPerStep.FullInventory,
@@ -126,7 +126,7 @@ object Routines {
      * - Cutting magic logs into incense sticks without dialog
      * - Depositing incense sticks
      */
-    fun cutIncenseSticks(volume: Int, agent: RSOrchestrator = RSOrchestrator.getDefaultInstance(), bankPoint: Point = agent.getBankPoint()) {
+    fun cutIncenseSticks(volume: Int, agent: RSOrchestrator = RSOrchestrator.getInstance(), bankPoint: Point = agent.getBankPoint()) {
         val params = StandingTaskParams(
             volume,
             CommonVolumesPerStep.FullInventory,
@@ -152,7 +152,7 @@ object Routines {
      * - Coating incense sticks with ashes using hotkey
      * - Depositing coated sticks
      */
-    fun coatIncenseSticks(volume: Int, agent: RSOrchestrator = RSOrchestrator.getDefaultInstance(), bankPoint: Point = agent.getBankPoint()) {
+    fun coatIncenseSticks(volume: Int, agent: RSOrchestrator = RSOrchestrator.getInstance(), bankPoint: Point = agent.getBankPoint()) {
         val params = StandingTaskParams(
             volume,
             CommonVolumesPerStep.CoatingIncenseWithAsh,
@@ -177,7 +177,7 @@ object Routines {
      * - Infusing incense sticks with herbs using hotkey
      * - Depositing infused incense sticks
      */
-    fun infuseIncenseSticks(volume: Int, agent: RSOrchestrator = RSOrchestrator.getDefaultInstance(), bankPoint: Point = agent.getBankPoint()) {
+    fun infuseIncenseSticks(volume: Int, agent: RSOrchestrator = RSOrchestrator.getInstance(), bankPoint: Point = agent.getBankPoint()) {
         val params = StandingTaskParams(
             volume,
             CommonVolumesPerStep.InfusingIncenseWithHerb,
@@ -190,8 +190,25 @@ object Routines {
         RSOrchestrator.doStandingTask(agent, params)
     }
 
+    /**
+     * Crafts potions at a bank location using hotkeys.
+     *
+     * @param volume The total number of potions to craft.
+     * @param agent The RSOrchestrator instance to use. Defaults to default instance.
+     * @param bankPoint The location of the bank. Defaults to agent's configured bank point.
+     *
+     * This method handles the workflow of crafting potions using hotkeys while standing at a bank:
+     *
+     * - It constructs a StandingTaskParams instance defining:
+     *   - The volume, volume per trip, bank point, crafting hotkey, and other details
+     * - It calls the orchestrator's doStandingTask() method to execute the task.
+     *
+     * Progress is automatically printed during execution.
+     *
+     * @deprecated This method needs validation before use in production.
+     */
     @Deprecated("Needs validation before you use it for realsies")
-    fun craftPotionAtBank(volume: Int, agent: RSOrchestrator = RSOrchestrator.getDefaultInstance(), bankPoint: Point = agent.getBankPoint()) {
+    fun craftPotionAtBank(volume: Int, agent: RSOrchestrator = RSOrchestrator.getInstance(), bankPoint: Point = agent.getBankPoint()) {
         val params = StandingTaskParams(
             volume,
             CommonVolumesPerStep.FullInventory,
@@ -204,11 +221,32 @@ object Routines {
         RSOrchestrator.doStandingTask(agent, params)
     }
 
+    /**
+     * Grinds potions using a well location for water.
+     *
+     * @param volume The total number of potions to make.
+     * @param travelDurationInMillis The time in ms for the agent to travel between the bank and the well.
+     * @param agent The RSOrchestrator instance to use. Defaults to the default instance.
+     * @param bankPoint The Point location of the bank. Defaults to the agent's configured bank point.
+     *
+     * This method handles the workflow of grinding potions using a well as the water source.
+     *
+     * It prompts the user to position the mouse over the well location to get its coordinates.
+     *
+     * It then constructs a TravelTaskParams instance to define:
+     * - The volume, volume per trip, bank point, well point, and other task details.
+     *
+     * It calls the orchestrator's doTravelTask() method to execute the grinding task.
+     *
+     * Progress is automatically printed during execution.
+     *
+     * @deprecated This method needs validation before use in production.
+     */
     @Deprecated("Needs validation before you use it for realsies")
     fun potionGrindWithWell(
         volume: Int,
         travelDurationInMillis: Long,
-        agent: RSOrchestrator = RSOrchestrator.getDefaultInstance(),
+        agent: RSOrchestrator = RSOrchestrator.getInstance(),
         bankPoint: Point = agent.getBankPoint()
     ) {
         val well = agent.promptUserForPoint("Put your mouse over the well...")
@@ -227,10 +265,30 @@ object Routines {
         RSOrchestrator.doTravelTask(agent, params)
     }
 
-
+    /**
+     * Handles the workflow to grind supreme overloads near a bank.
+     *
+     * @param params The parameters defining the grind details.
+     *
+     * This method handles the full process of:
+     *
+     * 1. Withdrawing overload supplies from the bank.
+     * 2. Going to the well location to make overloads.
+     * 3. Using the F6 hotkey to make overloads.
+     * 4. Sleeping between cycles to pace the actions.
+     * 5. Repeating for the total volume in steps of size volumePerStep.
+     *
+     * The well location is prompted from the user by moving the mouse over it.
+     *
+     * The agent handles the banking and inventory management.
+     *
+     * @param params TaskParams defining totalVolume, volumePerStep, and other details.
+     *
+     * @deprecated This method needs validation before use in production.
+     */
     @Deprecated("Needs validation before you use it for realsies")
     fun supremeOverloadGrind(params: TaskParams) {
-        val agent = RSOrchestrator.getDefaultInstance()
+        val agent = RSOrchestrator.getInstance()
         val chest = agent.getBankPoint()
         val well = agent.promptUserForPoint("Put your mouse over the well...")
 
@@ -265,7 +323,7 @@ object Routines {
         //these two points are specific to my computer. we need to export these into a file or something
         val furnaceFromChest = Point(776, 321)
         val chestFromFurnance = Point(1713, 843)
-        val agent = RSOrchestrator.getDefaultInstance()
+        val agent = RSOrchestrator.getInstance()
         val params = TravelTaskParams(
             volume,
             28,
@@ -303,7 +361,7 @@ object Routines {
     @Deprecated("Needs validation before you use it for realsies")
     fun processRefinedPlanksIntoFrames(params: TaskParams) {
         println("You must zoom in all the way and have the compass pointing straight N with a completely top-down view\n you must also be standing at the touch point on the saw")
-        val agent = RSOrchestrator.getDefaultInstance()
+        val agent = RSOrchestrator.getInstance()
         agent.scrollOutToHeight(8)
 
         //the following 2 points are magic numbers from *my* setup and resolution