Components API

Category: API Reference

The components API provides access to UI widgets and interface elements in the game. Components can be buttons, text labels, inventory slots, dialog boxes, or any other UI element.

Overview

Components are organized hierarchically:

Group ID (Widget ID): Top-level interface (e.g., 149 for inventory)
Component ID: Specific component within the group (e.g., 0 for inventory container)
Child ID: Optional child components (e.g., individual inventory slots)

Methods

get

components:get(group_id: number, component_id: number, child_id: number?) -> Component?

Gets a component by its group ID and component ID. Optionally accepts a child ID to retrieve nested child components.

Parameters:

Parameter	Type	Required	Description
`group_id`	number	Yes	The interface group/widget ID
`component_id`	number	Yes	The component ID within the group
`child_id`	number	No	The child component ID for nested components

Returns:

Component?: The component, or nil if not found

Example:

-- Get parent component (inventory container)
local inventory = components:get(149, 0)
if inventory and inventory:visible() then
    logger:info("Inventory is visible")
end

-- Get child component (first inventory slot) with optional 3rd parameter
local first_slot = components:get(149, 0, 0)
if first_slot then
    local item_id = first_slot:item_id()
    if item_id ~= -1 then
        logger:info("First slot contains item: " .. item_id)
    end
end

-- Get specific inventory slot
local slot_5 = components:get(149, 0, 5)
if slot_5 then
    logger:info("Slot 5 item: " .. slot_5:item_id())
end

-- Get bank container
local bank = components:get(12, 2)
if bank and bank:visible() then
    logger:info("Bank is open")
end

Alternative: You can also use the component:child() method to navigate from a parent component to its children:

local inventory = components:get(149, 0)
if inventory then
    local first_slot = inventory:child(0)
end

find_first

components:find_first(filter: table?) -> Component?

Finds the first component matching the specified filters.

Parameters:

Parameter	Type	Required	Description
`filter`	table	No	Filter options (see Filter Options below)

Returns:

Component?: The first matching component, or nil if none found

Example:

-- Find continue button by text
local continue = components:find_first({
    text_contains = "Click here to continue"
})

-- Find visible components in a group
local dialog = components:find_first({
    group_id = 231,
    visible_only = true
})

-- Find component by action
local drop_slot = components:find_first({
    group_id = 149,
    actions_contains = "Drop"
})

find_all

components:find_all(filter: table?) -> Component[]

Finds all components matching the specified filters.

Parameters:

Parameter	Type	Required	Description
`filter`	table	No	Filter options (see Filter Options below)

Returns:

Component[]: Array of matching components (empty if none found)

Example:

-- Find all visible inventory slots
local visible_slots = components:find_all({
    group_id = 149,
    visible_only = true
})

-- Filter to only slots with items
local items = {}
for _, slot in ipairs(visible_slots) do
    if slot:item_id() ~= -1 then
        table.insert(items, slot)
    end
end

