Filters Guide

A comprehensive guide to using filters in the PowBot Desktop Lua API for querying and filtering game entities.

Filter Pattern Overview

PowBot uses a consistent filter pattern across all APIs. Filters are Lua tables that specify search criteria for finding game entities.

The Basic Pattern

Most find methods accept an optional filter table:

-- General pattern
api:find_all(filter)      -- Find all matching entities
api:find_first(filter)    -- Find first matching entity
api:find_nearest(filter)  -- Find nearest matching entity

Common Filter Fields

Name Filters

-- Exact name match
{ name = "Banker" }

-- Name contains text
{ name_contains = "Bank" }

-- Name matches regex
{ name_matches_regex = "^Bank.*" }

-- Match any of multiple names
{ name_any = {"Banker", "Bank booth", "Bank chest"} }

Distance Filters

-- Within distance of local player
{ within_distance_of_local = 10.0 }

-- Within distance of specific position
{ within_distance_of = {x, y, floor, max_distance} }

-- At exact tile location
{ at = {x = 3200, y = 3210, floor = 0} }

State Filters

-- Combat state
{ not_in_combat = true }
{ in_combat = true }

-- Animation state
{ is_animating = true }
{ not_animating = true }

-- Movement state
{ is_moving = true }
{ not_moving = true }

API-Specific Filters

NPC Filters

npcs:find_all({
    name = "Cow",
    not_in_combat = true,
    within_distance_of_local = 15.0
})

Game Object Filters

game_objects:find_all({
    name_contains = "Copper",
    within_distance_of_local = 10.0,
    not_interacting = true
})

Ground Item Filters

ground_items:find_all({
    name = "Cowhide",
    within_distance_of_local = 5.0
})

Inventory Filters

inventory:find_all({
    name = "Iron ore",
    id = 440  -- Item ID
})

Filter Combinations

You can combine multiple filters:

local npcs = npcs:find_all({
    name_contains = "Guard",
    within_distance_of_local = 20,
    not_in_combat = true,
    is_moving = false
})

Performance Tips

1. Use Specific Filters: More specific filters are faster
2. Use find_first When Possible: Faster than find_all if you only need one result
3. Cache Results: Store results if you'll use them multiple times
4. Combine Filters: Use API filters rather than manual filtering

Common Patterns

Find Nearest Entity

local nearest = npcs:find_nearest({
    name = "Banker",
    within_distance_of_local = 10.0
})

Find All in Area

local items = ground_items:find_all({
    within_distance_of = {x, y, floor, max_distance}
})

Filter by Multiple Names

local npcs = npcs:find_all({
    name_any = {"Cow", "Chicken", "Sheep"}
})

For complete filter documentation, see the API Reference section.

---