Bot Function Documentation

Mandatory Functions Movement & Navigation Combat & Skills Inventory & Items UI & Interface Global Variables Utility Functions Overwritable Functions Timer Functions

Mandatory Functions

handle_equip_change_before()
Called before equipment changes are processed. This function is mandatory to implement in your bot script. You should handle here any logic that needs to be executed before equipment changes take place.
Example implementation: 
function handle_equip_change_before()
    if get_waypoint_mode()~=0 then
        return true --do not change amulet/rings if is not in hunt mode
    end 
    return false          
end
handle_new_status(newstatus)
Called after status changes. You should handle here any logic that needs to be executed after the status changes take place, newstatus can be: "Idle", "Attacking", "Walking".
Example implementation: 
function handle_new_status(status)
    if status == "Idle"
        send_keyboard("KEY_F1")
    end
    return false          
end
main_handle()
Main handling function that's called regularly.
Example implementation: 
function main_handle()
    local xbl, ybl = last_battlelist_position()
    if xbl == 0 or ybl == 0 then
        return false -- if there is no battlelist, returns false to skip execution
    end  
        return false -- returns false to work normal
end
wpt_before() and wpt_after()
Called before clicking on each waypoint. / Called after reaching the waypoint
Example implementation: 
function wpt_before()
    return false
end
    
function wpt_after()
    return false
end
Returns: boolean - true to skip waypoint action, false to proceed

Movement & Navigation

goto_refill(value)
Forces the bot to enter refill mode and return to town.
Parameters:
• value: boolean - Whether to force refill mode
Returns: void
get_walk_mode() / set_walk_mode(value)
Forces the bot to change its walk mode, values can be:
  • WALK_MODE_KEYBOARD = 0
  • WALK_MODE_MAPCLICK = 1
  • WALK_MODE_WINDOWCLICK = 2
Parameters:
• value: number - The walk mode to set
Returns: void
try_go_to_wpt(mode,index)
Bot will try to go to the specified waypoint index in the given mode: Mode can be:
  • 0 - Hunt Mode
  • 1 - Refill Mode
  • 2 - To Hunt Mode
  • 3 - To Logout Mode
  • 4 - Login To Go Hunt Mode
Parameters:
• mode: number - The mode to use for navigation (0-4)
• index: number - The waypoint index to navigate to
Returns: void
get_waypoint_index() / set_waypoint_index(x)
Get or set the current waypoint index.
Parameters for set:
• x: number - The index to set as current waypoint
Returns for get: number - Current waypoint index
get_waypoint_mode() / set_waypoint_mode(x)
Get or set current waypoint mode.
Parameters for set:
• x: number - The mode to set (0: hunt, 1: refill, 2: to-hunt, 3: to-logout)
Returns for get: number - Current mode (0-3)
current_wpt()
Gets information about the current waypoint, including its position, dimensions, and various action properties.
Returns: table with the following fields:

Required fields:
• x, y, z: number - Waypoint coordinates
• vX, vY, vZ: number - Waypoint vectors
• vL, vR, vT, vB: number - Waypoint boundaries (Left, Right, Top, Bottom)
• radius: number - Waypoint radius
• minimumWaitTime: number - Minimum time to wait at waypoint
• luafunc: string - Lua function associated with waypoint

Optional fields:
• title: string - Waypoint title/description
• pausebot: boolean - Whether to pause bot at this waypoint
• lure: boolean - Whether this is a lure waypoint
• hotkey: string - Hotkey to press at waypoint
• click: string - Mouse click action to perform
• windowClick_X: number - X coordinate for window click
• windowClick_Y: number - Y coordinate for window click
• ladder_direction: string - Direction for ladder interaction
• nowait: boolean - Whether to skip waiting at waypoint
• chat_spell: string - Spell/text to say in chat
• facing_direction: string - Direction character should face
Example usage: 
local wpt = current_wpt()
if wpt.pausebot then
    close_tibia()
