A GroundItem represents an item lying on the ground in the game world that can be picked up.

ground_item:id() -> number

Returns the unique item ID.

Returns:

• number: The item's ID

Example:

local items = ground_items:find({name = "Coins"})
for _, item in ipairs(items) do
    logger:info("Item ID: " .. item:id())
end

---

ground_item:name() -> string

Returns the name of the item.

Returns:

• string: The item's name

Example:

local items = ground_items:find({within_distance_of_local = 10})
for _, item in ipairs(items) do
    logger:info("Found: " .. item:name())
end

---

ground_item:stack_size() -> number

Returns the stack size of the item (how many are in the pile).

Returns:

• number: The number of items in the stack

Example:

local coins = ground_items:find_first({name = "Coins"})
if coins then
    local amount = coins:stack_size()
    logger:info("Coin pile: " .. amount .. " coins")
end

---

ground_item:x() -> number

Returns the world X coordinate.

Returns:

• number: The X coordinate

---

ground_item:y() -> number

Returns the world Y coordinate.

Returns:

• number: The Y coordinate

---

ground_item:floor() -> number

Returns the floor/plane level.

Returns:

• number: The floor level (0-3)

---

ground_item:tile() -> Tile

Returns the tile position as a Tile object.

Returns:

• Tile: The tile containing x, y, and floor

Example:

local item = ground_items:find_first({name = "Logs"})
if item then
    local tile = item:tile()
    logger:info("Item at: " .. tile.x .. ", " .. tile.y .. ", floor " .. tile.floor)
end

---

ground_item:local_x() -> number

Returns the local (scene-relative) X coordinate.

Returns:

• number: The local X coordinate

---

ground_item:local_y() -> number

Returns the local (scene-relative) Y coordinate.

Returns:

• number: The local Y coordinate

---

ground_item:distance() -> number

Returns the distance from the local player to this item. This is the preferred method over distance_to_player().

Returns:

• number: The distance in tiles

Example:

local items = ground_items:find({name = "Dragon bones"})
for _, item in ipairs(items) do
    local dist = item:distance()
    logger:info("Distance: " .. dist)
end

---

Deprecated: Use distance() instead.

ground_item:distance_to_player() -> number

Returns the distance from the local player to this item.

Returns:

• number: The distance in tiles

---

ground_item:is_valid() -> boolean

