Events and game data

​

Query helpers

Optional<NPC> banker = NPCs.search()
    .withAnyAction("Bank", "Collect")
    .nameContainsIgnoreCase("banker")
    .nearestByPath();

List<Widget> firstFiveRunes = Bank.search()
    .idIn(Set.of(561, 563, 565))
    .limit(5)
    .result();

• Never use first() as a nearest-target policy. Scene collection order is not a distance ranking. Use walkable().nearestToPoint(anchor) for a stable work area or nearestByPath() for the shortest reachable target from the player.
• Name predicates strip tags for you. Inventory and equipment widgets return styled names like <col=ff9040>Steel axe</col>; pass bare strings.
• Mapped names resolve through IdMapRegistry. A mapped base name such as Ancient sceptre matches its released variants. Item name filters fall back to the item-definition API when a widget carries only an ID.
• geTradeable() is the market filter. The older tradeAble() remains for source compatibility and delegates to it.
• ItemContainers.search(...) snapshots any container as immutable ContainerItem values. Each call copies live state; take a fresh search(...) per independent assertion.
• ProjectileQuery and GraphicsObjectQuery snapshot on every search() rather than tick-caching. Reuse one query object to chain filters within a tick.

​

Event snapshots

SdkEvents.xpGained().forEach(event ->
        log.debug("{} gained {}", event.getSkill(), event.getGainedXp()));

List<NpcLifecycleEvent> bankers = SdkEvents.npcSpawns().stream()
        .filter(event -> "Banker".equals(event.getName()))
        .collect(Collectors.toList());

​

Scenario and replay foundation

• EventEnvelope<T> carries a stable payload, deterministic sequence and tick metadata, and source provenance.
• StimulusDispatcher routes envelopes to the first supporting StimulusHandler under an explicit DispatchMode (SYNC, ASYNC, DRY_RUN), deduplicating by event ID per session.
• ScenarioRunner operates tick-driven: dispatch once, then verify state on later ticks. Posting an event never counts as proof the target processed it.
• EventReplayService replays a recorded EventTimeline through the dispatcher under a ReplayPolicy.
• StateFixtureService manages named state fixtures with atomic apply/rollback for deterministic scenario setup.

​

Utility actions

​

Game variables

int stage = GameVars.getVarbit(7334);            // quest stage varbit
boolean autoRetaliate = GameVars.getVarPlayerBit(1, 0);

• getVarbit(id) and getVarPlayer(id) return 0 when the client reads null.
• getVarPlayerBit(id, bitIndex) returns false when the client reads null.

​

ID maps

IdMapRegistry maps = IdMapRegistry.getDefault();

Optional<String> itemName = maps.itemName(995);
List<Integer> itemIds = maps.itemIds("Coins");
List<Integer> npcIds = maps.npcIds("'Beedy-eye' Jones");
List<Integer> objectIds = maps.objectIds("4-poster");

​

Progress reads

​

QuestProgressApi

QuestState state = QuestProgressApi.state(Quest.COOKS_ASSISTANT);
Optional<Quest> quest = QuestProgressApi.findQuest("Cook's Assistant");
InteractionResult allowed = QuestProgressApi.satisfies(requirement);

​

DiaryProgressApi

Optional<DiaryProgress> lumbridgeEasy =
        DiaryProgressApi.progress(DiaryRegion.LUMBRIDGE, DiaryTier.EASY);

List<DiaryProgress> varrock = DiaryProgressApi.forRegion(DiaryRegion.VARROCK);