Class Npcs

java.lang.Object

com.botwithus.bot.api.entities.Npcs

public final class Npcs
extends Object

NPC query facade. Singleton per GameAPI; obtain via api.npcs().

Holds a definition cache so repeat getNpcType lookups for the same typeId are free after the first hit. NpcType is effectively immutable per session, so cache entries never expire — the map only grows, bounded in practice by the number of distinct NPC types a script encounters (typically < 100).

Npc target = api.npcs().query()
    .named("Goblin")
    .withinDistance(15)
    .filter(n -> n.hasOption("Attack"))
    .nearest();

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	Npcs.Query	Query subclass — wires the snapshot stream + name resolution to EntityQuery.

Constructor Summary

Constructors

Constructor	Description
Npcs(GameAPI api)

Method Summary

Modifier and Type	Method	Description
List<Npc>	all(int typeId)	All NPCs of the given type id.
List<Npc>	all(String name)	All NPCs whose name matches name (case-insensitive contains).
List<Npc>	allByGameval(String gameval)	All NPCs with the given gameval name.
void	clearDefinitionCache()	Drop the definition cache.
int	definitionCacheSize()	Diagnostic — current size of the NpcType cache.
Npc	nearest(int typeId)	Nearest NPC of the given type id, or null.
Npc	nearest(String name)	Nearest NPC matching name (case-insensitive contains), or null.
Npc	nearestByGameval(String gameval)	Nearest NPC with the given gameval name (e.g.
Npcs.Query	query()	Start a fluent query.

Methods inherited from class Object

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

Constructor Details

Npcs

public Npcs(GameAPI api)

Method Details

query

public Npcs.Query query()

Start a fluent query. Each call returns a fresh builder.

nearest

public Npc nearest(String name)

Nearest NPC matching name (case-insensitive contains), or null.

nearest

public Npc nearest(int typeId)

Nearest NPC of the given type id, or null.

all

public List<Npc> all(String name)

All NPCs whose name matches name (case-insensitive contains).

all

public List<Npc> all(int typeId)

All NPCs of the given type id.

nearestByGameval

public Npc nearestByGameval(String gameval)

Nearest NPC with the given gameval name (e.g. "HANS"), or null. Distinct from nearest(String), which matches the localised display name.

allByGameval

public List<Npc> allByGameval(String gameval)

All NPCs with the given gameval name. Distinct from all(String), which matches the localised display name.

clearDefinitionCache

public void clearDefinitionCache()

Drop the definition cache. Useful after a game update or for tests.

definitionCacheSize

public int definitionCacheSize()

Diagnostic — current size of the NpcType cache.