Class TaskNodeRunner<C>

java.lang.Object
privbot.task.TaskNodeRunner<C>
Type Parameters:
C - the context type shared across all nodes

public class TaskNodeRunner<C> extends Object
Manages a flat list of TaskNodes and executes the highest-priority valid node each tick. Higher TaskNode.getPriority() wins; equal priorities keep registration order.

Ordinary plugins construct the runner with the context object, register nodes, and call start() / onGameTick() / stop(). The runner owns the ScriptExecutor: selection runs on the client thread and execution on the script worker. Catalog plugins that already own a worker may keep selectNode() + executeNode(TaskNode).

Usage:


 TaskNodeRunner<MyContext> runner = new TaskNodeRunner<>(context);
 runner.addNodes(
     new DeathRecoveryTask(),
     new EatFoodTask(),
     new LootTask(),
     new AttackTask());
 runner.start();

 // From onGameTick:
 runner.onGameTick();
 
See Also:
  • Constructor Details

    • TaskNodeRunner

      public TaskNodeRunner(C context)
      Creates a runner that holds context for every tick. start() names the worker thread after the context class.
    • TaskNodeRunner

      public TaskNodeRunner(C context, String workerName)
      Creates a runner that holds context and uses workerName as the ScriptExecutor thread name.
    • TaskNodeRunner

      public TaskNodeRunner(C context, BooleanSupplier runnableCheck)
      Creates a runner that holds context and skips ticks when runnableCheck returns false.
    • TaskNodeRunner

      public TaskNodeRunner(Supplier<C> contextSupplier)
      Creates a runner with the given context supplier. Register nodes via addNode(TaskNode).
      Parameters:
      contextSupplier - supplies the shared context each tick
    • TaskNodeRunner

      public TaskNodeRunner(Supplier<C> contextSupplier, BooleanSupplier runnableCheck)
      Creates a runner with a runnable guard. When the guard returns false, tick() is a no-op.
      Parameters:
      contextSupplier - supplies the shared context each tick
      runnableCheck - returns true when the script is in a runnable state
  • Method Details

    • addNode

      public void addNode(TaskNode<C> node)
      Registers a node. Equal-priority nodes are evaluated in registration order.
      Parameters:
      node - the node to register
    • addNodes

      @SafeVarargs public final void addNodes(TaskNode<C>... tasks)
      Registers tasks. Higher-priority eligible tasks win; equal priorities keep this registration order.
      Parameters:
      tasks - tasks to register
    • removeNode

      public void removeNode(String name)
      Removes a node by name.
      Parameters:
      name - the name of the node to remove
    • getNodes

      public List<TaskNode<C>> getNodes()
      Returns an unmodifiable view of all registered nodes.
    • getActiveNode

      public TaskNode<C> getActiveNode()
      Returns the currently active node (the one that last executed), or null.
    • getNodeCount

      public int getNodeCount()
      Returns the number of registered nodes.
    • initialize

      public void initialize()
      Initializes (or reinitializes) the runner, clearing all tracking state. Does not reset nodes; use reset() for that.
    • shutdown

      public void shutdown()
      Shuts down the runner: stops the owned worker if present and calls TaskNode.cleanup() on all nodes.
    • start

      public void start()
      Starts the owned script worker. Safe to call again while running. Catalog plugins that construct their own ScriptExecutor must not call this.
    • stop

      public void stop()
      Stops the owned worker (waiting up to 2 s for it to exit), cancels pending HANDS dispatches and resets nodes. Does not remove registered nodes; start() may follow.
    • onGameTick

      public void onGameTick()
      Game-tick pulse. Decrements reconnect grace, then signals the owned worker. No-op while disconnected or when start() has never been called.

      Call from onGameTick on the client thread. It returns at once: selection and execution happen on the worker. While the forced-move guard holds bot actions the worker runs no node and the status reads "HELD: ...".

    • setWorkerPrelude

      public void setWorkerPrelude(Runnable workerPrelude)
      Installs detached observation work that must be serialized with node selection.

      The callback runs on this runner's script worker immediately before GameThread.ensure(Supplier) selects a node. It may marshal bounded reads, but it must not dispatch gameplay actions or sleep. This gives plugins with passive observers one tick pipeline instead of a second worker competing for the client-thread queue.

    • onDisconnect

      public void onDisconnect()
      Pauses the owned worker and requests a node reset on the next cycle.
    • onReconnect

      public void onReconnect()
      Resumes after disconnect with a 5-tick grace window.
    • onReconnect

      public void onReconnect(int graceTicks)
      Resumes after disconnect with graceTicks of idle ticks.
    • tick

      public boolean tick()
      Executes one tick. Iterates all registered nodes, finds the highest-priority node whose TaskNode.shouldExecute(Object) returns true, and executes it.

      Only ONE node executes per tick.

      Threading: This method runs everything on the calling thread. For script-thread execution (where sleepUntil must not block the client), use selectNode() + executeNode(TaskNode) instead.

      Returns:
      true if the selected node performed a blocking action
    • setTraceListener

      public void setTraceListener(TaskTraceListener trace)
      Installs an optional diagnostics listener for selection and execution events, or clears it with null. Callbacks run on the selecting or executing thread and must return quickly.
    • selectNode

      public TaskNode<C> selectNode()
      Finds the highest-priority enabled node whose TaskNode.shouldExecute(C) returns true, without executing it. Ties keep registration order; a predicate that throws is logged and skipped. All predicates share one ReadScope, so repeated snapshot reads within this pass are served once.

      Threading: predicates read game state, so call this on the client thread, e.g. GameThread.ensure(runner::selectNode) from a worker. The owned worker started by start() already does this.

      Returns:
      the selected node, or null if none validates
    • executeNode

      public boolean executeNode(TaskNode<C> node)
      Executes a previously selected node. Call this after selectNode().

      Threading: This method runs the node's execute(), which may call sleepUntil(). It should run on the script thread so that sleeping blocks only the script, not the game.

      Parameters:
      node - the node to execute (from selectNode())
      Returns:
      true if the node performed a blocking action
    • getActiveTaskName

      public String getActiveTaskName()
      Returns the name of the currently active node, or null if idle.
    • getActiveTaskStatus

      public String getActiveTaskStatus()
      Returns the status of the currently active node, or "Idle".
    • didLastTickBlock

      public boolean didLastTickBlock()
      Returns whether the last tick resulted in a blocking action.
    • getExecutionTimes

      public Map<String,Long> getExecutionTimes()
      Returns an unmodifiable map of node name to last execution duration (ms).
    • getExecutionCounts

      public Map<String,Long> getExecutionCounts()
      Returns an unmodifiable map of node name to total execution count.
    • getTotalTicks

      public long getTotalTicks()
      Returns the total number of ticks processed.
    • getNodeStats

      public String getNodeStats()
      Builds a human-readable statistics report for all registered nodes.
    • reset

      public void reset()
      Resets all nodes and clears active state.
    • markIdle

      public void markIdle()
      Clears the active task/status when no node validates during split-thread execution.
    • clearNodes

      public void clearNodes()
      Removes all registered nodes.