feat(world-hop): pace hops against an estimated per-IP hop allowance

docs/AGENT_SERVER.md

@@ -492,6 +492,8 @@ When the client is on the login screen, the response includes `loginIndex` and `
   "loggedIn": true,
   "gameState": "LOGGED_IN",
   "loginAttemptActive": false,
+  "hopsAvailable": 372,
+  "nextHopInMs": 0,
   "loginDurationMs": 120000,
   "activeProfile": {
     "name": "player@email.com",
@@ -514,6 +516,8 @@ When the client is on the login screen, the response includes `loginIndex` and `
 
 `loginIndex` and `loginError` are only present when `gameState` is `LOGIN_SCREEN`. When logged in, these fields are omitted.
 
+`hopsAvailable` and `nextHopInMs` come from the world hop limiter (`HopBudget`). They are present whenever "Pace world hops" is enabled in the Microbot settings. `nextHopInMs` is how long `Microbot.hopToWorld` would wait right now, and is 0 while the allowance is above the login reserve.
+
 #### POST /login
 
 Triggers a login using the active profile. **Blocks by default** until the login succeeds or fails, returning a definitive result.

docs/ARCHITECTURE.md

@@ -31,6 +31,7 @@
 - `BlockingEventManager` uses exponential backoff when no events validate to reduce overhead; events are re-queued if execution fails.
 - Default Gradle `test` tasks are disabled in `runelite-client/build.gradle.kts`; use explicit tasks such as `:client:runUnitTests`, `:client:runTests`, `:client:runDebugTests`, `:client:runIntegrationTest`, or `:client:runClientThreadScanner`.
 - World hopping short-circuits if the player is interacting or already hopping; confirmation widget auto-click handled in `Microbot.hopToWorld`.
+- `Microbot.hopToWorld` paces hops against `HopBudget`, an estimate of Jagex's per-IP hop/login allowance (default 390 tokens, 93 regained per hour, 20 kept in reserve for logins). Every `HOPPING` and `LOGGING_IN` transition spends a token, including manual hops. When the allowance is down to the reserve, script threads wait for the next token; the client thread and Swing thread get `false` instead. The state lives in `~/.runelite/microbot-hop-budget.properties`, keyed by SOCKS proxy host, so it survives restarts and is shared by every client on the same IP. A "Too many login attempts" lockout (login index 33) sets it to zero.
 
 ## References
 - Queryable API guide: `../runelite-client/src/main/java/net/runelite/client/plugins/microbot/api/QUERYABLE_API.md`

runelite-client/src/main/java/net/runelite/client/plugins/microbot/BlockingEventManager.java

@@ -59,6 +59,7 @@ public BlockingEventManager()
         blockingEvents.add(new BankJagexPopupEvent());
         blockingEvents.add(new PluginPauseEvent());
 		blockingEvents.add(new EnjoyRSChatboxEvent());
+		blockingEvents.add(new MembershipPromptEvent());
 		blockingEvents.add(new DisableWorldSwitcherConfirmationEvent());
 		blockingEvents.add(new HideRoofsEvent());
 

runelite-client/src/main/java/net/runelite/client/plugins/microbot/Microbot.java

@@ -55,6 +55,7 @@
 import net.runelite.client.plugins.microbot.api.playerstate.Rs2PlayerStateCache;
 import net.runelite.client.plugins.microbot.api.tileitem.Rs2TileItemCache;
 import net.runelite.client.plugins.microbot.api.tileobject.Rs2TileObjectCache;
+import net.runelite.client.plugins.microbot.util.security.HopBudget;
 import net.runelite.client.plugins.microbot.util.security.LoginManager;
 import net.runelite.client.plugins.microbot.util.widget.Rs2Widget;
 import net.runelite.client.ui.overlay.infobox.InfoBoxManager;
@@ -376,6 +377,9 @@ public static boolean hopToWorld(int worldNumber) {
             log.error("Can't hop world, already trying to hop");
             return false;
         }
