Interface ScriptContext

public interface ScriptContext
Context object passed to BotScript.onStart(ScriptContext) providing access to the game API and the event bus.
See Also:

  • Method Details

    • getGameAPI

      GameAPI getGameAPI()
      Returns the game API for interacting with the game client.
      Returns:
      the GameAPI instance

    • getEventBus

      EventBus getEventBus()
      Returns the event bus for subscribing to and publishing game events.
      Returns:
      the EventBus instance

    • getMessageBus

      MessageBus getMessageBus()
      Returns the message bus for inter-script communication.
      Returns:
      the MessageBus instance

    • getSharedState

      SharedState getSharedState()
      Returns the shared state store for inter-script data sharing.
      Returns:
      the SharedState instance

    • getNavigation

      Navigation getNavigation()
      Returns the navigation interface for blocking walk operations. Walk methods block the calling thread until arrival, cancellation, failure, or timeout, but do not block the pipe.
      Returns:
      the Navigation instance

    • getScriptContext

      default ScriptContextPublisher getScriptContext()
      Returns the debug publisher bound to this script. Calls into the returned publisher fan out to whoever is subscribed to the agent's script.context broker topic (primarily NXTDebugger).

      The default implementation returns ScriptContextPublisher.NOOP; runtimes that have wired a channel override this to return a per-script tagged publisher.

    • isStopRequested

      default boolean isStopRequested()
      Whether the user (or the host) has asked this script to stop.

      Poll this inside any loop or wait that could run for more than a moment, and return from onLoop when it goes true. The runtime also interrupts the script thread, but interruption is only observed between loops — a script that waits inside onLoop won't see it:

      @Override
public int onLoop() {
    while (!bank.isOpen()) {
        if (ctx.isStopRequested()) {
            return -1;          // clean exit
        }
        Thread.sleep(100);
    }
    ...
}

      Ignoring this is not fatal but is not free either: a script that won't exit is eventually revoked — every subsequent game call throws ScriptRevokedException — and then quarantined, which keeps its thread alive and its classloader pinned for the rest of the session.

      Defaults to false for contexts that aren't runtime-backed (test mocks), so a script polling it in a unit test simply never stops.

    • stopSelf

      default void stopSelf()
      Request that this script terminate. Idempotent. The runner will let the current BotScript.onLoop() iteration finish, then transition through BotScript.onStop() as usual — same lifecycle a -1 return from onLoop produces, but reachable from any depth in the script.

      This is the push side of isStopRequested(), and it takes the same path a user Stop does: afterwards isStopRequested() returns true and the script thread is interrupted, so a sleep or wait later in the same onLoop ends early with InterruptedException. Return from onLoop promptly after calling it.

      Use this for self-stop conditions detected in deep call sites (controllers, sub-tasks) where bubbling -1 back up to the top-level loop is awkward. It does not grant peer-stop capability — a BotScript still cannot terminate other scripts on the same Client. For cross-script control use ManagementContext from a ManagementScript.

      The default implementation is a no-op so unit tests instantiating their own ScriptContext don't have to wire the stop pathway. The real runtime overrides this.

    • getDisplayName

      default Optional<String> getDisplayName()
      The display name of the character on this script's client, once the host knows it.

      Same value as Client.getDisplayName() for the client this script runs on. When the client was launched for a known Jagex character, the name is available from the login screen on; otherwise it is empty until the client is in a world. In a world the logged-in character's name wins over the launched one, and it is refreshed after a later login. Cheap to call from onLoop: it never blocks on the client.

      The default returns empty, for contexts that are not bound to a live game client (test mocks).

      Returns:
      the character's display name, or empty while it is not known