Item Definitions API

Category: API Reference

Access static item definitions from the game cache. This allows looking up item properties like name, cost, members status, without needing the item in inventory or bank.

Functions

get

item_definitions:get(item_id: number) -> ItemDefinition?

Look up a single item definition by ID.

Parameters:

Parameter	Type	Required	Description
`item_id`	number	Yes	The item ID to look up

Returns:

ItemDefinition? - The item definition, or nil if not found

Example:

local def = item_definitions:get(4151)  -- Abyssal whip
if def then
    logger:info("Item: " .. def:name())
    logger:info("Cost: " .. def:cost())
    logger:info("Members: " .. tostring(def:members()))
end

find_first

item_definitions:find_first(filter: table?) -> ItemDefinition?

Find the first item definition matching the filter.

Parameters:

Parameter	Type	Required	Description
`filter`	table	No	Filter options

Returns:

ItemDefinition? - First matching item definition, or nil

Filters:

Filter	Type	Description
`id`	number	Exact item ID
`ids`	table	Array of item IDs to match
`name`	string	Exact name match
`name_contains`	string	Name contains text
`name_any`	table	Match if name equals any in array
`name_contains_any`	table	Match if name contains any substring

Example:

local whip = item_definitions:find_first({name = "Abyssal whip"})
if whip then
    logger:info("Found: " .. whip:name() .. " (ID: " .. whip:id() .. ")")
end

find_all

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

Find all item definitions matching the filter.

Parameters:

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

Returns:

table - Array of matching ItemDefinition objects

Example:

-- Find all dragon items
local dragon_items = item_definitions:find_all({name_contains = "Dragon"})
logger:info("Found " .. #dragon_items .. " dragon items")

for _, item in ipairs(dragon_items) do
    logger:info(item:name() .. " - " .. item:cost() .. " gp")
end

-- Find specific items by name
local potions = item_definitions:find_all({
    name_contains_any = {"Super restore", "Prayer potion", "Saradomin brew"}
})

count

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

Count item definitions matching the filter.

Parameters:

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

Returns:

number - Count of matching item definitions

Example:

local members_items = item_definitions:count({members = true})
logger:info("Members items: " .. members_items)

contains

item_definitions:contains(filter: table?) -> boolean

Check if any item definition matches the filter.

Parameters:

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

Returns:

boolean - True if at least one item matches

Example:

if item_definitions:contains({name = "Twisted bow"}) then
    logger:info("Twisted bow exists in the game!")
end

ItemDefinition Methods

Each ItemDefinition object has methods to access item properties:

Basic Info

Method	Returns	Description
`id()`	number	Item ID
`name()`	string	Item name
`examine()`	string	Examine text
`cost()`	number	Base cost/value
`category()`	number	Item category (-1 if none)
`team()`	number	Team cape number
`model_id()`	number	Inventory model ID

Flags

Method	Returns	Description
`stackable()`	boolean	Is item stackable
`members()`	boolean	Is members-only
`tradeable()`	boolean	Is tradeable
`noted()`	boolean	Is this a noted form
`equipable()`	boolean	Can be equipped
`cosmetic()`	boolean	Is cosmetic item

Related Items

Method	Returns	Description
`noted_id()`	number	Noted variant ID (-1 if none)
`placeholder_id()`	number	Placeholder ID (-1 if none)

Equipment

Method	Returns	Description
`wear_pos_1()`	number	Primary equipment slot (-1 if not equipable)
`wear_pos_2()`	number	Secondary slot (-1 if none)
`wear_pos_3()`	number	Tertiary slot (-1 if none)

Actions

Method	Returns	Description
`actions()`	table	Inventory/interface actions
`ground_actions()`	table	Ground/floor actions

Common Patterns

Looking Up Item Info

local function get_item_info(item_id)
    local def = item_definitions:get(item_id)
    if not def then
        logger:warn("Item not found: " .. item_id)
        return
    end
    
    logger:info("=== " .. def:name() .. " ===")
    logger:info("ID: " .. def:id())
    logger:info("Cost: " .. def:cost() .. " gp")
    logger:info("Members: " .. tostring(def:members()))
    logger:info("Tradeable: " .. tostring(def:tradeable()))
    logger:info("Stackable: " .. tostring(def:stackable()))
    
    if def:equipable() then
        logger:info("Equipment slot: " .. def:wear_pos_1())
    end
end

get_item_info(4151)  -- Abyssal whip

Finding Items by Name Pattern

-- Find all rune items
local rune_items = item_definitions:find_all({name_contains = "Rune "})
for _, item in ipairs(rune_items) do
    if item:equipable() then
        logger:info(item:name() .. " (equipable)")
    end
end

Checking Item Properties

local function is_food(item_id)
    local def = item_definitions:get(item_id)
    if not def then return false end
    
    local actions = def:actions()
    for _, action in ipairs(actions) do
        if action == "Eat" then
            return true
        end
    end
    return false
end

if is_food(379) then  -- Lobster
    logger:info("Lobster is food!")
end

Finding Tradeable Equipment

local function find_tradeable_weapons()
    local weapons = item_definitions:find_all({name_contains = "sword"})
    local tradeable = {}
    
    for _, item in ipairs(weapons) do
        if item:tradeable() and item:equipable() then
            table.insert(tradeable, item)
        end
    end
    
    return tradeable
end

Performance Notes

find_all() without filters iterates through ~30,000 items and can be slow
Always use filters when possible to narrow results
get() by ID is fast and preferred when you know the item ID
Results are not cached; repeated queries will re-scan the cache

Related APIs

Inventory API - Access inventory items
Bank API - Bank management
Equipment API - Equipment slots