Class EntityQuery<T extends EntityContext, Q extends EntityQuery<T,Q>>

java.lang.Object
com.botwithus.bot.api.entities.EntityQuery<T,Q>
Type Parameters:
T - rich entity type
Q - self-type for fluent chaining (CRTP)
Direct Known Subclasses:
GroundItems.Query, Npcs.Query, Players.Query, Projectiles.Query, SceneObjects.Query
public abstract class EntityQuery<T extends EntityContext, Q extends EntityQuery<T,Q>> extends Object
Fluent query builder shared across entity types. Subclasses bind the concrete result type T (Npc, Player, ...) and provide the snapshot-backed source stream plus the bits that are entity-specific (id field, name resolution).

Filters compose: each call narrows the set. Terminal operations (all(), nearest(), first(), count(), exists(), stream()) materialise the result. The builder is single-use — once you call a terminal it's done; build a new query for another lookup.

All filters run client-side against the published snapshot, so a query is a few microseconds plus whatever definition lookups the rich wrappers trigger (which are cached by id on the entity facade).

  • Method Summary

    Modifier and Type
    Method
    Description
    List<T>
    all()
     
    int
    count()
     
    boolean
    exists()
     
    Q
    filter(Predicate<T> predicate)
    Adds a predicate; multiple calls AND together.
    Optional<T>
    findFirst()
    First match as Optional.
    Optional<T>
    findNearest()
    Nearest as Optional.
    T
    first()
    First match in source order, or null.
    Q
    limit(int max)
    Cap the number of results.
    Q
    named(String name)
    Filter by display name (case-insensitive substring).
    Q
    namedExact(String name)
    Filter by display name (case-insensitive exact match).
    Q
    nameMatching(String regex)
    Filter by display name (regex match against the full name).
    T
    nearest()
    Nearest result, or null when no match.
    Q
    onPlane(int plane)
    Filter to a specific plane.
    Q
    sortByDistance()
    Sort results by distance from the local player, ascending.
    Stream<T>
    stream()
    Stream over the materialised result list (filters/sort already applied).
    Q
    visible()
    Convenience shim — the snapshot only carries visible entities, so this method is a no-op chain.
    Q
    withId(int typeId)
    Filter by type/definition id.
    Q
    within(int tileX, int tileY, int radius)
    Filter to entities within radius tiles (Chebyshev) of the given world tile.
    Q
    withinDistance(int radius)
    Filter to entities within radius tiles of the local player.

    Methods inherited from class Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • filter

      public Q filter(Predicate<T> predicate)
      Adds a predicate; multiple calls AND together.

    • named

      public Q named(String name)
      Filter by display name (case-insensitive substring).

    • namedExact

      public Q namedExact(String name)
      Filter by display name (case-insensitive exact match).

    • nameMatching

      public Q nameMatching(String regex)
      Filter by display name (regex match against the full name).
      Throws:
      PatternSyntaxException - if regex is malformed

    • withId

      public Q withId(int typeId)
      Filter by type/definition id.

    • onPlane

      public Q onPlane(int plane)
      Filter to a specific plane.

    • visible

      public Q visible()
      Convenience shim — the snapshot only carries visible entities, so this method is a no-op chain. Kept so call sites that pre-date the rewrite (e.g. new SceneObjects(api).query().withId(id).visible().all()) keep compiling.

    • within

      public Q within(int tileX, int tileY, int radius)
      Filter to entities within radius tiles (Chebyshev) of the given world tile.

    • withinDistance

      public Q withinDistance(int radius)
      Filter to entities within radius tiles of the local player. Returns no results when the local player is not in-game.

    • sortByDistance

      public Q sortByDistance()
      Sort results by distance from the local player, ascending.

    • limit

      public Q limit(int max)
      Cap the number of results. Applied after sorting.

    • all

      public List<T> all()

    • nearest

      public T nearest()
      Nearest result, or null when no match. Implies sortByDistance().

    • findNearest

      public Optional<T> findNearest()
      Nearest as Optional.

    • first

      public T first()
      First match in source order, or null. No distance sort applied.

    • findFirst

      public Optional<T> findFirst()
      First match as Optional.

    • count

      public int count()

    • exists

      public boolean exists()

    • stream

      public Stream<T> stream()
      Stream over the materialised result list (filters/sort already applied).