Class NPCQuery

java.lang.Object
privbot.query.NPCQuery

public final class NPCQuery extends Object
Fluent filter chain over the NPCs in the scene, built by ctx.npcs.query().

The hook takes the NPC list on the client thread; the chain then runs on the caller's thread. Filters narrow the query in place, so a query is single-use. Native name, action and position reads marshal through GameThread.ensure(java.util.function.Supplier<T>, T); custom filter predicates retain their caller-thread contract. An empty result can mean "nothing matches" or "the scene could not be read"; check ctx.game.isLoggedIn() before acting on an absence.

  • Constructor Details

    • NPCQuery

      public NPCQuery(List<PrivNPC> raw, net.runelite.api.Client client)
      Wraps a copy of raw; plugins normally get a query from ctx.npcs.query().
  • Method Details

    • withId

      public NPCQuery withId(int... ids)
      Keeps NPCs whose composition id is one of ids; no ids leaves the query unchanged.
    • withAction

      public NPCQuery withAction(String... actions)
      Keeps NPCs whose composition has at least one of the given actions (case-insensitive substring).
    • withName

      public NPCQuery withName(String... names)
      Keeps NPCs whose name contains any of names (case-insensitive substring, tags stripped). "Goblin" also matches "Goblin champion"; filter by id or an exact predicate when that matters.
    • filter

      public NPCQuery filter(Predicate<PrivNPC> pred)
      Narrows this query in place and returns it. Queries are mutable and single-use; the predicate runs on the calling thread.
    • where

      public NPCQuery where(Predicate<PrivNPC> pred)
    • alive

      public NPCQuery alive()
      Excludes dead NPCs using PrivNPC.isAlive().
    • withinTiles

      public NPCQuery withinTiles(int maxTiles)
      Chebyshev distance on the current plane (OSRS tile steps). Leaves the query unchanged when the local player's position cannot be read or maxTiles is negative.
    • playerNorthOf

      public NPCQuery playerNorthOf()
      Keeps NPCs whose tile the local player stands strictly north of (player Y > NPC Y, same plane). See PlayerRelativeToPoint.
    • playerSouthOf

      public NPCQuery playerSouthOf()
      Keeps NPCs the local player stands south of (player Y < NPC Y).
    • playerWestOf

      public NPCQuery playerWestOf()
      Keeps NPCs the local player stands west of (player X < NPC X).
    • playerEastOf

      public NPCQuery playerEastOf()
      Keeps NPCs the local player stands east of (player X > NPC X).
    • hintArrowOnly

      public NPCQuery hintArrowOnly()
      Keeps only the NPC that is the current hint arrow target.
    • excludeHintArrow

      public NPCQuery excludeHintArrow()
      Keeps NPCs that are NOT the hint arrow target (inverse of hintArrowOnly()).
    • closest

      public PrivNPC closest()
      The NPC nearest the local player in tile steps. NPCs on another plane rank last. When the player's position cannot be read this returns the first entry instead; null when empty.
    • closest

      public PrivNPC closest(Predicate<PrivNPC> pred)
      Filter then nearest to the local player.
    • nearest

      public PrivNPC nearest()
      Alias of closest().
    • nearest

      public PrivNPC nearest(Predicate<PrivNPC> pred)
    • first

      public PrivNPC first()
      The first remaining entry in snapshot order, or null when the query is empty.
    • first

      public PrivNPC first(Predicate<PrivNPC> pred)
      Narrows by pred (in place) and returns the first match, or null.
    • list

      public List<PrivNPC> list()
      An unmodifiable view of the remaining entries.
    • empty

      public boolean empty()
      True when no entry is left.
    • size

      public int size()
      The number of entries left.