Skip to main content

Query Helpers

Query classes now expose common collection-style helpers where the underlying type supports them:

  • withAnyAction, withoutAction
  • nameContainsIgnoreCase, withTextContainsIgnoreCase
  • idIn(Collection<Integer>)
  • withMappedName(String) on item, NPC, and tile object queries
  • exists, count, single
  • limit, sorted
  • walkable on tile object and ground-item queries
  • geTradeable

StringMatchers centralizes tag-stripping and case-insensitive matching.

For scene targets, compose eligibility filters before choosing a finalizer. walkable().nearestToPoint(anchor) selects the reachable object closest to a stable work-area anchor; nearestByPath() selects the shortest reachable target from the player. Do not use first() when the behavior promises nearest spatial selection because scene collection order is not a distance ranking.

ItemQuery.geTradeable() filters through ItemComposition.isGeTradeable(). Use it for Grand Exchange or market-facing filters. The older ItemQuery.tradeAble() remains for source compatibility and delegates to geTradeable(); it no longer uses RuneLite's broader ItemComposition.isTradeable() semantics.

ItemQuery.withMappedName(...), NPCQuery.withMappedName(...), and TileObjectQuery.withMappedName(...) resolve generated IDs through IdMapRegistry and then filter by ID. Item mapped-name lookups also include RuneLite item variation groups for the current release. These are additive helpers; existing withName(...) methods remain exact runtime-name filters. See docs/id-maps.md for cache and import behavior.

ItemQuery name filters resolve the comparison name from the widget first. If RuneLite does not populate a widget name, the query resolves the item ID through the project item-definition API before comparing. This keeps bank and inventory name filters usable when the live widget only carries item IDs.

All name predicates on ItemQuery, EquipmentItemQuery, and WidgetQuery (withName, nameContains, nameContainsNoCase, nameContainsIgnoreCase, matchesWildCardNoCase) route the widget side through Text.removeTags before comparison. Inventory and equipment widgets return styled names like <col=ff9040>Steel axe</col>; callers can safely pass bare strings (nameContains("axe"), withName("Steel axe")) without manual stripping. The query parameter is not stripped on nameContains family methods - keep call sites passing plain strings.

Examples:

Optional<NPC> banker = NPCs.search()
    .withAnyAction("Bank", "Collect")
    .nameContainsIgnoreCase("banker")
    .nearestByPath();
List<Widget> firstFiveNotedItems = Bank.search()
    .idIn(Set.of(561, 563, 565))
    .limit(5)
    .result();

Query Entry Points​

Most callers start from a static container and then chain a query object:

  • Inventory.search() -> ItemQuery
  • Bank.search() -> ItemQuery
  • BankInventory.search() -> ItemQuery
  • Equipment.search() -> EquipmentItemQuery
  • DepositBox.search() -> ItemQuery
  • Shop.search() -> ItemQuery
  • ShopInventory.search() -> ItemQuery
  • GrandExchangeInventory.search() -> ItemQuery
  • TradeInventory.search(theirs) -> ItemQuery
  • NPCs.search() -> NPCQuery
  • Players.search() -> PlayerQuery
  • TileObjects.search() -> TileObjectQuery
  • TileItems.search() -> TileItemQuery
  • Widgets.search() -> WidgetQuery

BankItemWidget and EquipmentItemWidget are compatibility wrappers for bank and equipment item metadata. They do not implement RuneLite's Widget interface. Use getWidget() when a lower-level widget action needs the backing RuneLite widget.

Support matrix:

  • WidgetQuery: actions, text contains, item IDs, count/single/limit/sorted.
  • ItemQuery: actions, names, mapped names, item IDs, GE tradeability, count/single/limit/sorted.
  • EquipmentItemQuery: actions, names, equipment item IDs, count/single/limit/sorted.
  • NPCQuery: actions, names, mapped names, IDs, count/single/limit/sorted.
  • TileObjectQuery: actions, names, mapped names, IDs, walkable, count/single/limit/sorted.
  • TileItemQuery: names, IDs, walkable, count/single/limit/sorted.
  • PlayerQuery: names and collection helpers; player action filtering is not exposed by this RuneLite API surface.

Query Pipeline Flow​

The query pipeline converts a static facade scan of game objects/widgets/NPCs into a filtered stream of elements: