Query Introduction

Query

The Query API is the main system in RSBot to get the information you need. The vast majority of the RSBot API is reliant on the Query system, so a solid understanding of it is necessary. There are several different types of queries, all with a unique purpose, but all of them extend the base AbstractScript, and their general syntax is all the same. The query system is a chained, fluent API much like jQuery (which is was designed after) and the Java Stream API. Each method will modify the contents of the query, then return itself. This allows you to chain function calls, instead of having to call each separately.

Example: ctx.npcs.select().name("Guard").nearest().poll()
So if we dissect the query call:

select(): populate the query with all of the loaded Npcs
name("Guard"): filter the query to only include Npcs named 'Guard'
nearest(): sort the query by distance, nearest first
poll(): return and remove the head (first entity) in the query

It is very important to note that the contents of the query are persistent through calls, until reset using select(). So the call the nearest() only applies the sort the previous contents of the query (Npcs named Guard").

AbstractQuery Methods

These are not all of the methods, just the important ones.

select(): resets and populates the query with the loaded entities.
select(Filter<K>): filters the current elements by the given filter. Does NOT reset the contents. select() and select(Filter) have nothing to do with each other.
size(): returns the number of the elements in the query.
isEmpty(): returns if the size of the query is zero (0).
poll(): returns and removes the head (first element) of the query.
peek(): returns and preserves the head of the query.

Using Queries

Queries are used similarly to lists: you can get a specific entity from the query (as you see previously with poll()), or you can iterate over them with a for-each loop. The query will only contain valid entities, so if you were to use a loop over them, nothing inside the loop would execute if it were empty. If you use poll(), however, it can return nil.

nil

peek() and poll() both return nil if the query is empty. They will never return null. nil is just an empty entity. It contains no information, but can be used like any other entity. Rather than null-checking an entity, you should check valid() (more info later).