Ground Items API

Find and interact with items lying on the ground.

Functions

find_first

ground_items:find_first(filters: table?) -> GroundItem?

Find first ground item matching filters.

Parameters:

Parameter	Type	Required	Description
filters	table	No	Filter options

Returns:

• GroundItem? - First matching item

Filters:

Filter	Type	Description
name	string	Exact name match
name_contains	string	Name contains text
name_matches_regex	string	Name matches regex
name_any	table	Match if name equals any in array of strings
name_contains_any	table	Match if name contains any substring in array
id	number	Exact item ID
ids	table	Array of IDs
within_distance_of_local	number	Distance from player
within_distance_of	table	Distance from coordinates
at	table	Exact tile location {x, y, z} or [x, y, z]
at_any	table	Array of tiles to check {{x, y, z}, ...}
actions_contains	string	Has an action containing this text (case-insensitive)
actions_equals	string	Has an action exactly matching this text (case-insensitive)
min_store_price	number	Minimum store price (vendor value)
max_store_price	number	Maximum store price (vendor value)
min_store_price_total	number	Minimum total store price (store_price × stack_size)
max_store_price_total	number	Maximum total store price (store_price × stack_size)
min_high_price	number	Minimum high price from Grand Exchange
max_high_price	number	Maximum high price from Grand Exchange
has_high_price	boolean	Filter items that have high price data available
min_high_price_total	number	Minimum total high price (high_price × stack_size)
max_high_price_total	number	Maximum total high price (high_price × stack_size)
min_low_price	number	Minimum low price from Grand Exchange
max_low_price	number	Maximum low price from Grand Exchange
has_low_price	boolean	Filter items that have low price data available
min_low_price_total	number	Minimum total low price (low_price × stack_size)
max_low_price_total	number	Maximum total low price (low_price × stack_size)
min_average_price	number	Minimum average price (average of high and low)
max_average_price	number	Maximum average price (average of high and low)
has_average_price	boolean	Filter items that have average price data available
min_average_price_total	number	Minimum total average price (average_price × stack_size)
max_average_price_total	number	Maximum total average price (average_price × stack_size)

---

find_all

ground_items:find_all(filters: table?) -> table

Find all ground items matching filters.

Parameters:

Parameter	Type	Required	Description
filters	table	No	Filter options

Returns:

• table - Array of GroundItem objects

Example:

local bones = ground_items:find_all({name = "Bones"})
local nearby = ground_items:find_all({within_distance_of_local = 10})

-- Find item at specific tile
local item = ground_items:find_first({
    name = "Coins",
    at = {3200, 3210, 0}  -- or at = {x = 3200, y = 3210, floor = 0}
})

-- Find items with any of multiple names
local valuable = ground_items:find_first({
    name_any = {"Coins", "Dragon bones", "Rune platebody"}
})

-- Find items containing any substring
local loot = ground_items:find_all({
    name_contains_any = {"rune", "dragon", "gold"}
})

-- Find valuable ground items by price
local valuable = ground_items:find_all({
    min_high_price_total = 10000,
    has_high_price = true,
    within_distance_of_local = 15.0
})

---

find_nearest

ground_items:find_nearest(filters: table?) -> GroundItem?

Find nearest ground item matching filters.

Parameters:

Parameter	Type	Required	Description
filters	table	No	Filter options

Returns:

• GroundItem? - Nearest matching item

---

Common Patterns

Looting Items

local function loot_bones()
    local bones = ground_items:find_nearest({name = "Bones"})
    
    if bones then
        logger:info("Looting bones")
        bones:smart_interact({action = "Take"})
        return true
    end
    
    return false
end

---

Multi-Item Looting

local function loot_items(item_names, max_distance)
    local looted = 0
    
    for _, name in ipairs(item_names) do
        local items = ground_items:find_all({
            name = name,
            within_distance_of_local = max_distance
        })
        
        for _, item in ipairs(items) do
            if inventory:full() then
                logger:info("Inventory full")
                break
            end
            
            item:smart_interact({action = "Take"})
            looted = looted + 1
            sleep(600)
        end
    end
    
    return looted
end

local count = loot_items({"Bones", "Dragon bones"}, 10)
logger:info("Looted " .. count .. " items")

---

Related APIs

• Inventory API - Inventory management