API Overview

Complete documentation for all Lua API modules available in the pow-desktop scripting engine.

Quick Navigation

Entity & Interaction APIs

• Players - Query and interact with players
• NPCs - Find and interact with NPCs
• Game Objects - Find and interact with game objects
• Ground Items - Find and loot ground items

Inventory & Equipment APIs

• Inventory - Access inventory items
• Bank - Banking operations
• Grand Exchange - Grand Exchange trading and offer management
• Equipment - Equipped items management
• Loadout - Declarative loadout management with auto-acquisition
• ItemDefinitions - Static item data from game cache

Character & Stats APIs

• Skills - Skill levels and experience
• Combat - Combat stats and abilities
• Prayer - Prayer activation and management

Input & Navigation APIs

• Mouse - Mouse movement and clicking
• Keyboard - Keyboard input simulation
• Movement - Player movement and walking
• Camera - Camera control

UI & Interaction APIs

• Menu - Right-click context menus
• Chat - Chat and dialogue handling
• Components - UI component interaction
• Magic - Magic spell casting and management
• POH - Player Owned House features (Portal Nexus, Fairy Ring, stat restoration)

Game State APIs

• Game - Game client state
• Worlds - World/server information

Utility & Debug APIs

• Logger - Logging messages
• Paint - On-screen overlays
• Stats - Script statistics tracking

---

Common Patterns

Finding and Interacting with Entities

All entity APIs (Players, NPCs, Game Objects, Ground Items) use a similar pattern:

-- Find first matching
local entity = npcs:find_first({name = "Banker"})

-- Find all matching
local all = npcs:find_all({within_distance_of_local = 10})

-- Find nearest
local nearest = npcs:find_nearest()

-- Interact
entity:smart_interact({action = "Bank"})

---

Checking Player State

local player = players:local_player()

if player then
    -- Position
    local tile = player:tile()

    -- Activity
    if player:is_moving() then
        -- Player moving
    end

    -- Combat
    if combat:is_low_health(30) then
        -- Low health
    end
end

---

Inventory Management

-- Check status
if inventory:full() then
    logger:warn("Inventory full")
end

-- Find items
local potions = inventory:find_all({name_contains = "potion"})

-- Count items
local coins = inventory:count_of(995)

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

---

Input Simulation

-- Mouse
mouse:move_to(300, 250)
mouse:left_click(300, 250)
mouse:right_click(300, 250)

-- Keyboard
keyboard:type_text("Hello")
keyboard:press_enter()
keyboard:key_press(27)  -- Escape

-- Combine
mouse:right_click(300, 250)
sleep(300)
keyboard:key_press(13)  -- Select option

---

Logging and Debugging

-- Different levels
logger:info("Normal information")
logger:warn("Something might be wrong")
logger:error("Something is definitely wrong")
logger:debug("Debugging information")

-- With values
logger:info("Health: " .. combat:current_health())
logger:warn("Items found: " .. #items)

---

Type System

Each API module works with specific types. Type documentation is included within each API module's documentation.

---

Best Practices

Always Check for Nil

local npc = npcs:find_first({name = "Banker"})
if npc then
    npc:smart_interact({action = "Bank"})
else
    logger:warn("Banker not found")
end

Use Filters Efficiently

-- Good: Single query with multiple filters
local npcs = npcs:find_all({
    name = "Guard",
    within_distance_of_local = 20,
    not_in_combat = true
})

-- Bad: Multiple queries
local npcs = npcs:find_all({name = "Guard"})
-- ... filter manually

Handle Timeouts

local start = os.time()
while condition_not_met() and os.time() - start < 30 do
    sleep(100)
end

if os.time() - start >= 30 then
    logger:warn("Timeout!")
end

Use Smart Interact

-- Preferred: Handles visibility, distance, camera
npc:smart_interact({action = "Talk-to"})

-- Only use regular interact if smart_interact not available
npc:interact({action = "Talk-to"})

---

Error Handling

Most API functions return false or nil on failure:

if not movement:walk_to(tile) then
    logger:error("Failed to walk")
    return
end

local item = inventory:find_first({name = "Food"})
if not item then
    logger:warn("Food not found")
    return
end

---

Performance Tips

1. Cache results when possible

   local player = players:local_player()
   -- Reuse player variable
   

2. Use appropriate find method

   find_first()    -- When you only need one
   find_nearest()  -- When distance matters
   find_all()      -- Only when you need all
   

3. Combine filters rather than filtering results manually

   npcs:find_all({
       name = "Guard",
       within_distance_of_local = 20
   })
   

4. Avoid repeated queries in loops

   local nearby = npcs:find_all({within_distance_of_local = 20})
   for _, npc in ipairs(nearby) do
       -- Process npc
   end
   

---

Related Resources

• Lua Reference - Lua language reference