Checks if the ground item is still valid (hasn't despawned).

Returns:

• boolean: True if the item is still valid

Example:

local item = ground_items:find_first({name = "Bones"})
if item and item:is_valid() then
    item:interact({action = "Take"})
end

---

ground_item:click() -> boolean

Performs a human-like left click on the item.

Returns:

• boolean: True if the click was successful

Example:

local item = ground_items:find_first({name = "Coins"})
if item then
    item:click()
end

---

ground_item:shift_click() -> boolean

Shift+click the ground item (holds shift, clicks, releases shift). Useful for shift-click actions.

Returns:

• boolean: True if the click was successful

Example:

local item = ground_items:find_first({name = "Bones"})
if item then
    item:shift_click()
end

---

ground_item:interact(filters: table?) -> boolean

Right-clicks and selects a menu option using filters.

Parameters:

• filters (table, optional): Menu item filters
  • action: Action contains text (flexible)
  • action_equals: Action matches exactly
  • action_contains: Action contains text
  • target: Target contains text (flexible)
  • target_equals: Target matches exactly
  • target_contains: Target contains text

Returns:

• boolean: True if the interaction was successful

Example:

local item = ground_items:find_first({name = "Logs"})
if item then
    -- Use exact action match
    item:interact({action_equals = "Take"})
    
    -- Or use contains (more flexible)
    item:interact({action = "Take"})
end

---

ground_item:is_visible() -> boolean

Checks if the ground item is visible in the viewport.

Returns:

• boolean: True if the item is visible on screen

Example:

local items = ground_items:find({within_distance_of_local = 15})
for _, item in ipairs(items) do
    if item:is_visible() then
        logger:info(item:name() .. " is visible")
    end
end

---

ground_item:reachable() -> boolean

Check if ground item is reachable from the local player's position using pathfinding.

Returns:

• boolean: True if the ground item can be reached from the player's current position, false otherwise

Example:

local item = ground_items:find_first({name = "Dragon bones"})
if item and item:reachable() then
    item:interact({action = "Take"})
else
    logger:warn("Item is blocked or unreachable")
end

---

ground_item:noted() -> boolean

Checks if the ground item is a noted item.

Returns:

• boolean: True if the ground item is noted, false otherwise

Example:

local note = ground_items:find_first({name = "Oak logs", noted = true})
if note and note:noted() then
    logger:info("Found noted loot: " .. note:name())
end

---

ground_item:move_mouse_to() -> boolean

Move the mouse to this ground item with human-like movement. Uses the item's clickable point.

Returns:

• boolean: True on success, false if the position is invalid or the move fails

Example:

local item = ground_items:find_first({name = "Coins"})
if item and item:move_mouse_to() then
    mouse:click()
end

---

ground_item:track() -> ()

Start tracking this ground item: the mouse follows the item until the entity is invalid, another mouse action is performed, or you call mouse:stop_track().

Example:

local item = ground_items:find_first({name = "Dragon bones"})
if item then
    item:track()
    sleep(2000)
    mouse:stop_track()
end

---

local function loot_nearby_items(item_names, max_distance)
    for _, name in ipairs(item_names) do
        local items = ground_items:find({
            name = name,
            within_distance_of_local = max_distance
        })
        
        for _, item in ipairs(items) do
            if item:is_valid() and not inventory:full() then
                if item:interact({action = "Take"}) then
                    logger:info("Looted: " .. item:name())
                    sleep(600)
                end
            end
        end
    end
end

-- Loot valuable items
loot_nearby_items({"Dragon bones", "Rune scimitar", "Coins"}, 10)

---

local valuable_items = {
    ["Dragon bones"] = 3000,
    ["Ranarr seed"] = 50000,
    ["Rune platelegs"] = 38000,
    ["Coins"] = 1  -- Per coin
}

local function loot_if_valuable(min_value)
    local items = ground_items:find({within_distance_of_local = 10})
    
    for _, item in ipairs(items) do
        local name = item:name()
        local value = valuable_items[name]
        
        if value then
            local total_value = value * item:stack_size()
            
            if total_value >= min_value then
                logger:info("Looting " .. name .. " (value: " .. total_value .. ")")
                item:interact({action = "Take"})
                sleep(800)
            end
        end
    end
end

loot_if_valuable(10000)  -- Only loot items worth 10k+

---

local function loot_nearest_first(item_name, count)
    local items = ground_items:find({name = item_name})
    
    -- Sort by distance
    table.sort(items, function(a, b)
        return a:distance_to_player() < b:distance_to_player()
    end)
    
    local looted = 0
    for _, item in ipairs(items) do
        if looted >= count then break end
        
        if item:is_valid() then
            if item:interact({action = "Take"}) then
                looted = looted + 1
                sleep(600)
            end
        end
    end
    
    return looted
end

local picked_up = loot_nearest_first("Bones", 5)
logger:info("Picked up " .. picked_up .. " bones")

---

local function should_loot_item(item)
    -- Don't loot if inventory is full
    if inventory:full() then
        return false
    end
    
    -- Don't loot if too far
    if item:distance_to_player() > 7 then
        return false
    end
    
    -- Don't loot if not visible and far
    if not item:is_visible() and item:distance_to_player() > 3 then
        return false
    end
    
    return true
end

local items = ground_items:find({within_distance_of_local = 10})
for _, item in ipairs(items) do
    if should_loot_item(item) then
        item:interact({action = "Take"})
        sleep(600)
    end
end

---

-- Only pick up coin piles above a certain amount
local min_coins = 100

local coins = ground_items:find({name = "Coins"})
for _, coin_pile in ipairs(coins) do
    if coin_pile:stack_size() >= min_coins then
        logger:info("Picking up " .. coin_pile:stack_size() .. " coins")
        coin_pile:interact({action = "Take"})
        sleep(600)
    end
end

---

local loot_area = Area.new(
    Tile.new(3200, 3200, 0),
    Tile.new(3210, 3210, 0)
)

local function loot_in_area(area, item_names)
    local items = ground_items:find({within_distance_of_local = 15})
    
    for _, item in ipairs(items) do
        if area:contains_tile(item:tile()) then
            for _, target_name in ipairs(item_names) do
                if item:name() == target_name then
                    item:interact({action = "Take"})
                    sleep(600)
                    break
                end
            end
        end
    end
end

loot_in_area(loot_area, {"Dragon bones", "Dragon scales"})

---

Ground items are typically found using the ground_items API module:

-- Find all items by name
local bones = ground_items:find({name = "Bones"})

-- Find first item
local coin_pile = ground_items:find_first({name = "Coins"})

-- Find within distance
local nearby = ground_items:find({within_distance_of_local = 5})

-- Combine filters
local valuable = ground_items:find({
    name = "Dragon bones",
    within_distance_of_local = 10
})

• Item - Inventory items
• Tile - Position in game world
• Area - Rectangular regions