Class ObjectQuery

java.lang.Object
privbot.query.ObjectQuery

public final class ObjectQuery extends Object
Fluent filter chain over scene objects (walls, decorations, ground objects and game objects), built by ctx.objects.query().

Name, action and player-relative filters and closest() read object definitions and the player position, so off the client thread they re-run inside GameThread.ensure(java.util.function.Supplier<T>, T) on a copy and return that copy. If that read is dropped they return null, so a long chain from a worker can throw; split the chain or wrap it in ctx.read(...). Filters narrow the query in place, so a query is single-use.

  • Constructor Details

    • ObjectQuery

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

    • withAction

      public ObjectQuery withAction(String... actions)
      Keeps objects whose definition has at least one of the given actions (case-insensitive substring).

      Runs composition/action resolution on the game thread when the caller is not on the client thread (e.g. script executor), matching

      invalid reference
      GameObjects#query()
      behaviour.
    • withName

      public ObjectQuery withName(String... names)
      Name substring match (see PrivObject.getName()).

      Must run on the game thread because filtering calls getObjectDefinition via PrivObject.getName().

    • withId

      public ObjectQuery withId(int... ids)
      Keeps objects whose scene id is one of ids; no ids leaves the query unchanged.
    • withinTiles

      public ObjectQuery withinTiles(int maxTiles)
      Chebyshev distance on the current plane (OSRS tile steps). Same contract as NPCQuery.withinTiles(int).
    • atTile

      public ObjectQuery atTile(net.runelite.api.coords.WorldPoint tile)
      Keeps objects whose world location equals tile (same x, y, plane). Null tile → empty.
    • nearTile

      public ObjectQuery nearTile(net.runelite.api.coords.WorldPoint tile, int radius)
      Chebyshev radius around tile on the same plane. Null tile or radius < 0 → empty.
    • filter

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

      public ObjectQuery where(Predicate<PrivObject> pred)
    • playerNorthOf

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

      public ObjectQuery playerSouthOf()
      Keeps objects the local player stands south of (player Y < object Y).
    • playerWestOf

      public ObjectQuery playerWestOf()
      Keeps objects the local player stands west of (player X < object X).
    • playerEastOf

      public ObjectQuery playerEastOf()
      Keeps objects the local player stands east of (player X > object X).
    • closest

      public PrivObject closest()
      Closest by Euclidean distance to the local player. Requires client thread for player location.

      The distance is PrivObject.distanceTo(net.runelite.api.coords.WorldPoint), which is the tile-step (Chebyshev) distance and ignores the plane. Marshals through GameThread.ensure(java.util.function.Supplier<T>, T) off the client thread and returns null when that read is dropped; returns the first entry when the player position cannot be read; null when empty.

    • closest

      public PrivObject closest(Predicate<PrivObject> pred)
      Narrows by pred (in place), then returns the closest match; see closest().
    • nearest

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

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

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

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

      public List<PrivObject> 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.