The Query System

[Naton 1028]

What is a query/the query system?

The query system is an easy-to-use, flexible, and powerful way to search for entities. This should be used any time you want to find some entity (think like some type in the package org.tribot.script.types). Visit the Query documentation to see all types that can be queried over (filter to show only static methods).

An individual query allows you to search over a specific entity. An example is an NpcQuery. An NpcQuery allows you to query over Npcs. The corresponding type is listed in the documentation, and can generally be deduced from the query class name. You will apply filters on a query and then some method to retrieve a result.

 

Javadocs: https://runeautomation.com/docs/sdk/javadocs/org/tribot/script/sdk/query/Query.html

 

How do I use it?

All queries are available as static methods in the org.tribot.script.sdk.query.Query class.

The general approach is you will create a query, apply some filters/maybe apply some sorting, and retrieve some result.

An example of creating a query is calling

Query.npcs()

This creates an NpcQuery that you can then apply filters on and retrieve a result.

A full query example is

Query.npcs().isHealthBarVisible().sortedByPathDistance().findFirst()

You can also nicely indent the query method chain to make it easier to read:

Query.npcs()			// Create the query
	.isHealthBarVisible()	// Filter
	.sortedByPathDistance()	// Sort
	.findFirst()		// Execute and retrieve result

 

What are filters?

Filters allow you to filter what result you are querying. Maybe you want only npcs that have a visible health bar, or only npcs in a specific area. You can apply these through pre-configured helper methods (such as NpcQuery#isHealthBarVisible), or a custom filter through Query#filter.

Note that you don't have to apply filters. If you want to get all loaded npcs, you can use Query.npcs().toList().

 

How do I get a result from a query?

There are multiple methods to retrieve results from executing a query. Some examples are Query#toList which executes the query and returns a list of all matching entities. Another method is Query#anyMatch which executes the query and returns true/false if there is any entity that matches the filters. Visit the documentation to see all methods.

There's also a method InteractableQuery#findBestInteractable that is available for any interactable entity. This attempts to find a target to interact with based on distance to player/mouse.

Note that each Query object can only be executed once. Create a new Query each time you need one.

 

Common result extraction methods:

Query#toList

Query#findFirst - note this returns a java Optional. See https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Optional.html

Query#isAny

Query#count

Query#stream

 

Examples:

 

GroundItemQuery:

Looting rune arrows

boolean looted = Query.groundItems()
          .nameEquals("Rune arrow")
          .findFirst()
          .map(loot -> loot.interact("Take"))
          .orElse(false);

 

Check if we are standing on any logs

boolean standingOnLogs = Query.groundItems()
          .nameContains("logs")
          .tileEquals(MyPlayer.getPosition())
          .isAny();

 

InventoryQuery:

Check if we have any item whose name contains dragon

Query.inventory().nameContains("dragon").isAny()

 

Light a log (use a tinderbox on a log)

Query.inventory()
	.idEquals(LOG_ID)
	.findFirst()
	.map(log -> Query.inventory()
			.idEquals(TINDERBOX_ID)
			.findFirst()
			.map(tinderbox -> tinderbox.useOn(log))
			.orElse(false))

 

 

NpcQuery:

Check if there is any cow within 10 tiles that isn't being interacted with

Query.npcs().nameEquals("Cow").isNotBeingInteractedWith().maxDistance(10).isAny()

 

Finding and interacting with a green dragon

boolean attacked = Query.npcs()
          .nameEquals("Green dragon")
          .findBestInteractable()
          .map(npc -> npc.interact("Attack"))
          .orElse(false);

 

 

WidgetQuery:

(note for performance reasons, it's generally recommended to provide a root index to search in, rather than searching everything)

 

Find a visible widget that has a root index of 12, has a depth of 2, and has either "Hide worn items", or "Show worn items" as an action

Query.widgets().inRoots(12).isDepth(2).actionEquals("Hide worn items", "Show worn items").isVisible().findFirst()

 

Check if there exists any interface with the click here to continue text

Query.widgets().textEquals("Click here to continue").isAny()

 

Closing the first widget with a "Close" action

boolean closed = Query.widgets().actionEquals("Close").findFirst().map(widget -> widget.click("Close")).orElse(false);

 

[SkrrtNick 236]

Thank you for all your hard work Naton!

[scriptoboy 39]

Query system legit brought Tribot scripting to another level! Thanks a bunch for this!

[Mochi 2]

Whats the difference between `isPresent` vs `isAny`
 

and I also wonder when to use Query system vs doing something like Widgets.get() or Inventory.contains("name")

Thanks for this tutorial!

[Naton 1028]

36 minutes ago, Mochi said:

Whats the difference between `isPresent` vs `isAny`
 

and I also wonder when to use Query system vs doing something like Widgets.get() or Inventory.contains("name")

Thanks for this tutorial!

isPresent is a method in Optional, not Query. Query.isAny() is functionally the same as Query.findFirst().isPresent().

The query system is the only way to access some entities such as Npcs, but for things like inventory, the query system would be for more involved searches where Inventory.contains(name) doesn't cut it (Inventory.contains(name) actually uses the query system internally).

[Mochi 2]

32 minutes ago, Naton said:

isPresent is a method in Optional, not Query. Query.isAny() is functionally the same as Query.findFirst().isPresent().

The query system is the only way to access some entities such as Npcs, but for things like inventory, the query system would be for more involved searches where Inventory.contains(name) doesn't cut it (Inventory.contains(name) actually uses the query system internally).

Thank you! Looking forward to more tutorials!!!