Fix Queryable API gaps: isDespawned bug, missing methods, missing example files

runelite-client/src/main/java/net/runelite/client/plugins/microbot/api/AbstractEntityQueryable.java

@@ -199,6 +199,11 @@ public List<E> toList() {
         return source.collect(Collectors.toList());
     }
 
+    @Override
+    public int count() {
+        return (int) source.count();
+    }
+
     public E firstOnClientThread() {
         return Microbot.getClientThread().invoke(() -> first());
     }

runelite-client/src/main/java/net/runelite/client/plugins/microbot/api/IEntityQueryable.java

@@ -35,6 +35,8 @@ public interface IEntityQueryable<Q extends IEntityQueryable<Q, E>, E extends IE
 
     List<E> toList();
 
+    int count();
+
     E firstOnClientThread();
 
     E nearestOnClientThread();

runelite-client/src/main/java/net/runelite/client/plugins/microbot/api/QUERYABLE_API.md

@@ -343,16 +343,16 @@ List<Rs2PlayerModel> friends = playerCache.query()
 
 **Rs2PlayerModel Methods:**
 ```java
-player.getName()           // Player name
-player.getCombatLevel()    // Combat level
-player.getHealthRatio()    // Health (-1 if not visible)
-player.isFriend()          // Is friend?
-player.isClanMember()      // In your clan?
-player.isFriendsChatMember() // In friends chat?
-player.getSkullIcon()      // Skull icon (-1 if none)
-player.getOverheadIcon()   // Prayer icon
-player.getAnimation()      // Current animation
-player.isInteracting()     // Is interacting?
+player.getName()              // Player name
+player.getCombatLevel()       // Combat level
+player.getHealthRatio()       // Health (-1 if not visible)
+player.isFriend()             // Is friend?
+player.isClanMember()         // In your clan?
+player.isFriendsChatMember()  // In friends chat?
+player.getSkullIcon()         // Skull icon (-1 if none)
+player.getOverheadIcon()      // Prayer icon (HeadIcon or null)
+player.getAnimation()         // Current animation
+player.isInteracting()        // Is interacting?
 ```
 
 ### 4. Rs2TileObjectQueryable - Tile Object Queries
@@ -389,7 +389,7 @@ obj.getName()              // "Tree"
 obj.getId()                // Object ID
 obj.getWorldLocation()     // WorldPoint
 obj.click("Chop down")     // Interact with object
-obj.interact("Mine")       // Alternative interact
+obj.click("Mine")          // Interact with a specific action
 ```
 
 ---
@@ -478,6 +478,16 @@ List<Rs2NpcModel> guards = npcCache.query()
     .toList();
 ```
 
+#### `count()`
+Returns the number of matching entities.
+
+```java
+int guardCount = npcCache.query()
+    .withName("Guard")
+    .within(10)
+    .count();
+```
+
 ### Filter Operations
 
 These filter entities and return the queryable for chaining:

runelite-client/src/main/java/net/runelite/client/plugins/microbot/api/README.md

@@ -103,6 +103,7 @@ api/
 ├── tileobject/                   # Tile object queries
 │   ├── Rs2TileObjectQueryable.java
 │   ├── Rs2TileObjectCache.java
+│   ├── TileObjectApiExample.java
 │   └── models/
 │       └── Rs2TileObjectModel.java
 │
@@ -145,6 +146,7 @@ Check the `*ApiExample.java` files in each subdirectory for complete examples:
 - `npc/NpcApiExample.java` - NPC query examples
 - `tileitem/TileItemApiExample.java` - Ground item examples
 - `player/PlayerApiExample.java` - Player query examples
+- `tileobject/TileObjectApiExample.java` - Tile object examples
 
 ## 🔗 Additional Resources
 

runelite-client/src/main/java/net/runelite/client/plugins/microbot/api/player/PlayerApiExample.java