end
get_char_pos()
Gets the current character position.
Returns: table - [x, y, z] coordinates of character
is_pos_found()
Checks if the character's position has been successfully detected.
Returns: boolean - true if position is found, false otherwise
get_use_keyboard_walk() / set_use_keyboard_walk(enabled)
Get or set whether keyboard walking is enabled. If set as false, will use mouse click to walk.
Parameters for set:
• enabled: boolean - Whether to enable keyboard walking
Returns for get: boolean - Current keyboard walk status
can_go_to_wpt(mode, index)
Checks if moving to a specific waypoint is possible.
Parameters:
• mode: number - Waypoint mode (0: hunt, 1: refill, 2: to-hunt, 3: to-logout)
• index: number - Waypoint index to check
Returns: boolean - true if movement is possible
try_recenter_map()
Attempts to recenter the game map view, can only be called once every 10 seconds.
Returns: void
trygotocity(cityname)
Attempts to travel to a specified city using boat NPC (Mark the previous waypoint near the boat NPC).
Parameters:
• cityname: string - Name of the city to travel to
  • carlin
  • thais
  • venore
  • edron
  • libertybay
  • abdendriel
  • ankrahmun
  • darashia
  • grayisland
  • issavi
  • roshamuul
  • oramond
  • svargrond
  • porthope
    • pheast
    • phwest
    • phcentre/phcenter
    • phbanuta
    • phmountain
    • phchor
Carpet destination:
  • flyedron
  • flykazordoon
  • flydarashia
  • flyfemorhills
  • flysvargrond
  • flyzao
  • flyissavi
  • flymarapur
Returns: boolean - true if successful

Combat & Skills

handle_eq()
Handles equipment-related actions and checks.
Returns: void
cast_utito()
Casts utito tempo spell.
Returns: void
cast_amp_res()
Casts exeta amp res if conditions are met.
Returns: void
get_min_creature_to_attack() / set_min_creature_to_attack(value)
Get or set minimum number of creatures required to start attacking.
Parameters for set:
• value: number - Minimum number of creatures
Returns for get: number - Current minimum creature setting
get_nextwpt_avg_hp() / set_nextwpt_avg_hp(value)
Get or set the average HP threshold for moving to next waypoint.
Parameters for set:
• value: number - HP threshold percentage
Returns for get: number - Current HP threshold
get_nextwpt_min_mana_next_wpt() / set_nextwpt_min_mana_next_wpt(value)
Get or set minimum mana required to move to next waypoint.
Parameters for set:
• value: number - Minimum mana percentage
Returns for get: number - Current mana threshold
cast(spell_name)
Casts a specified spell or performs an action.
Parameters:
• spell_name: string - One of:
  - "eat_food": Use food item
  - "exeta_res": Cast exeta res spell
  - "healing_potion": Use healing potion
  - "utito_tempo": Cast utito tempo spell
  - "get_loot": Collect nearby loot
  - "mana_potion": Use mana potion
  - "exeta_amp_res": Cast exeta amp res spell
  - "battle_list_next_target": Switch to next target
  - "lure_rune_attack": Use lure rune
Returns: void
cast_lure_rune()
Casts a rune on the first target on the battlelist.
Returns: void
cast_lure_rune_nomouse()
Casts a rune on the selected target in the battlelist.
Returns: void
creature_count()
Gets the count of creatures in the battle list.
Returns: number - Number of creatures
cast_heal()
Executes healing if necessary based on configured thresholds.
Returns: void
cast_attack_spell()
Focuses target and casts configured attack spell.
Returns: void
focus_creature()
Focuses creature based on configured focus mode.
Returns: void
get_index_attack()
Return the creature index that its attacking.
Returns: number the index of the creature being attacked on battlelist, or -1, if no creature is being attacked
get_focus_mode() / set_focus_mode(mode)
Get or set the creature focusing mode.
Parameters for set:
• mode: string - One of: "Lowest_HP", "Highest_HP", "Smart_HP", "First_One"
Returns for get: string - Current focus mode
is_paralyzed_utited_hungry_hasted()
Checks if character is affected by paralysis, utito, hunger and hasted status.
Example usage: 
                    local is_paralyzed, is_utito, is_hungry, is_hasted = is_paralyzed_utited_hungry_hasted()
Returns: multiple boolean boolean, boolean, boolean, boolean

Inventory & Items

