Inventory API

Access and manage player inventory items and inventory state.

Functions

items

inventory:items() -> table

Returns all items currently in inventory.

Returns:

• table - Array of Item objects

Example:

local all_items = inventory:items()
logger:info("Inventory slots: " .. #all_items)

for _, item in ipairs(all_items) do
    logger:info(item:name() .. " x" .. item:stack_size())
end

---

item_count

inventory:item_count() -> number

Returns the number of non-empty inventory slots.

Returns:

• number - Count of items in inventory

---

full

inventory:full() -> boolean

Checks if inventory is full (28 slots occupied).

Returns:

• boolean - True if inventory has 28 items

---

empty

inventory:empty() -> boolean

Checks if inventory is empty.

Returns:

• boolean - True if inventory has no items

---

empty_slot_count

inventory:empty_slot_count() -> number

Returns the number of empty inventory slots.

Returns:

• number - Count of empty slots (0-28)

Example:

local free_slots = inventory:empty_slot_count()
logger:info("Free slots: " .. free_slots)

if free_slots < 5 then
    logger:warn("Running low on inventory space!")
end

---

contains

inventory:contains(item_id: number) -> boolean
inventory:count_of(item_id: number) -> number

Check for an item ID and return total count across stacks.

Parameters:

Parameter	Type	Required	Description
item_id	number	Yes	The item ID to check/count

Returns:

• boolean (contains) / number (count_of)

---

opened

inventory:opened() -> boolean

Checks if the inventory tab is open.

Returns:

• boolean - True if inventory is visible

---

find_first

inventory:find_first(filter: table?) -> Item?

Finds the first item matching the filter.

Parameters:

Parameter	Type	Required	Description
filter	table	No	Filter options

Returns:

• Item? - First matching item, or nil

Filters:

Filter	Type	Description
id	number	Exact item ID
name	string	Exact name match
name_contains	string	Name contains text
name_any	table	Match if name equals any in array of strings
name_contains_any	table	Match if name contains any substring in array
slot	number	Exact slot index
slot_range	table	Slot range {min, max}
min_stack	number	Minimum stack size
max_stack	number	Maximum stack size
charges_eq	number	Charges exactly equal to value
charges_gt / charges_gte	number	Charges greater than (or ≥) value
charges_lt / charges_lte	number	Charges less than (or ≤) value
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

inventory:find_all(filter: table?) -> table

Finds all items matching the filter.

Parameters:

Parameter	Type	Required	Description
filter	table	No	Filter options (same as find_first)

Returns:

• table - Array of matching Item objects

Example:

local potions = inventory:find_all({name_contains = "potion"})
logger:info("Potions: " .. #potions)

local stackables = inventory:find_all({min_stack = 2})
logger:info("Stackable items: " .. #stackables)

-- Find items with any of multiple names
local food = inventory:find_first({
    name_any = {"Lobster", "Swordfish", "Shark"}
})

-- Find items containing any substring
local combat_items = inventory:find_all({
    name_contains_any = {"potion", "food", "rune"}
})

-- Find valuable items by price
local valuable_items = inventory:find_all({
    min_high_price_total = 5000,
    has_high_price = true
})

-- Find cheap items for dropping
local junk_items = inventory:find_all({
    max_store_price = 100
})

---

count

inventory:count(filter: table?) -> number

Counts items matching the filter.

Parameters:

Parameter	Type	Required	Description
filter	table	No	Filter options (same as find_first)

Returns:

• number - Count of matching items

---

drop_all

inventory:drop_all(filter: table?) -> boolean

Drops all items matching the filter.

Parameters:

Parameter	Type	Required	Description
filter	table	No	Filter options

Returns:

• boolean - True if successful

Example:

-- Drop all junk items
inventory:drop_all({name_contains = "junk"})

-- Drop low-value items
local junks = {"Bones", "Ashes"}
for _, junk in ipairs(junks) do
    inventory:drop_all({name = junk})
end

---

drop_all_except

inventory:drop_all_except(filter: table?) -> boolean

Drops all items EXCEPT those matching the filter.

Parameters:

Parameter	Type	Required	Description
filter	table	No	Keep items matching this filter

Returns:

• boolean - True if successful

Example:

-- Keep only food, drop everything else
inventory:drop_all_except({name_contains = "bread"})

---

selected

inventory:selected() -> Item?

Returns the currently selected inventory item (after clicking "Use"), or nil.

Example:

local selected = inventory:selected()
if selected then
    logger:info("Selected: " .. selected:name())
end

---

shift_click

inventory:shift_click(filter: table?) -> boolean

Shift-click items matching the provided filter. Useful for mass dropping.

---

Common Patterns

Inventory Management

local function manage_inventory()
    if inventory:full() then
        logger:info("Inventory full! Dropping junk...")
        inventory:drop_all({name_contains = "junk"})
    else
        logger:info("Inventory has " .. inventory:item_count() .. " items")
    end
end

---

Drinking Potions

local function drink_potion(potion_name)
    local potion = inventory:find_first({name_contains = potion_name})
    
    if potion then
        logger:info("Drinking " .. potion:name())
        return potion:click()
    end
    
    logger:warn("Potion not found: " .. potion_name)
    return false
end

drink_potion("Super Restore")

---

Checking Resources

local function check_resources()
    logger:info("=== Inventory ===")
    logger:info("Items: " .. inventory:item_count() .. "/28")
    logger:info("Coins: " .. inventory:count_of(995))
    logger:info("Food: " .. inventory:count({name_contains = "bread"}))
    logger:info("Potions: " .. inventory:count({name_contains = "potion"}))
end

check_resources()

---

Dropping While Gathering

local function drop_lowest_priority_items(keep_names)
    if inventory:full() then
        local all_items = inventory:items()
        
        for _, item in ipairs(all_items) do
            local should_keep = false
            for _, keep_name in ipairs(keep_names) do
                if item:name():find(keep_name) then
                    should_keep = true
                    break
                end
            end
            
            if not should_keep then
                logger:info("Dropping: " .. item:name())
                item:click()
                break
            end
        end
    end
end

drop_lowest_priority_items({"ore", "log"})

---

Quick Use Pattern

local function use_item_on_target(item_name, target)
    local item = inventory:find_first({name_contains = item_name})
    
    if not item then
        logger:warn("Item not found: " .. item_name)
        return false
    end
    
    -- Click item first
    item:click()
    sleep(100)
    
    -- Click target
    return target:click()
end

---

Item Methods

Each Item object has methods to access properties:

• Basic Info

  • id() → number
  • name() → string
  • stack_size() → number

• Interaction

  • click() → boolean
  • interact(action) → boolean

See the methods listed above for complete Item functionality.

---

Related APIs

• Bank API - Bank management
• Equipment API - Equipment slots