Class GameThread
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 Summary
Modifier and TypeMethodDescriptionstatic StringWhat the policy amounts to right now, e.g.static <T> TRunsfnon the client thread and returns the result.static <T> Tensure(Supplier)with an answer for when the read cannot be served.static net.runelite.api.ClientThe client given toinit(net.runelite.api.Client, net.runelite.client.callback.ClientThread), ornullbefore this copy was initialised.static ThreadThe identified game thread, or null when the server gives us none.static voidinit(net.runelite.api.Client client, net.runelite.client.callback.ClientThread clientThread) Connects this class to the client and its client thread.static voidRunsron the client thread (fire-and-forget).static booleanReturns true if the current thread is the client (game-tick) thread.static booleanTrue 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.static booleanisImpact()True when the active server is Impact, where the game thread is the AWT EDT.static voidpinPolicy(GameThreadPolicy pinned) Fixes how reads are routed, so a laterinit(net.runelite.api.Client, net.runelite.client.callback.ClientThread)orsetGameThread(java.lang.Thread)cannot change it.static GameThreadPolicypolicy()The pinned policy, orGameThreadPolicy.AUTO.static voidDeclares the thread the game loop runs on.
-
Method Details
-
pinPolicy
Fixes how reads are routed, so a laterinit(net.runelite.api.Client, net.runelite.client.callback.ClientThread)orsetGameThread(java.lang.Thread)cannot change it.nullrestoresGameThreadPolicy.AUTO. PrivBot sets this; a plugin leaves it alone. -
policy
The pinned policy, orGameThreadPolicy.AUTO. -
describePolicy
What the policy amounts to right now, e.g."AUTO -> EDT marshal". -
setGameThread
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
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 (thePrivContextconstructor 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
ensure(Supplier)with an answer for when the read cannot be served.ensurereturnsnullwhen it drops a read rather than guessing, which is a fine answer for an object but a trap for a primitive: assigning it to anintor abooleanunboxes 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
Runsfnon 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 theClientThreadqueue (bounded at 5 s). Returnsnullwhen the read is dropped rather than guessed: a timeout, an interrupt, or an exception thrown byfn(logged). Treatnullas "could not read", never as a negative answer; for primitives useensure(Supplier, Object). In a copy that was neverinitialisedit warns once per thread and runs inline.When
fnruns 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
Runsron the client thread (fire-and-forget). If the caller is already on the client thread, runs inline. When uninitialized, mirrorsensure(Supplier): warn and run inline rather than silently dropping the runnable — a dropped action dispatch is invisible to callers.A queued
rruns 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 toinit(net.runelite.api.Client, net.runelite.client.callback.ClientThread), ornullbefore this copy was initialised.
-