get_my_hp() / get_my_mana() / get_my_cap()
Get character's current stats.
Returns: number - Current HP/Mana percentage (0-100) or capacity value
get_my_level()
Get character's current level.
Returns: number - Current Level
npc_buyitem(icon_name, filter, amount, complete_buy)
Purchases items from an NPC.
Parameters:
• icon_name: string - The item icon to locate
• filter: string - Filter text for finding correct item
• amount: number - Quantity to purchase
• complete_buy: boolean - Whether to complete the purchase immediately
Returns: boolean - true if successful
do_npc_sellall()
Sells all eligible items to the NPC.
Returns: boolean - true if successful
dodepositall()
Deposits all items in the NPC bank.
Returns: void
get_potion_mana() / get_potion_hp()
Get current number of mana or health potions.
Returns: number - Current quantity of potions
do_drag_drop(x_ori, y_ori, x_dest, y_dest, reset)
Performs drag and drop operation.
Parameters:
• x_ori: number - Starting X coordinate
• y_ori: number - Starting Y coordinate
• x_dest: number - Destination X coordinate
• y_dest: number - Destination Y coordinate
• reset: boolean - Whether to reset mouse position after operation
Returns: boolean - true if successful
try_drop_vial()
Attempts to drop empty vials when conditions are met.
Returns: void
trydorefillpot()
Single attempt to refill potions from NPC.
Returns: boolean - true if successful
dorefillpot()
Multiple attempts to refill potions with retry logic.
Returns: void
get_eq_ring() / get_eq_amulet()
Return the ring/amulet currently equiped.
Returns: string
set_eq_ring("Sword") / get_eq_amulet("Red Plasma")
Ask the bot to use the new ring/amulet.
Allowed values for Amulets: "Foxtail", "Turtle", "Red Plasma", "Gill", "Glacier", "Magma", "Lightning", Terra"
Allowed values for Rings: "Dwarven", "Sword", "Club", "Axe", "Red Plasma", "Prismatic", "Stealth", "Spiritthorn"
Returns: void

UI & Interface

checkscreen()
Check if the screen is missing something, it will print on the lua console whats not found and save a screenshot under ./tmp/clientwindow.png with the found details.
Returns: void
set_ignore_first_x_pm_tabs(value:number)
Set the amount of tabs that will be ignored when checking for pm messages, default value is 4.
Returns: void
last_battlelist_position()
Gets the position of the last found creature in the battle list on screen.
Returns: tuple - (x, y) screen coordinates of battle list position. Returns (0,0) if no battle list is found
has_player_on_screen()
Checks if other players are visible on the screen. This function is used in conjunction with player detection systems and anti-PK features.
Example usage: 
    if has_player_on_screen() then
        printwebln("Warning: Player detected!")
        screenshot_telegram("Player on screen")
        -- Add your safety measures here
    end
Returns: boolean - true if other players are detected on screen, false otherwise
Related functions:
• notify_player_on_screen - Global variable to enable/disable notifications
send_keyboard(command)
Sends a keyboard command to the game client.
Parameters:
• command: string - Keyboard command to send
Returns: boolean - true if successful
send_keyboard_before_potion(command)
Sends a keyboard command to the game client before using pot.
Parameters:
• command: string - Keyboard command to send
Returns: boolean - true if successful
do_click(button)
Performs a mouse click with specified button.
Parameters:
• button: number - Mouse button (1: left, 2: right)
Returns: boolean - true if successful
open_npc_chat()
Opens NPC chat window and sends initial greeting.
Returns: void
send_text(text)
Sends text to the current chat window.
Parameters:
• text: string - Text to send
Returns: void
printweb(message) / printwebln(message)
Prints message to web console, with or without line break.
Parameters:
• message: string - Message to display
Returns: void
sendserial(command)
Sends a serial command and logs it to web console.
Parameters:
• command: string - Command to send
Returns: void
screenshot_telegram(command)
Sends a screenshot to Telegram with a command message.
Parameters:
• command: string - Message to send with screenshot
Returns: void
Note: Can only be used once every 30 seconds
handle_pending_command()
Processes any pending commands from the web interface.
Returns: void
locate(icon)
Locates an image on the screen.
Parameters:
• icon: string - Name of the icon to locate
Returns: tuple - (x, y, confidence, centerx, centery)
click_at(x, y, button, reset)
Performs mouse click at specified coordinates.
Parameters:
• x: number - X coordinate
• y: number - Y coordinate
• button: number - Mouse button (1: left, 2: right)
• reset: boolean - Whether to reset mouse position after click
Returns: boolean - true if successful
mousedown(x, y, button) / mouseup(x, y, button)
Controls individual mouse button press and release actions.
Parameters:
• x: number - X coordinate
• y: number - Y coordinate
• button: number - Mouse button (1: left, 2: right)
Returns: boolean - true if successful
send_keyboard_down(key) / send_keyboard_up(key)
Sends a keyboard key down or up event.
Parameters:
• key: string - Key to press or release (e.g., KEY_F1, KEY_F2...) list of all keys at the end
Returns: boolean - true if successful
mousemove(x, y)
Moves the mouse cursor to the specified coordinates.
Parameters:
• x: number - X coordinate
• y: number - Y coordinate
Returns: boolean - true if successful