+        if (Microbot.getClient().getWorld() != worldNumber && !awaitHopBudget(worldNumber)) {
+            return false;
+        }
         final net.runelite.api.World[] target = new net.runelite.api.World[1];
         boolean prepared = Microbot.getClientThread().runOnClientThreadOptional(() -> {
             if (Rs2Combat.inCombat()) {
@@ -464,6 +468,35 @@ public static boolean hopToWorld(int worldNumber) {
         return success;
     }
 
+    static boolean awaitHopBudget(int worldNumber) {
+        HopBudget budget = HopBudget.getInstance();
+        long waitMs = budget.millisUntilHopAllowed();
+        if (waitMs <= 0) {
+            return true;
+        }
+        if (Microbot.getClient().isClientThread() || SwingUtilities.isEventDispatchThread()) {
+            log.warn("Hop limit reached - not hopping to world {}, next hop allowed in {}s",
+                    worldNumber, TimeUnit.MILLISECONDS.toSeconds(waitMs));
+            return false;
+        }
+        log.info("Hop limit reached - waiting {}s before hopping to world {}",
+                TimeUnit.MILLISECONDS.toSeconds(waitMs), worldNumber);
+        String previousStatus = status;
+        try {
+            while (waitMs > 0) {
+                status = "Hop limit - next hop in " + TimeUnit.MILLISECONDS.toSeconds(waitMs + 999) + "s";
+                Thread.sleep(Math.min(waitMs, 1000L));
+                waitMs = budget.millisUntilHopAllowed();
+            }
+            return true;
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            return false;
+        } finally {
+            status = previousStatus;
+        }
+    }
+
     static boolean hopViaWorldSwitcher(net.runelite.api.World rsWorld, int loadTimeoutMs) {
         if (!isWorldSwitcherLoaded()
                 && !sleepUntil(Microbot::isWorldSwitcherLoaded, Microbot::openWorldSwitcher, loadTimeoutMs, WORLD_SWITCHER_REOPEN_INTERVAL_MS)) {

runelite-client/src/main/java/net/runelite/client/plugins/microbot/MicrobotConfig.java

@@ -7,6 +7,8 @@
 import net.runelite.client.config.ConfigGroup;
 import net.runelite.client.config.ConfigItem;
 import net.runelite.client.config.ConfigSection;
+import net.runelite.client.config.Range;
+import net.runelite.client.plugins.microbot.util.security.HopBudget;
 
 @ConfigGroup(MicrobotConfig.configGroup)
 public interface MicrobotConfig extends Config
@@ -272,4 +274,67 @@ default int inputIdleResumeMs()
 	{
 		return 1800;
 	}
+
+	@ConfigSection(
+		name = "World hop limit",
+		description = "Pace world hops so the per-IP login limit (\"Too many login attempts\") is never reached",
+		position = 4
+	)
+	String hopLimitSection = "hopLimitSection";
+
+	String keyEnableHopLimit = "enableHopLimit";
+	@ConfigItem(
+		keyName = keyEnableHopLimit,
+		name = "Pace world hops",
+		description = "Wait before a scripted world hop when the estimated hop allowance runs low, instead of getting locked out. " +
+				"Shared by every client on the same IP or proxy.",
+		position = 0,
+		section = hopLimitSection
+	)
+	default boolean enableHopLimit()
+	{
+		return true;
+	}
+
+	String keyHopLimitCapacity = "hopLimitCapacity";
+	@Range(min = 1, max = 1000)
+	@ConfigItem(
+		keyName = keyHopLimitCapacity,
+		name = "Hop allowance",
+		description = "Estimated number of hops and logins Jagex allows before locking the IP out",
+		position = 1,
+		section = hopLimitSection
+	)
+	default int hopLimitCapacity()
+	{
+		return HopBudget.DEFAULT_CAPACITY;
+	}
+
+	String keyHopLimitRefillPerHour = "hopLimitRefillPerHour";
+	@Range(min = 1, max = 1000)
+	@ConfigItem(
+		keyName = keyHopLimitRefillPerHour,
+		name = "Hops regained per hour",
+		description = "Estimated number of hops the allowance regains every hour",
+		position = 2,
+		section = hopLimitSection
+	)
+	default int hopLimitRefillPerHour()
+	{
+		return HopBudget.DEFAULT_REFILL_PER_HOUR;
+	}
+
+	String keyHopLimitReserve = "hopLimitReserve";
+	@Range(min = 0, max = 200)
+	@ConfigItem(
+		keyName = keyHopLimitReserve,
+		name = "Reserve for logins",
+		description = "Hops never spent on world hopping, kept for logging back in after breaks or disconnects",
+		position = 3,
+		section = hopLimitSection
+	)
+	default int hopLimitReserve()
+	{
+		return HopBudget.DEFAULT_RESERVE;
+	}
 }

runelite-client/src/main/java/net/runelite/client/plugins/microbot/MicrobotPlugin.java

@@ -6,6 +6,7 @@
 import net.runelite.api.*;
 import net.runelite.api.events.*;
 import net.runelite.api.gameval.InventoryID;
+import net.runelite.client.RuneLite;
 import net.runelite.client.RuneLiteProperties;
 import net.runelite.client.config.ConfigManager;
 import net.runelite.client.eventbus.EventBus;
@@ -40,6 +41,7 @@
 import net.runelite.client.plugins.microbot.util.shop.Rs2Shop;
 import net.runelite.client.plugins.microbot.util.tabs.Rs2Tab;
 import net.runelite.client.plugins.microbot.util.widget.Rs2Widget;
+import net.runelite.client.plugins.microbot.util.security.HopBudget;
 import net.runelite.client.plugins.microbot.util.security.LoginManager;
 import net.runelite.client.ui.ClientToolbar;
 import net.runelite.client.ui.NavigationButton;
@@ -58,6 +60,7 @@
 import java.awt.AWTException;
 import java.awt.Rectangle;
 import java.awt.image.BufferedImage;
+import java.io.File;
 import java.lang.reflect.Field;
 import java.lang.reflect.InvocationTargetException;
 import java.util.ArrayList;
@@ -66,6 +69,7 @@
 import java.util.List;
 import java.util.Objects;
 import java.util.Optional;
+import java.util.concurrent.ScheduledExecutorService;
 @PluginDescriptor(
 	name = PluginDescriptor.Default + "Microbot",
 	description = "Microbot",
@@ -101,6 +105,9 @@ public class MicrobotPlugin extends Plugin
 	@Inject
 	private MicrobotConfig microbotConfig;
 
+	@Inject
+	private ScheduledExecutorService executor;
+
 	private MicrobotTopLevelConfigPanel topLevelConfigPanel;
 
 	private NavigationButton navButton;
@@ -177,6 +184,8 @@ protected void startUp() throws AWTException
 		InputArbiter.setDisabled(microbotConfig.disableInputYielding());
 		InputArbiter.setMotionThresholdPx(microbotConfig.inputMotionThresholdPx());
 		InputArbiter.setIdleResumeMs(microbotConfig.inputIdleResumeMs());
+		HopBudget.getInstance().persistTo(new File(RuneLite.RUNELITE_DIR, HopBudget.FILE_NAME).toPath(), HopBudget.networkKey());
+		applyHopBudgetConfig();
 		CanvasInputListener.attach();
 		Microbot.enableAutoRunOn = microbotConfig.enableAutoRunOn();
 		Microbot.useStaminaPotsIfNeeded = microbotConfig.useStaminaPotsIfNeeded();
@@ -323,7 +332,10 @@ private int[] getShopContainerIds()
 	@Subscribe
 	public void onGameStateChanged(GameStateChanged gameStateChanged)
 	{
-
+	   if (isLoginServerRequest(LoginManager.getLastKnownGameState(), gameStateChanged.getGameState()))
+	   {
+		   executor.execute(() -> HopBudget.getInstance().recordHop());
+	   }
 	   if (gameStateChanged.getGameState() == GameState.LOGGED_IN)
 	   {
 		   // Region-based login detection logic
@@ -359,6 +371,26 @@ public void onGameStateChanged(GameStateChanged gameStateChanged)
 	   LoginManager.setLastKnownGameState(gameStateChanged.getGameState());
 	}
 
+	static boolean isLoginServerRequest(GameState previous, GameState next)
+	{
+		if (next == GameState.HOPPING)
+		{
+			return previous != GameState.HOPPING;
+		}
+		return next == GameState.LOGGING_IN
+				&& previous != GameState.HOPPING
+				&& previous != GameState.LOGGING_IN;
+	}
+
+	private void applyHopBudgetConfig()
+	{
+		HopBudget.getInstance().configure(
+				microbotConfig.enableHopLimit(),
+				microbotConfig.hopLimitCapacity(),
+				microbotConfig.hopLimitRefillPerHour(),
+				microbotConfig.hopLimitReserve());
+	}
+
 	private static EnumSet<WorldType> normalizeWorldTypesForProfileComparison(EnumSet<WorldType> rawTypes)
 	{
 		EnumSet<WorldType> normalized = rawTypes == null
@@ -518,6 +550,12 @@ public void onConfigChanged(ConfigChanged ev)
 				case MicrobotConfig.keyInputIdleResumeMs:
 					InputArbiter.setIdleResumeMs(microbotConfig.inputIdleResumeMs());
 					break;
+				case MicrobotConfig.keyEnableHopLimit:
+				case MicrobotConfig.keyHopLimitCapacity:
+				case MicrobotConfig.keyHopLimitRefillPerHour:
+				case MicrobotConfig.keyHopLimitReserve:
+					applyHopBudgetConfig();
+					break;
 				case MicrobotConfig.keyEnableGameChatLogging:
 				case MicrobotConfig.keyGameChatLogPattern:
 				case MicrobotConfig.keyGameChatLogLevel:

runelite-client/src/main/java/net/runelite/client/plugins/microbot/agentserver/handler/LoginHandler.java

@@ -7,6 +7,7 @@
 import net.runelite.api.GameState;
 import net.runelite.client.config.ConfigProfile;
 import net.runelite.client.plugins.microbot.Microbot;
+import net.runelite.client.plugins.microbot.util.security.HopBudget;
 import net.runelite.client.plugins.microbot.util.security.LoginLockout;
 import net.runelite.client.plugins.microbot.util.security.LoginManager;
 
@@ -79,6 +80,11 @@ private Map<String, Object> buildStatusMap() {
 		if (loginCooldownMs > 0) {
 			result.put("loginCooldownMs", loginCooldownMs);
 		}
+		HopBudget hopBudget = HopBudget.getInstance();
+		if (hopBudget.isEnabled()) {
+			result.put("hopsAvailable", hopBudget.available());
+			result.put("nextHopInMs", hopBudget.millisUntilHopAllowed());
+		}
 
 		if (Microbot.isLoggedIn()) {
 			long durationMs = LoginManager.getLoginDuration().toMillis();

runelite-client/src/main/java/net/runelite/client/plugins/microbot/util/events/MembershipPromptEvent.java

@@ -0,0 +1,56 @@
+package net.runelite.client.plugins.microbot.util.events;
+
+import net.runelite.api.Client;
+import net.runelite.api.gameval.InterfaceID;
+import net.runelite.api.widgets.Widget;
+import net.runelite.client.plugins.microbot.BlockingEvent;
+import net.runelite.client.plugins.microbot.BlockingEventPriority;
+import net.runelite.client.plugins.microbot.Microbot;
+import net.runelite.client.plugins.microbot.util.Global;
+import net.runelite.client.plugins.microbot.util.widget.Rs2Widget;
+
+public class MembershipPromptEvent implements BlockingEvent {
+
+    static final int[][] PROMPTS = {
+            {InterfaceID.F2PBondRedeem.UNIVERSE, InterfaceID.F2PBondRedeem.CLOSE},
+            {InterfaceID.BondPrompt.UNIVERSE, InterfaceID.BondPrompt.CLOSE},
+            {InterfaceID.MembershipBenefitsPromptHop.UNIVERSE, InterfaceID.MembershipBenefitsPromptHop.CLOSE_BUTTON},
+    };
+
+    @Override
+    public boolean validate() {
+        return findCloseButton() != null;
+    }
+
+    @Override
+    public boolean execute() {
+        Widget closeButton = findCloseButton();
+        if (closeButton == null) return true;
+
+        Rs2Widget.clickWidget(closeButton);
+        return Global.sleepUntil(() -> findCloseButton() == null, 10000);
+    }
+
+    @Override
+    public BlockingEventPriority priority() {
+        return BlockingEventPriority.NORMAL;
+    }
+
+    private static Widget findCloseButton() {
+        if (!Microbot.isLoggedIn()) return null;
+        return Microbot.getClientThread()
+                .runOnClientThreadOptional(() -> findCloseButton(Microbot.getClient()))
+                .orElse(null);
+    }
+
+    static Widget findCloseButton(Client client) {
+        if (client == null) return null;
+        for (int[] prompt : PROMPTS) {
+            Widget root = client.getWidget(prompt[0]);
+            if (root == null || root.isHidden()) continue;
+            Widget close = client.getWidget(prompt[1]);
+            if (close != null && !close.isHidden()) return close;
+        }
+        return null;
+    }
+}