@@ -0,0 +1,101 @@
+package net.runelite.client.plugins.microbot.api.player;
+
+import net.runelite.client.plugins.microbot.Microbot;
+import net.runelite.client.plugins.microbot.api.player.models.Rs2PlayerModel;
+
+import java.util.List;
+
+/**
+ * Example usage of the Player Cache & Queryable API
+ *
+ * IMPORTANT: Always use Microbot.getRs2PlayerCache().query() to create queries.
+ * Never instantiate Rs2PlayerQueryable directly.
+ *
+ * - Rs2PlayerCache: Singleton cache accessed via Microbot.getRs2PlayerCache()
+ * - query(): Returns a fluent queryable interface for filtering players
+ */
+public class PlayerApiExample {
+
+    public static void examples() {
+        Rs2PlayerCache cache = Microbot.getRs2PlayerCache();
+
+        // Example 1: Get the nearest player
+        Rs2PlayerModel nearestPlayer = cache.query().nearest();
+
+        // Example 2: Get the nearest player within 10 tiles
+        Rs2PlayerModel nearestPlayerWithinRange = cache.query().nearest(10);
+
+        // Example 3: Find a player by name
+        Rs2PlayerModel specificPlayer = cache.query().withName("Zezima").nearest();
+
+        // Example 4: Find a player by multiple names
+        Rs2PlayerModel friend = cache.query().withNames("Alice", "Bob", "Charlie").nearest();
+
+        // Example 5: Find a player by ID
+        Rs2PlayerModel playerById = cache.query().withId(1234).nearest();
+
+        // Example 6: Get all players within 5 tiles as a list
+        List<Rs2PlayerModel> nearbyPlayers = cache.query()
+                .within(5)
+                .toList();
+
+        // Example 7: Find players that are animating (e.g. skilling or in combat)
+        List<Rs2PlayerModel> animatingPlayers = cache.query()
+                .where(player -> player.getAnimation() != -1)
+                .toList();
+
+        // Example 8: Find players that are moving
+        List<Rs2PlayerModel> movingPlayers = cache.query()
+                .where(player -> player.getPoseAnimation() != player.getIdlePoseAnimation())
+                .toList();
+
+        // Example 9: Count players in the current area
+        int playerCount = cache.query().count();
+
+        // Example 10: Count players within 15 tiles
+        int nearbyCount = cache.query().within(15).count();
+
+        // Example 11: Find the nearest player currently interacting with something
+        Rs2PlayerModel interactingPlayer = cache.query()
+                .where(player -> player.isInteracting())
+                .nearest();
+
+        // Example 12: Get all players as a list
+        List<Rs2PlayerModel> allPlayers = cache.query().toList();
+
+        // Example 13: Direct stream access when needed
+        Rs2PlayerModel firstPlayer = cache.getStream()
+                .filter(player -> player.getName() != null)
+                .findFirst()
+                .orElse(null);
+
+        // Example 14: Find players with a specific combat level
+        List<Rs2PlayerModel> highLevelPlayers = cache.query()
+                .where(player -> player.getCombatLevel() >= 100)
+                .toList();
+
+        // Example 15: Find the nearest reachable player
+        Rs2PlayerModel reachablePlayer = cache.query().nearestReachable();
+
+        // Example 16: Find friends nearby
+        List<Rs2PlayerModel> friends = cache.query()
+                .where(Rs2PlayerModel::isFriend)
+                .within(20)
+                .toList();
+
+        // Example 17: Find clan members nearby
+        List<Rs2PlayerModel> clanMembers = cache.query()
+                .where(Rs2PlayerModel::isClanMember)
+                .toList();
+
+        // Example 18: Find players with a skull (PvP/risk)
+        List<Rs2PlayerModel> skulledPlayers = cache.query()
+                .where(player -> player.getSkullIcon() != -1)
+                .toList();
+
+        // Example 19: Find the nearest skulled player within 10 tiles
+        Rs2PlayerModel nearestSkulled = cache.query()
+                .where(player -> player.getSkullIcon() != -1)
+                .nearest(10);
+    }
+}

runelite-client/src/main/java/net/runelite/client/plugins/microbot/api/player/models/Rs2PlayerModel.java

@@ -81,4 +81,49 @@ public  boolean isSalvaging() {
         }
         return false;
     }
+
+    /**
+     * Checks if this player is in your friends list.
+     *
+     * @return true if the player is a friend
+     */
+    public boolean isFriend() {
+        return Microbot.getClientThread().runOnClientThreadOptional(player::isFriend).orElse(false);
+    }
+
+    /**
+     * Checks if this player is a member of your clan.
+     *
+     * @return true if the player is a clan member
+     */
+    public boolean isClanMember() {
+        return Microbot.getClientThread().runOnClientThreadOptional(player::isClanMember).orElse(false);
+    }
+
+    /**
+     * Checks if this player is in your friends chat.
+     *
+     * @return true if the player is in the friends chat channel
+     */
+    public boolean isFriendsChatMember() {
+        return Microbot.getClientThread().runOnClientThreadOptional(player::isFriendsChatMember).orElse(false);
+    }
+
+    /**
+     * Gets the skull icon shown above this player's head, or -1 if none.
+     *
+     * @return the skull icon id, or -1
+     */
+    public int getSkullIcon() {
+        return Microbot.getClientThread().runOnClientThreadOptional(player::getSkullIcon).orElse(-1);
+    }
+
+    /**
+     * Gets the overhead prayer icon shown above this player's head.
+     *
+     * @return the overhead HeadIcon, or null if none
+     */
+    public HeadIcon getOverheadIcon() {
+        return Microbot.getClientThread().runOnClientThreadOptional(player::getOverheadIcon).orElse(null);
+    }
 }

runelite-client/src/main/java/net/runelite/client/plugins/microbot/api/tileitem/TileItemApiExample.java