Timer Functions

reset_exit_time(timetoexit)
Resets the exit timer with a new duration.
Parameters:
• timetoexit: string - Time in format "HH:MM:SS"
Returns: void
timeToMilliseconds(timeStr)
Converts time string to milliseconds.
Parameters:
• timeStr: string - Time in format "HH:MM:SS"
Returns: number - Time in milliseconds

Global Variables

drop_empty_vials_min, drop_empty_vials_max
Minimum and maximum time intervals between vial dropping attempts.
Type: number (default: 5000, 12000 milliseconds)
drop_empty_vials_min_cap
Minimum capacity threshold for dropping empty vials.
Type: number (default: 500)
exit_timer, ms_exit_timer
Time until bot exits hunt and absolute millisecond timestamp for exit.
Type: string (format: "HH:MM:SS") and number
player_detection_start, cumulative_player_time
Timestamps for player detection system.
Type: number (milliseconds)
mana_to_buy, hp_to_buy
Amount of mana and health potions to maintain during refill.
Type: number
exit_hunt_timer_playeronscreen
Time in milliseconds before exiting hunt when player is detected.
Type: number (default: 15000)
health_potion, mana_potion
Type of potions to use for healing and mana.
Type: string (default: "supreme h", "strong m")
notify_player_on_screen
Whether to enable player detection notifications.
Type: boolean (default: true)
CITY_COORDINATES
Table containing coordinates for all cities.
Type: table - Contains city names and their coordinates

Overwritable Functions

cast_utito()
If you want to change it, set it up inside the script
Original code: 
function cast_utito()
    local last_utito = get_last_utito()
    local last_support_spell = get_last_support_spell()
    local is_paralyzed, is_utito, is_hungry, is_hasted = is_paralyzed_utited_hungry_hasted()

    if (not is_utito or (last_utito.as_millis() > 9700))
        and (last_support_spell.as_millis() > 2000)
        and get_creatures_battlelist().len() > 0
    then
        cast("utito_tempo")
    end
end
Parameters:
Returns: void

Utility Functions

set_read_party_list(BOOL)
If set to true will set the bot to start reading the party list, if false, will ignore and improve performance, default value is false
Parameters:
Returns: void
get_last_utito()
Return the amount of milliseconds since last utito.
Parameters: None
get_last_support_spell()
Return the amount of milliseconds since last support spell was used.
Parameters: None
get_partymembers()
Returns a table with vector of (hp,mana), if both are 0, means the player is far away from the screen
Example implementation: 
local members = get_partymembers()
print("Party members:")
for i = 1, #members do
    print("Member " .. i .. ": hp=" .. members[i][1] .. ", mana=" .. members[i][2])