logger:info("Found " .. #items .. " items in inventory")

Filter Options

The find_first and find_all methods accept a filter table with the following options:

Option	Type	Description
`text_contains`	string	Component text contains this string (case-insensitive)
`text_equals`	string	Component text exactly matches this string (case-insensitive)
`visible_only`	boolean	Only return visible components
`group_id`	number	Filter by specific group/widget ID
`content_type`	number	Filter by content type (0=graphic, 1=text, 2=filled box, etc.)
`min_width`	number	Minimum width in pixels
`min_height`	number	Minimum height in pixels
`parent_id`	number	Filter by parent component ID
`with_text`	boolean	Only components that have non-empty text
`actions_contains`	string	Component actions contain this string
`actions_equals`	string	Component actions exactly match this string

Example:

-- Find large visible buttons with text
local buttons = components:find_all({
    visible_only = true,
    with_text = true,
    min_width = 50,
    min_height = 20,
    content_type = 2  -- Filled box
})

-- Find specific dialog option
local option = components:find_first({
    group_id = 219,
    text_contains = "Yes",
    visible_only = true
})

Common Component Groups

Here are some commonly used component group IDs:

Group ID	Interface	Description
149	Inventory	Player inventory (28 slots)
12	Bank	Bank interface
162	Chatbox	Chat messages and input
231	Dialog	NPC dialogs and continue buttons
387	Equipment	Worn equipment
218	Spellbook	Magic spellbook
593	Grand Exchange	GE interface
219	Dialog Options	Multiple choice dialog options
465	Bank Inventory	Inventory shown when bank is open

Common Patterns

Checking if Interface is Open

local function is_bank_open()
    local bank = components:get(12, 2)
    return bank and bank:visible()
end

local function is_inventory_open()
    local inventory = components:get(149, 0)
    return inventory and inventory:visible()
end

if is_bank_open() then
    logger:info("Bank is open")
end

Getting All Inventory Slots

local function get_all_inventory_slots()
    local slots = {}
    for i = 0, 27 do
        local slot = components:get(149, 0, i)
        if slot then
            table.insert(slots, slot)
        end
    end
    return slots
end

local slots = get_all_inventory_slots()
logger:info("Found " .. #slots .. " inventory slots")

Finding Items in Inventory

local function find_item_in_inventory(item_id)
    for i = 0, 27 do
        local slot = components:get(149, 0, i)
        if slot and slot:item_id() == item_id then
            return slot, i
        end
    end
    return nil, -1
end

-- Find coins (item ID 995)
local coin_slot, index = find_item_in_inventory(995)
if coin_slot then
    local amount = coin_slot:item_stack_size()
    logger:info("Found " .. amount .. " coins in slot " .. index)
end

Clicking Dialog Buttons

local function click_continue()
    local continue = components:find_first({
        text_contains = "Click here to continue",
        visible_only = true
    })
    
    if continue then
        continue:click()
        return true
    end
    return false
end

local function select_dialog_option(text)
    local option = components:find_first({
        group_id = 219,
        text_contains = text,
        visible_only = true
    })
    
    if option then
        option:click()
        return true
    end
    return false
end

-- Use in script
if click_continue() then
    logger:info("Clicked continue")
end

if select_dialog_option("Yes") then
    logger:info("Selected 'Yes' option")
end

Waiting for Component to Appear

local function wait_for_component(group_id, component_id, timeout)
    local start = os.time()
    
    while os.time() - start < timeout do
        local comp = components:get(group_id, component_id)
        if comp and comp:is_valid() and comp:visible() then
            return comp
        end
        sleep(100)
    end
    
    return nil
end

-- Wait up to 5 seconds for bank to open
local bank = wait_for_component(12, 2, 5)
if bank then
    logger:info("Bank opened!")
else
    logger:warn("Bank did not open within 5 seconds")
end

Reading Component Text

local function get_dialog_text()
    -- Try common dialog component IDs
    local dialog_ids = {
        {231, 5},
        {217, 5},
        {231, 6}
    }
    
    for _, ids in ipairs(dialog_ids) do
        local comp = components:get(ids[1], ids[2])
        if comp and comp:visible() then
            local text = comp:text()
            if text and text ~= "" then
                return text
            end
        end
    end
    
    return nil
end

local text = get_dialog_text()
if text then
    logger:info("NPC says: " .. text)
end

Interacting with Component Actions

local function drop_item_in_slot(slot_index)
    local slot = components:get(149, 0, slot_index)
    if slot and slot:item_id() ~= -1 then
        -- Use interact to right-click and select "Drop"
        return slot:interact("Drop")
    end
    return false
end

-- Drop items in slots 0-5
for i = 0, 5 do
    if drop_item_in_slot(i) then
        logger:info("Dropped item in slot " .. i)
        sleep(100)
    end
end

Checking Component Bounds

local function is_point_in_component(comp, x, y)
    if not comp or not comp:is_valid() then
        return false
    end
    
    local cx = comp:x()
    local cy = comp:y()
    local cw = comp:width()
    local ch = comp:height()
    
    return x >= cx and x <= cx + cw and
           y >= cy and y <= cy + ch
end

-- Check if mouse is over inventory
local inventory = components:get(149, 0)
if inventory then
    local mouse_x, mouse_y = mouse:position()
    if is_point_in_component(inventory, mouse_x, mouse_y) then
        logger:info("Mouse is over inventory")
    end
end

Finding Empty Inventory Slots

local function count_empty_slots()
    local empty = 0
    for i = 0, 27 do
        local slot = components:get(149, 0, i)
        if slot and slot:item_id() == -1 then
            empty = empty + 1
        end
    end
    return empty
end

local function find_first_empty_slot()
    for i = 0, 27 do
        local slot = components:get(149, 0, i)
        if slot and slot:item_id() == -1 then
            return slot, i
        end
    end
    return nil, -1
end

local empty_count = count_empty_slots()
logger:info("Inventory has " .. empty_count .. " empty slots")

local empty_slot, index = find_first_empty_slot()
if empty_slot then
    logger:info("First empty slot is at index " .. index)
end

Advanced Examples

Smart Component Search

local function find_clickable_button(text_hint)
    -- Find buttons that are visible, have reasonable size, and contain text
    local buttons = components:find_all({
        visible_only = true,
        with_text = true,
        min_width = 30,
        min_height = 15
    })
    
    -- Filter by text hint if provided
    if text_hint then
        for _, button in ipairs(buttons) do
            local text = button:text()
            if text and text:lower():find(text_hint:lower()) then
                return button
            end
        end
    end
    
    return buttons[1]
end

local button = find_clickable_button("Accept")
if button then
    button:click()
end

Component State Monitoring

local function monitor_component_text(group_id, component_id, callback, interval)
    local last_text = ""
    
    while true do
        local comp = components:get(group_id, component_id)
        if comp and comp:visible() then
            local current_text = comp:text()
            if current_text ~= last_text then
                callback(current_text, last_text)
                last_text = current_text
            end
        end
        sleep(interval or 100)
    end
end

-- Example usage
monitor_component_text(231, 5, function(new_text, old_text)
    logger:info("Dialog text changed from '" .. old_text .. "' to '" .. new_text .. "'")
end, 200)

Component Content Types

Component content types determine how the component is rendered:

Value	Type	Description
0	GRAPHIC	Image/sprite
1	TEXT	Text label
2	FILLED_BOX	Solid rectangle
3	MODEL	3D model
4	TEXT_INPUT	Text input field
5	CONTAINER	Container for other components
6	MODEL_LIST	List of 3D models
9	LINE	Line separator

Example:

local function find_text_components()
    return components:find_all({
        content_type = 1,  -- TEXT
        visible_only = true
    })
end

local text_comps = find_text_components()
for _, comp in ipairs(text_comps) do
    logger:info("Text: " .. comp:text())
end

Best Practices

Always Validate Components

-- Bad
local comp = components:get(149, 0)
comp:click()  -- May error if comp is nil

-- Good
local comp = components:get(149, 0)
if comp and comp:is_valid() and comp:visible() then
    comp:click()
else
    logger:warn("Component not available")
end

Use Appropriate Access Methods

-- For parent components - use get()
local inventory = components:get(149, 0)

-- For child components - use get_child()
local first_slot = components:get_child(149, 0, 0)

-- Or navigate from parent to child
local inventory = components:get(149, 0)
if inventory then
    local first_slot = inventory:child(0)
end

Cache Component Lookups

-- Bad: Repeated lookups
for i = 1, 10 do
    local comp = components:get(149, 0)
    if comp:visible() then
        -- Do something
    end
    sleep(100)
end

-- Good: Cache the lookup
local comp = components:get(149, 0)
for i = 1, 10 do
    if comp and comp:is_valid() and comp:visible() then
        -- Do something
    end
    sleep(100)
end

Use Filters Efficiently

-- Bad: Get all then filter manually
local all = components:find_all({})
local visible = {}
for _, comp in ipairs(all) do
    if comp:visible() and comp:text() ~= "" then
        table.insert(visible, comp)
    end
end

-- Good: Use filter options
local visible = components:find_all({
    visible_only = true,
    with_text = true
})

Components API

Overview

Methods

get

find_first

find_all

Filter Options

Common Component Groups

Common Patterns

Checking if Interface is Open

Getting All Inventory Slots

Finding Items in Inventory

Clicking Dialog Buttons

Waiting for Component to Appear

Reading Component Text

Interacting with Component Actions

Checking Component Bounds

Finding Empty Inventory Slots

Advanced Examples

Smart Component Search

Component State Monitoring

Component Content Types

Best Practices

Always Validate Components

Use Appropriate Access Methods

Cache Component Lookups

Use Filters Efficiently

See Also