Class GameThread

java.lang.Object
privbot.context.GameThread

public final class GameThread extends Object
Static utility for thread-safe game state access — mirrors the dispatch layer of other bot frameworks.

Hooks call ensure(Supplier) around any code that touches the Client. If the caller is already on the client thread the lambda runs inline; otherwise it is dispatched via ClientThread.invoke(java.lang.Runnable) and the calling (script) thread blocks until the result is ready.

Usage in hooks:


 public NPCQuery query() {
     return GameThread.ensure(() -> {
         List<PrivNPC> list = new ArrayList<>();
         for (NPC n : client.getNpcs()) { ... }
         return new NPCQuery(list, adapter);
     });
 }
 

Initialized once by PrivContext during plugin startup.

Which thread a call lands on is decided by GameThreadRouting from this copy's GameThreadPolicy and what it knows; this class gathers those facts and carries the decision out.

  • Method Details

    • pinPolicy

      public static void pinPolicy(GameThreadPolicy pinned)
      Fixes how reads are routed, so a later init(net.runelite.api.Client, net.runelite.client.callback.ClientThread) or setGameThread(java.lang.Thread) cannot change it. null restores GameThreadPolicy.AUTO. PrivBot sets this; a plugin leaves it alone.
    • policy

      public static GameThreadPolicy policy()
      The pinned policy, or GameThreadPolicy.AUTO.
    • describePolicy

      public static String describePolicy()
      What the policy amounts to right now, e.g. "AUTO -> EDT marshal".
    • setGameThread

      public static void setGameThread(Thread t)
      Declares the thread the game loop runs on. Idempotent; safe to call every frame.

      Once set, ensure(java.util.function.Supplier<T>, T) marshals onto it via the ClientThread queue — which the same pulse drains — instead of taking the EDT fallback.

    • getGameThread

      public static Thread getGameThread()
      The identified game thread, or null when the server gives us none.
    • init

      public static void init(net.runelite.api.Client client, net.runelite.client.callback.ClientThread clientThread)
      Connects this class to the client and its client thread. PrivBot calls it during startup (the PrivContext constructor does); a plugin never needs to. Idempotent.
    • isClientThread

      public static boolean isClientThread()
      Returns true if the current thread is the client (game-tick) thread.

      A pulse-identified game thread is authoritative: on Elorin the EDT check is WRONG (the game ticks on client.c), and answering true there sent reads straight into the client off-thread.

      Without one, on Impact the game ticks on the AWT EDT (AWT-EventQueue-1) and client.isClientThread() returns false there. Treat the EDT as the client thread so hooks read/dispatch inline rather than marshaling (which dead-ends on the no-pump CT-drain thread → 5s timeout), and so isClientThread()-guarded helpers (ObjectQuery.withName/closest, PrivObject.interact) do NOT recurse through ensure() now that ensure() also runs inline on the EDT.

      Note: thread dumps taken later (2026-10-08, 2026-10-24) show Impact's game loop on main, not the EDT. The EDT rule above describes what this method answers, not where Impact actually ticks.

    • ensure

      public static <T> T ensure(Supplier<T> fn, T fallback)
      ensure(Supplier) with an answer for when the read cannot be served.

      ensure returns null when it drops a read rather than guessing, which is a fine answer for an object but a trap for a primitive: assigning it to an int or a boolean unboxes it and throws a NullPointerException. That NPE does not surface as a crash - a workflow catches it, reports "condition error", and skips the stage, so a flow can park for an entire session on a read that timed out once.

      Use this wherever the result is a primitive, passing the same fallback the read itself would use when it cannot answer.

    • ensure

      public static <T> T ensure(Supplier<T> fn)
      Runs fn on the client thread and returns the result. If the caller is already on the client thread, runs inline.

      The route (GameThreadRouting.ensure(privbot.context.GameThreadPolicy, privbot.context.GameThreadRouting.Facts)) depends on the server and on what this copy was told: inline, the pulse-drained queue (bounded at 2 s), an EDT marshal, or the ClientThread queue (bounded at 5 s). Returns null when the read is dropped rather than guessed: a timeout, an interrupt, or an exception thrown by fn (logged). Treat null as "could not read", never as a negative answer; for primitives use ensure(Supplier, Object). In a copy that was never initialised it warns once per thread and runs inline.

      When fn runs on another thread, it still runs as the calling plugin's own work there, so what the client allows that plugin applies to it as it would inline. Nothing extra is waited on for this.

    • invokeLater

      public static void invokeLater(Runnable r)
      Runs r on the client thread (fire-and-forget). If the caller is already on the client thread, runs inline. When uninitialized, mirrors ensure(Supplier): warn and run inline rather than silently dropping the runnable — a dropped action dispatch is invisible to callers.

      A queued r runs as the calling plugin's own work, as it does inline.

    • isImpact

      public static boolean isImpact()
      True when the active server is Impact, where the game thread is the AWT EDT.
    • isEdtMarshalServer

      public static boolean isEdtMarshalServer()
      True when this server's client reads run on the AWT EDT (Impact, Elorin): ensure(java.util.function.Supplier<T>, T) marshals a read there from any other thread. False on RuneLite-API servers (Orion, Roat Pkz, ...), where the EDT is only the Swing thread, not the client thread.
    • getClient

      public static net.runelite.api.Client getClient()
      The client given to init(net.runelite.api.Client, net.runelite.client.callback.ClientThread), or null before this copy was initialised.