end
Parameters: None
Returns: table
last_move_millis()
Returns the amount of milliseconds since character last moved
Returns: number
reset_lastmove()
Resets the lastmove timer.
Returns: void
grid_to_window_pixel(x_offset,y_offset)
Return a pixel coordinate of the game window screen based on the grid format. 0,0 means center, -1,0, means 1 square to left, -2,-2 means diagonal top left (2 square distance from 0,0)
Returns: table
set_status() / get_status()
Gets/Sets bot status, allowed values: "Idle", "Attacking", "Walking" (they are all case sensitive).
Returns: string - Current Status: "Idle", "Attacking", "Walking"
lastframe()
Return frame number.
Returns: number
get_notify_player_on_screen() / set_notify_player_on_screen(value)
Get or set whether to notify when players are detected on screen.
Parameters for set:
• value: boolean - true to enable notifications, false to disable
Returns for get: boolean - Current notification state
send_telegram(message)
Sends a message to the configured Telegram, only one message can be sent every minute to avoid spam.
Parameters:
• message: string - Message to send
Returns: void
locate_on_battlelist(icon_name)
Attempts to locate a image on the battle list.
Parameters:
• icon_name: string - Name of the icon to locate
Returns: (x, y, confidence, center_x, center_y)
sleep(duration_millis)
Pauses execution for specified duration.
Parameters:
• duration_millis: number - Duration in milliseconds
Returns: boolean - true if successful
sleep_with_healattack(duration_millis)
Pauses execution for specified duration but will still cast healling and attackign spells while waiting.
Parameters:
• duration_millis: number - Duration in milliseconds
Returns: void
goto_next_wpt()
Will try to go to the next waypoint ignoring creatures and current state.
Returns: void
checkscreen()
Alerts you on telegram in case there is missing some mandatore objects on screen, like Battlelist, Battlelist Players and some backpacks.
Returns: void
get_millis()
Gets current system time in milliseconds.
Returns: number - Current time in milliseconds
release_pressed_keys()
Releases all pressed keyboard keys.
Returns: void
current_fps()
Gets the current frames per second being processed.
Returns: number - Current FPS
exit_client()
Exits the client application.
Returns: void
is_paused() / set_is_bot_paused(val)
Gets or sets the bot's pause state.
Parameters for set:
• val: boolean - Pause state to set
Returns for get: boolean - Current pause state
close_tibia()
Will close tibia client and pause the bot.
Returns: void
calculate_distance_creatures()
Calculate the distance considering the pathfinding between you and the creatures on screen.
Returns: table it contains the distance between you and all visible creatures on screen.
get_loot_positions()
Return the table containing [x,y,z] of the loots visible on the window.
Returns: table.
is_bestiary_mode()
Checks if the bestiary mode is enabled.
Returns: boolean - True if bestiary mode is enabled, false otherwise.
set_bestiary_mode(enable)
Enables or disables bestiary mode.
Parameters:
• enable: boolean - true to enable, false to disable
Returns: void
get_creatures_battlelist()
Returns a table containing information about all creatures currently visible in the battle list.
Returns: table - A table of creature objects, each containing:
• creature_hp: number - Current HP of the creature
• priority: number - Priority value of the creature (defined in the script)
• is_with_ampres: boolean - Whether the creature has ampres status
• is_ranged: boolean - Whether the creature is ranged (defined in the script)
• is_exeta: boolean - Whether the creature has exeta (defined in the script)
Example:
local battlelist = get_creatures_battlelist()
print("Battle List (" .. #battlelist .. " creatures):")
print("=" .. string.rep("=", 50))

for i, creature in pairs(battlelist) do
    print(string.format("Creature %d: HP=%d, Priority=%d, Ampres=%s, Ranged=%s, Exeta=%s",
        i,
        creature.creature_hp,
        creature.priority,
        creature.is_with_ampres and "Yes" or "No",
        creature.is_ranged and "Yes" or "No",
        creature.is_exeta and "Yes" or "No"
    ))
end
reset_mouse()
Resets the mouse position so bot knows where the mouse is (in case you moved the mouse and want to move it back programatically).
Returns: void
goto_position(x, y, z, r, mwt, lure, nowait)
Create a virtual waypoint.
Parameters:
• x: number - X coordinate
• y: number - Y coordinate
• z: number - Z coordinate
• r: number - Radius for movement
• mwt: number - Minimum wait time
• lure: boolean - Whether its a lure waypoint
• nowait: boolean - Whether is a no wait waypoint
Returns: void