@@ -71,7 +71,7 @@ public void examples() {
         Rs2TileItemModel target = cache.query()
                 .where(Rs2TileItemModel::isLootAble)
                 .where(item -> item.getTotalGeValue() >= 5000)
-                .where(item -> item.isDespawned())
+                .where(item -> !item.isDespawned())
                 .nearest(15);
 
         // Example 17: Find items by quantity

runelite-client/src/main/java/net/runelite/client/plugins/microbot/api/tileitem/models/Rs2TileItemModel.java

@@ -154,7 +154,8 @@ public boolean isOwned() {
     }
 
     public boolean isDespawned() {
-        return getDespawnTime() > Microbot.getClient().getTickCount();
+        int despawnTime = getDespawnTime();
+        return despawnTime != -1 && despawnTime <= Microbot.getClient().getTickCount();
     }
 
     public int getTotalGeValue() {
@@ -191,6 +192,15 @@ public boolean click() {
         return click("");
     }
 
+    /**
+     * Picks up this ground item (equivalent to clicking "Take").
+     *
+     * @return true if the interaction was dispatched successfully
+     */
+    public boolean pickup() {
+        return click("Take");
+    }
+
     public boolean click(String action) {
         try {
             int param0;

runelite-client/src/main/java/net/runelite/client/plugins/microbot/api/tileobject/TileObjectApiExample.java

@@ -0,0 +1,84 @@
+package net.runelite.client.plugins.microbot.api.tileobject;
+
+import net.runelite.client.plugins.microbot.Microbot;
+import net.runelite.client.plugins.microbot.api.tileobject.models.Rs2TileObjectModel;
+
+import java.util.List;
+
+/**
+ * Example usage of the Tile Object Cache & Queryable API
+ *
+ * IMPORTANT: Always use Microbot.getRs2TileObjectCache().query() to create queries.
+ * Never instantiate Rs2TileObjectQueryable directly.
+ *
+ * - Rs2TileObjectCache: Singleton cache accessed via Microbot.getRs2TileObjectCache()
+ * - query(): Returns a fluent queryable interface for filtering tile objects
+ */
+public class TileObjectApiExample {
+
+    public static void examples() {
+        Rs2TileObjectCache cache = Microbot.getRs2TileObjectCache();
+
+        // Example 1: Get the nearest tile object
+        Rs2TileObjectModel nearestObject = cache.query().nearest();
+
+        // Example 2: Get the nearest tile object within 10 tiles
+        Rs2TileObjectModel nearestObjectWithinRange = cache.query().nearest(10);
+
+        // Example 3: Find a tile object by name
+        Rs2TileObjectModel tree = cache.query().withName("Oak tree").nearest();
+
+        // Example 4: Find a tile object by multiple names
+        Rs2TileObjectModel bankObj = cache.query().withNames("Bank booth", "Bank chest", "Bank").nearest();
+
+        // Example 5: Find a tile object by ID
+        Rs2TileObjectModel objectById = cache.query().withId(1234).nearest();
+
+        // Example 6: Find a tile object by multiple IDs
+        Rs2TileObjectModel objectByIds = cache.query().withIds(1234, 5678, 9012).nearest();
+
+        // Example 7: Get all tile objects matching a partial name
+        List<Rs2TileObjectModel> doorObjects = cache.query()
+                .where(obj -> obj.getName() != null && obj.getName().toLowerCase().contains("door"))
+                .toList();
+
+        // Example 8: Find the nearest reachable tile object
+        Rs2TileObjectModel reachableObject = cache.query()
+                .withName("Ladder")
+                .nearestReachable();
+
+        // Example 9: Find the nearest reachable tile object within 15 tiles
+        Rs2TileObjectModel nearbyReachable = cache.query()
+                .withName("Furnace")
+                .nearestReachable(15);
+
+        // Example 10: Get all tile objects as a list
+        List<Rs2TileObjectModel> allObjects = cache.query().toList();
+
+        // Example 11: Count tile objects matching criteria
+        int treeCount = cache.query()
+                .where(obj -> obj.getName() != null && obj.getName().contains("tree"))
+                .count();
+
+        // Example 12: Find the nearest bank and interact with it
+        boolean clickedBank = cache.query()
+                .withNames("Bank booth", "Bank chest", "Bank")
+                .interact("Bank");
+
+        // Example 13: Find the nearest object by name and interact with a specific action
+        boolean clickedOpen = cache.query()
+                .withName("Door")
+                .interact("Open");
+
+        // Example 14: Find objects within a specific distance and interact
+        boolean clickedChop = cache.query()
+                .withNames("Tree", "Oak tree", "Willow tree")
+                .interact("Chop down", 5);
+
+        // Example 15: Direct stream access when needed
+        Rs2TileObjectModel firstObject = cache.getStream()
+                .filter(obj -> obj.getName() != null)
+                .findFirst()
+                .orElse(null);
+    }
+}