MAUBOT LUA

Start with a small macro.

Create your first macro, understand the essentials, then find the functions you need.

01

Create a Lua file

Create or open a Lua file in your macro configuration and paste the example below.

02

Save and reload

Save the file, reload your macros and find My first macro in the macro list.

03

Enable and check the log

Enable the macro. It writes a message to the macro info log every five seconds. Turn it off when finished.

Your first macro

LUA

macro(5000, "My first macro", function()
  info("MauBot macro is running.")
end)

5000 is the interval in milliseconds. The function contains the code that runs each time.

A few essentials

macro(...): Runs your code repeatedly at the chosen interval.
storage: Keeps settings for the current character and configuration.
delay(...): Pauses the current macro, hotkey or event callback.
nil: Means no value was returned. Check for it before using an optional result.

If a macro fails, read its error message and check the function signature, argument order and return value in the reference.

Explore complete examples Open the macro reference

LUA

Examples

Complete scripts you can copy, read and adapt. Choose a task to get started.

Configurable Heal With Setup Draggable Toggle Icon Auto Haste With Safety Checks Anti Paralyze Recovery Smart Closest Target Safe Rune Selector Auto Party Invite Auto Follow Last Seen Position Use Items Around Player Push Target To Tile

Configurable Heal With Setup

Store settings, expose setup fields, and cast only when conditions match.

local key = "example_heal"
storage[key] = storage[key] or {
  spell = "exura",
  hp = 80,
  mana = 10,
  hotkey = ""
}

local config = storage[key]

local heal = macro(100, "Example Heal", config.hotkey, function()
  if hppercent() <= tonumber(config.hp) and manapercent() >= tonumber(config.mana) and canCast(config.spell) then
    castSpell(config.spell)
    delay(1000)
  end
end)

heal:setSetup(function()
  UI.Section("Heal Settings")

  UI.Field("Spell", config.spell, function(value)
    config.spell = value
  end)

  UI.NumberField("HP <=", config.hp, function(value)
    config.hp = math.max(1, math.min(100, tonumber(value) or 80))
  end)

  UI.NumberField("Mana >=", config.mana, function(value)
    config.mana = math.max(0, math.min(100, tonumber(value) or 10))
  end)

  UI.HotkeyField("Hotkey", config.hotkey, function(combo)
    config.hotkey = combo
    heal:setHotkey(combo)
  end)
end)

Draggable Toggle Icon

Link a movable screen icon to a macro and let users show or hide it.

local key = "example_icon_heal"
storage[key] = storage[key] or {
  showIcon = true,
  iconItemId = 3160,
  iconText = "Heal"
}

local config = storage[key]
local icon

local heal = macro(100, "Icon Heal", function()
  if hppercent() <= 70 and canCast("exura gran") then
    castSpell("exura gran")
    delay(1000)
  end
end)

local function setIconVisible()
  if icon and icon.setVisible then
    icon:setVisible(config.showIcon == true)
  end
end

icon = addIcon("example_icon_heal", {
  item = { id = config.iconItemId, count = 1 },
  text = config.iconText,
  movable = true
}, function(_, isOn)
  if isOn then
    heal:setOn()
  else
    heal:setOff()
  end
end)

setIconVisible()

heal:setSetup(function()
  UI.Switch("Show Icon", config.showIcon, function(enabled)
    config.showIcon = enabled
    setIconVisible()
  end)

  UI.IconFields(icon, config, { itemId = 3160, text = "Heal" })
end)

Auto Haste With Safety Checks

Keep haste active while respecting mana, target, paralysis, and cooldown checks.

local config = {
  spell = "utani hur",
  mana = 20,
  cooldown = 2000,
  onlyWithoutTarget = false
}

local nextCast = 0

macro(250, "Safe Haste", function()
  if now < nextCast then return end
  if manapercent() < config.mana then return end
  if isParalyzed() then return end
  if hasHaste() then return end
  if config.onlyWithoutTarget and target() then return end

  say(config.spell)
  nextCast = now + config.cooldown
end)

Anti Paralyze Recovery

React to paralysis quickly without spamming the spell every tick.

local config = {
  spell = "utani hur",
  mana = 15,
  cooldown = 1200
}

local nextCast = 0

macro(100, "Anti Paralyze", function()
  if not isParalyzed() then return end
  if manapercent() < config.mana then return end
  if now < nextCast then return end

  say(config.spell)
  nextCast = now + config.cooldown
end)

Smart Closest Target

Scan spectators, choose the best monster, and attack it automatically.

local config = {
  range = 6,
  preferLowHp = true
}

macro(250, "Attack Closest", function()
  if target() then return end

  local playerPos = pos()
  local best, bestScore

  for _, creature in ipairs(getSpectators()) do
    if creature:isMonster() then
      local creaturePos = creature:getPosition()
      local distance = getDistanceBetween(playerPos, creaturePos)

      if creaturePos.z == playerPos.z and distance <= config.range then
        local score = distance * 100
        if config.preferLowHp then
          score = score + creature:getHealthPercent()
        end

        if not bestScore or score < bestScore then
          best = creature
          bestScore = score
        end
      end
    end
  end

  if best then
    g_game.attack(best)
  end
end)

Safe Rune Selector

Use an area rune only when it is safe, otherwise fall back to a single target rune.

local config = {
  singleRune = 3155, -- SD
  areaRune = 3161,   -- Avalanche
  areaRange = 5
}

macro(200, "Safe Rune", function()
  local creature = g_game.getAttackingCreature()
  if not creature then return end

  local distance = getDistanceBetween(pos(), creature:getPosition())

  if distance <= config.areaRange and isSafe(8) then
    useWith(config.areaRune, creature)
  else
    useWith(config.singleRune, creature)
  end

  delay(900)
end)

Auto Party Invite

Listen to chat, validate the nearby player, and invite them to party.

local inviteWords = {
  ["party"] = true,
  ["pt"] = true,
  ["invite"] = true
}

onTalk(function(name, level, mode, text)
  if not inviteWords[text:lower()] then return end

  for _, creature in ipairs(getSpectators()) do
    if creature:isPlayer() and creature:getName():lower() == name:lower() then
      if not creature:isPartyMember() then
        g_game.partyInvite(creature:getId())
      end
      return
    end
  end
end)

Auto Follow Last Seen Position

Remember a player position from events and walk to the last known tile.

local followName = "Leader"
local lastSeen = {}

onCreaturePositionChange(function(creature, newPos, oldPos)
  if creature:getName():lower() ~= followName:lower() then return end
  if newPos then
    lastSeen[newPos.z] = newPos
  end
end)

macro(500, "Follow Last Seen", function()
  local creature = getCreatureByName(followName)
  if creature then
    g_game.follow(creature)
    return
  end

  local playerPos = pos()
  local knownPos = lastSeen[playerPos.z]
  if knownPos and getDistanceBetween(playerPos, knownPos) > 1 then
    autoWalk(knownPos, 50, {
      ignoreNonPathable = true,
      precision = 1
    })
  end
end)

Use Items Around Player

Scan nearby tiles and use matching items when they appear on screen.

local useIds = {
  [1948] = true, -- lever
  [435] = true,  -- hole
  [386] = true   -- rope spot
}

macro(500, "Use Nearby Items", function()
  local base = pos()

  for x = -1, 1 do
    for y = -1, 1 do
      local tile = g_map.getTile({
        x = base.x + x,
        y = base.y + y,
        z = base.z
      })

      local item = tile and tile:getTopUseThing()
      if item and useIds[item:getId()] then
        use(item)
        delay(500)
        return
      end
    end
  end
end)

Push Target To Tile

Select a creature and destination tile with a hotkey, then move or rune the target.

local state = {
  target = nil,
  destination = nil,
  pushRune = 3188
}

local function getCreatureFromTile(tile)
  if not tile then return nil end

  for _, thing in ipairs(tile:getThings()) do
    if thing:isCreature() then
      return thing
    end
  end
end

onKeyDown(function(key)
  local tile = getTileUnderCursor()

  if key == "F8" then
    state.target = getCreatureFromTile(tile)
    info("Push target selected.")
  elseif key == "F9" and tile then
    state.destination = tile:getPosition()
    info("Push destination selected.")
  elseif key == "F10" and state.target and state.destination then
    if state.pushRune and state.pushRune > 0 then
      useWith(state.pushRune, state.target)
    end

    g_game.move(state.target, state.destination)
  end
end)

API REFERENCE

Runtime

State and logging values available in every macro file.

storageconfigNameconfigDirnowtimeplayerpanelmainTabMauBotvBotsaveConfigreloadinfowarnerrorlogInfostandTimescheduledelay

`storage`

storage[key]

Persistent table saved per character and config.

Returns: table

`configName`

configName

Current macro config name.

Returns: string

`configDir`

configDir

Full path to the current macro config folder.

Returns: string

`now`

now

Current macro timestamp in milliseconds.

Returns: number

`time`

time

Alias for now.

Returns: number

`player`

player

Current local player object.

Returns: LocalPlayer

`panel`

panel

Current panel used by UI helpers.

Returns: widget

`mainTab`

mainTab

Main macro panel tab.

Returns: widget

`MauBot`

MauBot

Shared compatibility state table.

Returns: table

`vBot`

vBot

Alias for MauBot.

Returns: table

`saveConfig`

saveConfig()

Marks storage for saving.

Returns: nil

`reload`

reload()

Reloads the current config.

Returns: boolean

`info`

info(text)

Writes to the macro info log.

Returns: nil

`warn`

warn(text)

Writes to the macro warning log.

Returns: nil
Aliases: warning

`error`

error(text)

Writes to the macro error log.

Returns: nil

`logInfo`

logInfo(text)

Writes a terminal-style info line.

Returns: nil

`standTime`

standTime()

Milliseconds since the local player last moved.

Returns: number

`schedule`

schedule(timeoutMs, callback)

Runs callback once after the delay.

Returns: nil

`delay`

delay(durationMs)

Pauses the current macro, hotkey, or event callback.

Returns: nil

API REFERENCE

Macros

Create repeating macros, hotkeys, setup windows, and screen icons.

macromacromacromacro:isOnmacro:isOffmacro:setOnmacro:setOffmacro:togglemacro:setTooltipmacro:setHotkeymacro:setSetupmacro:openSetuphotkeysinglehotkeyhotkey:setTooltiphotkey:setHotkeyhotkey:setSetuphotkey:openSetupaddIcon

`macro`

macro(timeoutMs, name, callback)

Creates a named macro row.

Returns: macro

`macro`

macro(timeoutMs, name, hotkey, callback)

Creates a named macro row with a hotkey label.

Returns: macro

`macro`

macro(timeoutMs, callback)

Creates a background macro without a row.

Returns: macro

`macro:isOn`

macro:isOn()

True when enabled.

Returns: boolean

`macro:isOff`

macro:isOff()

True when disabled.

Returns: boolean

`macro:setOn`

macro:setOn([value])

Enables the macro. Passing false disables it.

Returns: nil

`macro:setOff`

macro:setOff([value])

Disables the macro. Passing false enables it.

Returns: nil

`macro:toggle`

macro:toggle()

Toggles enabled state.

Returns: nil

`macro:setTooltip`

macro:setTooltip(text)

Sets the row tooltip.

Returns: macro

`macro:setHotkey`

macro:setHotkey(combo)

Updates the displayed hotkey combo.

Returns: macro

`macro:setSetup`

macro:setSetup(function(panel, macro) end)

Adds a setup button and builds the setup window on click.

Returns: macro

`macro:openSetup`

macro:openSetup()

Opens the setup window.

Returns: macro

`hotkey`

hotkey(keys, name, callback)

Runs callback when the key combo is pressed.

Returns: hotkey

`singlehotkey`

singlehotkey(keys, name, callback)

Hotkey variant for single key-down actions.

Returns: hotkey

`hotkey:setTooltip`

hotkey:setTooltip(text)

Sets the row tooltip.

Returns: hotkey

`hotkey:setHotkey`

hotkey:setHotkey(combo)

Changes the key combo if it is not duplicated.

Returns: hotkey|false

`hotkey:setSetup`

hotkey:setSetup(function(panel, hotkey) end)

Adds a setup button to the hotkey row.

Returns: hotkey

`hotkey:openSetup`

hotkey:openSetup()

Opens the setup window.

Returns: hotkey

`addIcon`

addIcon(id, options, callbackOrMacro)

Creates a movable screen icon. Options: item, outfit, text, hotkey, movable, switchable, phantom, x, y.

Returns: widget

API REFERENCE

UI

Build controls in the macro panel or inside setSetup.

addTabsetDefaultTabsetupUIcreateWidgetaddSwitchaddButtonaddLabeladdTextEditaddSeparatorUI.SectionUI.FieldUI.NumberFieldUI.HotkeyFieldUI.SwitchUI.IconFieldsUI.ContainerUI.ContainerFieldUI.LabelUI.ButtonUI.TextEditUI.SeparatorUI.EditorWindowUI.SinglelineEditorWindowUI.MultilineEditorWindowUI.ConfirmationWindowUI.createWidgetUI.createWindowUI.createMiniWindowUI.ConfigUI.DualScrollPanelUI.DualScrollItemPanelUI.TwoItemsAndSlotPanelUI.DualLabelUI.LabelAndTextEditUI.SwitchAndButtonPanels.AttackLeaderTarget

`addTab`

addTab(name)

Creates or selects a macro panel tab.

Returns: panel
Aliases: getTab

`setDefaultTab`

setDefaultTab(name)

Sets where future UI helpers place widgets.

Returns: panel

`setupUI`

setupUI(otml, parent)

Loads an OTML widget string into a panel.

Returns: widget

`createWidget`

createWidget(name, parent)

Creates and tracks a widget.

Returns: widget

`addSwitch`

addSwitch(id, text, onClick, parent)

Creates a switch row.

Returns: widget

`addButton`

addButton(id, text, onClick, parent)

Creates a button.

Returns: widget

`addLabel`

addLabel(id, text, parent)

Creates a label.

Returns: widget

`addTextEdit`

addTextEdit(id, text, onTextChange, parent)

Creates a text input. Callback receives widget and text.

Returns: widget

`addSeparator`

addSeparator(id, parent)

Creates a separator.

Returns: widget

`UI.Section`

UI.Section(title, parent)

Creates a setup section header.

Returns: widget

`UI.Field`

UI.Field(label, value, callback, parent)

Creates a labeled text field. Callback receives text, widget, row.

Returns: widget

`UI.NumberField`

UI.NumberField(label, value, callback, parent)

Same as UI.Field, intended for numeric values.

Returns: widget

`UI.HotkeyField`

UI.HotkeyField(label, value, callback, parent)

Creates a key combo capture field.

Returns: widget

`UI.Switch`

UI.Switch(label, value, callback, parent)

Creates a labeled setup switch. Callback receives boolean, widget, row.

Returns: widget

`UI.IconFields`

UI.IconFields(icon, config, defaults, parent)

Creates icon item and icon text fields.

Returns: table

`UI.Container`

UI.Container(callback, unique, parent, widget)

Creates an item list editor with setItems and getItems.

Returns: widget

`UI.ContainerField`

UI.ContainerField(label, items, callback, unique, parent, height)

Creates a labeled item list editor.

Returns: widget

`UI.Label`

UI.Label(text, parent)

Creates a label with automatic id.

Returns: widget

`UI.Button`

UI.Button(text, callback, parent)

Creates a button with automatic id.

Returns: widget

`UI.TextEdit`

UI.TextEdit(text, callback, parent)

Creates a text edit with automatic id.

Returns: widget

`UI.Separator`

UI.Separator(parent)

Creates a separator with automatic id.

Returns: widget

`UI.EditorWindow`

UI.EditorWindow(text, options, callback)

Opens an editor window.

Returns: window

`UI.SinglelineEditorWindow`

UI.SinglelineEditorWindow(text, options, callback)

Opens a single-line editor.

Returns: window

`UI.MultilineEditorWindow`

UI.MultilineEditorWindow(text, options, callback)

Opens a multiline editor.

Returns: window

`UI.ConfirmationWindow`

UI.ConfirmationWindow(title, question, callback)

Opens a yes/no confirmation window.

Returns: window

`UI.createWidget`

UI.createWidget(name, parent)

Creates and tracks a widget.

Returns: widget

`UI.createWindow`

UI.createWindow(name, parent)

Creates, shows, raises, and focuses a window.

Returns: window

`UI.createMiniWindow`

UI.createMiniWindow(name, parent)

Creates a mini window.

Returns: window

`UI.Config`

UI.Config(parent)

Creates a small config panel.

Returns: panel

`UI.DualScrollPanel`

UI.DualScrollPanel(params, callback, parent)

Creates a two-slider percent range control.

Returns: widget

`UI.DualScrollItemPanel`

UI.DualScrollItemPanel(params, callback, parent)

Creates a two-slider range control with an item selector.

Returns: widget

`UI.TwoItemsAndSlotPanel`

UI.TwoItemsAndSlotPanel(params, callback, parent)

Creates a two-item and slot selector panel.

Returns: widget

`UI.DualLabel`

UI.DualLabel(left, right, params, parent)

Creates a left/right label row.

Returns: widget

`UI.LabelAndTextEdit`

UI.LabelAndTextEdit(params, callback, parent)

Creates a label plus text input row.

Returns: widget

`UI.SwitchAndButton`

UI.SwitchAndButton(params, callbackSwitch, callbackButton, callback, parent)

Creates a switch plus button row.

Returns: widget

`Panels.AttackLeaderTarget`

Panels.AttackLeaderTarget(parent)

Creates a panel that attacks the target hit by a configured leader.

Returns: nil

API REFERENCE

Player

Read character stats, position, equipment, outfit, and conditions.

namehpmaxhphppercentmanamaxmanamanapercentcapfreecapmaxcapexplvlmlevsoulstaminavocblessdirectionspeedskulloutfitsetOutfitsetSpeedhasConditionisPoisonedisBurningisEnergizedisDrunkhasManaShieldisParalyzedhasHastehasSwordscanLogoutisInProtectionZonehasPzLockisDrowningisFreezingisDazzledisCursedhasPartyBuffisBleedingisHungryisBuffedkillsToRs

`name`

name()

Character name.

Returns: string

`hp`

hp()

Current health.

Returns: number

`maxhp`

maxhp()

Maximum health.

Returns: number
Aliases: hpmax

`hppercent`

hppercent()

Current health percent.

Returns: number

`mana`

mana()

Current mana.

Returns: number

`maxmana`

maxmana()

Maximum mana.

Returns: number
Aliases: manamax

`manapercent`

manapercent()

Current mana percent.

Returns: number

`cap`

cap()

Current capacity.

Returns: number

`freecap`

freecap()

Free capacity.

Returns: number

`maxcap`

maxcap()

Total capacity.

Returns: number
Aliases: capmax

`exp`

exp()

Experience.

Returns: number

`lvl`

lvl()

Level.

Returns: number
Aliases: level

`mlev`

mlev()

Magic level.

Returns: number
Aliases: magic, mlevel

`soul`

soul()

Soul points.

Returns: number

`stamina`

stamina()

Stamina.

Returns: number

`voc`

voc()

Vocation id.

Returns: number
Aliases: vocation

`bless`

bless()

Blessings value.

Returns: number
Aliases: blesses, blessings

`direction`

direction()

Facing direction.

Returns: number

`speed`

speed()

Current speed.

Returns: number

`skull`

skull()

Skull value.

Returns: number

`outfit`

outfit()

Current outfit table.

Returns: table

`setOutfit`

setOutfit(outfit)

Changes outfit.

Returns: boolean|nil
Aliases: changeOutfit

`setSpeed`

setSpeed(value)

Changes local speed when supported.

Returns: boolean

`hasCondition`

hasCondition(condition)

Checks a PlayerStates flag.

Returns: boolean

`isPoisoned`

isPoisoned()

Poison condition.

Returns: boolean
Aliases: isPoisioned

`isBurning`

isBurning()

Burn condition.

Returns: boolean

`isEnergized`

isEnergized()

Energy condition.

Returns: boolean

`isDrunk`

isDrunk()

Drunk condition.

Returns: boolean

`hasManaShield`

hasManaShield()

Mana shield condition.

Returns: boolean

`isParalyzed`

isParalyzed()

Paralyze condition.

Returns: boolean

`hasHaste`

hasHaste()

Haste condition.

Returns: boolean

`hasSwords`

hasSwords()

In-fight condition.

Returns: boolean
Aliases: isInFight

`canLogout`

canLogout()

True when not in fight.

Returns: boolean

`isInProtectionZone`

isInProtectionZone()

Protection zone condition.

Returns: boolean
Aliases: hasPz, isInPz

`hasPzLock`

hasPzLock()

PZ lock/block condition.

Returns: boolean
Aliases: hasPzBlock, isPzLocked, isPzBlocked

`isDrowning`

isDrowning()

Drowning condition.

Returns: boolean

`isFreezing`

isFreezing()

Freezing condition.

Returns: boolean

`isDazzled`

isDazzled()

Dazzled condition.

Returns: boolean

`isCursed`

isCursed()

Cursed condition.

Returns: boolean

`hasPartyBuff`

hasPartyBuff()

Party buff condition.

Returns: boolean

`isBleeding`

isBleeding()

Bleeding condition.

Returns: boolean

`isHungry`

isHungry()

Hungry condition.

Returns: boolean

`isBuffed`

isBuffed()

Checks active party buff effect.

Returns: boolean

`killsToRs`

killsToRs()

Remaining unjustified kills before red skull.

Returns: number

API REFERENCE

Movement

Positions, walking, turning, pathfinding, and map view helpers.

posposxposyposzgetPoswalkturnfindAllPathstranslateAllPathsToPathfindPathautoWalkdistanceFromPlayergetMapViewzoomInzoomOut

`pos`

pos()

Current player position.

Returns: position

`posx`

posx()

Current x coordinate.

Returns: number

`posy`

posy()

Current y coordinate.

Returns: number

`posz`

posz()

Current floor.

Returns: number

`getPos`

getPos(x, y, z)

Builds a position table.

Returns: position|nil

`walk`

walk(direction)

Walks one direction.

Returns: boolean

`turn`

turn(direction)

Turns to a direction.

Returns: boolean

`findAllPaths`

findAllPaths(start, maxDist, params)

Finds reachable path nodes.

Returns: table|nil
Aliases: findEveryPath

`translateAllPathsToPath`

translateAllPathsToPath(paths, destPos)

Converts path nodes into directions.

Returns: table|nil
Aliases: translateEveryPathToPath

`findPath`

findPath(startPos, destPos, maxDist, params)

Finds directions to a destination.

Returns: table|nil
Aliases: getPath

`autoWalk`

autoWalk(destination, maxDist, params)

Walks to a destination or along a direction list.

Returns: boolean

`distanceFromPlayer`

distanceFromPlayer(coords, fromPos)

Chebyshev distance from player or another position.

Returns: number|false

`getMapView`

getMapView()

Returns the map panel.

Returns: widget|nil
Aliases: getMapPanel

`zoomIn`

zoomIn()

Zooms map panel in.

Returns: nil

`zoomOut`

zoomOut()

Zooms map panel out.

Returns: nil

API REFERENCE

Combat And Speech

Targeting, following, chat, channels, spells, and runes.

attackcancelAttackfollowcancelFollowcancelAttackAndFollowtargettargetPossaysayNpcyelltalkChanneltalkPrivategetChannelsgetChannelIdsaySpellsetSpellTimeoutgetSpellDatagetSpellCoolDowncanCastcastcastSpelluseRunescheduleNpcSayisAttSpell

`attack`

attack(creature)

Attacks a creature.

Returns: nil

`cancelAttack`

cancelAttack()

Stops attacking.

Returns: nil

`follow`

follow(creature)

Follows a creature.

Returns: nil

`cancelFollow`

cancelFollow()

Stops following.

Returns: nil

`cancelAttackAndFollow`

cancelAttackAndFollow()

Stops attack and follow.

Returns: nil

`target`

target()

Current attack target.

Returns: creature|nil
Aliases: getTarget

`targetPos`

targetPos([distance])

Target position, or distance when distance is true.

Returns: position|number|nil

`say`

say(text)

Sends normal chat.

Returns: nil
Aliases: talk

`sayNpc`

sayNpc(text)

Sends NPC chat.

Returns: nil
Aliases: talkNpc, sayNPC, talkNPC

`yell`

yell(text)

Sends yell chat.

Returns: nil

`talkChannel`

talkChannel(channelId, text)

Sends channel chat.

Returns: nil
Aliases: sayChannel

`talkPrivate`

talkPrivate(receiver, text)

Sends private chat.

Returns: nil
Aliases: sayPrivate

`getChannels`

getChannels()

Returns known channels.

Returns: table

`getChannelId`

getChannelId(name)

Finds a channel id by name.

Returns: number|nil
Aliases: getChannel

`saySpell`

saySpell(text, timeoutMs)

Says spell words if timeout passed.

Returns: boolean

`setSpellTimeout`

setSpellTimeout()

Updates the local spell timeout.

Returns: nil

`getSpellData`

getSpellData(spell)

Returns spell data by words or name.

Returns: table|false

`getSpellCoolDown`

getSpellCoolDown(text)

True when spell or group cooldown is active.

Returns: boolean

`canCast`

canCast(spell, ignoreRL, ignoreCd)

Checks cooldown, level, and mana when data exists.

Returns: boolean

`cast`

cast(text, delayMs)

Says text with a local cooldown.

Returns: boolean|nil

`castSpell`

castSpell(text)

Casts only when canCast returns true.

Returns: boolean|nil

`useRune`

useRune(itemId, target, timeoutMs)

Uses a rune item on a target with local timeout.

Returns: boolean
Aliases: userune

`scheduleNpcSay`

scheduleNpcSay(text, delayMs)

Schedules an NPC message.

Returns: nil|false

`isAttSpell`

isAttSpell(text)

True when text starts with exori or exevo.

Returns: boolean

API REFERENCE

Items

Inventory slots, containers, item use, and ground item helpers.

useusewithfindItemitemAmountgetContainersgetContainergetContainerByNamegetContainerByItemcontainerIsFullgetInventoryItemgetHeadgetNeckgetBackgetBodygetRightgetLeftgetLeggetFeetgetFingergetAmmogetPurseopenPursereopenPursemoveToSlotdropItemgetActiveItemIdgetInactiveItemIdgetNearTilesfindItemOnGroundisOnTileuseGroundItemreachGroundItemuseOnGroundItemuseOnInventoryItemgetTileUnderCursorcanShootisTrapped

`use`

use(thingOrItemId, subtype)

Uses an item, thing, or inventory item id.

Returns: mixed

`usewith`

usewith(thingOrItemId, target, subtype)

Uses an item on a target.

Returns: mixed
Aliases: useWith

`findItem`

findItem(itemId, subType)

Finds an item in open containers or inventory.

Returns: item|nil

`itemAmount`

itemAmount(itemId)

Counts player items by id.

Returns: number

`getContainers`

getContainers()

Returns open containers.

Returns: table

`getContainer`

getContainer(index)

Returns a container by index.

Returns: container|nil

`getContainerByName`

getContainerByName(name, notFull)

Finds an open container by exact name.

Returns: container|nil

`getContainerByItem`

getContainerByItem(itemId, notFull)

Finds an open container by container item id.

Returns: container|nil

`containerIsFull`

containerIsFull(container)

Checks whether a container is full.

Returns: boolean

`getInventoryItem`

getInventoryItem(slot)

Returns the item in an inventory slot.

Returns: item|nil
Aliases: getSlot

`getHead`

getHead()

Head slot item.

Returns: item|nil

`getNeck`

getNeck()

Neck slot item.

Returns: item|nil

`getBack`

getBack()

Backpack slot item.

Returns: item|nil

`getBody`

getBody()

Body slot item.

Returns: item|nil

`getRight`

getRight()

Right hand slot item.

Returns: item|nil

`getLeft`

getLeft()

Left hand slot item.

Returns: item|nil

`getLeg`

getLeg()

Leg slot item.

Returns: item|nil

`getFeet`

getFeet()

Feet slot item.

Returns: item|nil

`getFinger`

getFinger()

Ring slot item.

Returns: item|nil

`getAmmo`

getAmmo()

Ammo slot item.

Returns: item|nil

`getPurse`

getPurse()

Purse slot item.

Returns: item|nil

`openPurse`

openPurse()

Uses the purse slot item.

Returns: boolean|nil

`reopenPurse`

reopenPurse()

Reopens purse-related containers.

Returns: boolean|nil

`moveToSlot`

moveToSlot(itemOrId, slot, count)

Moves an item to an inventory slot.

Returns: boolean|nil

`dropItem`

dropItem(itemOrId)

Drops an item on the player position.

Returns: boolean|nil

`getActiveItemId`

getActiveItemId(id)

Maps inactive ring/amulet ids to active ids when known.

Returns: number|false

`getInactiveItemId`

getInactiveItemId(id)

Maps active ring/amulet ids to inactive ids when known.

Returns: number|false

`getNearTiles`

getNearTiles(positionOrCreature)

Returns the eight neighboring tiles.

Returns: table

`findItemOnGround`

findItemOnGround(itemId)

Finds a visible ground item by id.

Returns: item|nil

`isOnTile`

isOnTile(itemId, tileOrPos)

Checks whether an item id exists on a tile. Also accepts x, y, z.

Returns: boolean

`useGroundItem`

useGroundItem(itemId)

Uses the first visible ground item with id.

Returns: boolean|nil

`reachGroundItem`

reachGroundItem(itemId)

Walks toward the first visible ground item with id.

Returns: boolean

`useOnGroundItem`

useOnGroundItem(toolItemId, groundItemId)

Uses an inventory item on a visible ground item.

Returns: boolean|nil

`useOnInventoryItem`

useOnInventoryItem(toolItemId, targetItemId)

Uses an item on an inventory item.

Returns: boolean|nil
Aliases: useOnInvertoryItem

`getTileUnderCursor`

getTileUnderCursor()

Returns the tile under the mouse cursor.

Returns: tile|nil

`canShoot`

canShoot(pos, distance)

Checks if a tile can be shot.

Returns: boolean

`isTrapped`

isTrapped([creature])

True when no neighboring tile is walkable.

Returns: boolean

API REFERENCE

Creatures

Find spectators, players, monsters, NPCs, friends, enemies, and safe tiles.

getSpectatorsgetCreatureByIdgetCreatureByNamegetPlayerByNamegetMonstersInRangegetMonstersgetPlayersgetAllPlayersgetNpcsgetCreaturesInAreaisFriendisEnemygetPlayerDistributiongetFriendsgetNeutralsgetEnemiesisBlackListedPlayerInRangegetBestTileByPatternisSafe

`getSpectators`

getSpectators([positionOrCreatureOrPattern], [multifloor])

Returns visible spectators.

Returns: table

`getCreatureById`

getCreatureById(id, multifloor)

Finds a visible creature by id.

Returns: creature|nil

`getCreatureByName`

getCreatureByName(name, multifloor)

Finds a visible creature by exact name.

Returns: creature|nil

`getPlayerByName`

getPlayerByName(name, multifloor)

Finds a visible player by exact name.

Returns: creature|nil

`getMonstersInRange`

getMonstersInRange(position, range)

Counts monsters near a position.

Returns: number|false

`getMonsters`

getMonsters(range, multifloor)

Counts monsters around the player.

Returns: number

`getPlayers`

getPlayers(range, multifloor)

Counts nearby non-party players.

Returns: number

`getAllPlayers`

getAllPlayers(range, multifloor)

Counts all nearby non-local players.

Returns: number

`getNpcs`

getNpcs(range, multifloor)

Counts nearby NPCs.

Returns: number

`getCreaturesInArea`

getCreaturesInArea(positionOrPattern, patternOrMultifloor, type)

Counts spectators, monsters, or players in an area.

Returns: number

`isFriend`

isFriend(creatureOrName)

Checks friend list, party, and shared member state.

Returns: boolean

`isEnemy`

isEnemy(creatureOrName)

Checks enemy list, marks, and emblem state.

Returns: boolean

`getPlayerDistribution`

getPlayerDistribution()

Splits visible players into three lists.

Returns: friends, neutrals, enemies

`getFriends`

getFriends()

Returns visible friends.

Returns: table

`getNeutrals`

getNeutrals()

Returns visible neutral players.

Returns: table

`getEnemies`

getEnemies()

Returns visible enemies.

Returns: table

`isBlackListedPlayerInRange`

isBlackListedPlayerInRange(range)

Checks storage.playerList.blackList around the player.

Returns: boolean

`getBestTileByPattern`

getBestTileByPattern(pattern, specType, maxDist, safe)

Finds the best shootable and walkable tile for an area pattern.

Returns: table|false
Aliases: getBestTileByPatern

`isSafe`

isSafe(range, multifloor, padding)

True when no non-friend player is inside the range.

Returns: boolean

API REFERENCE

Files And Config

Load scripts, import styles, read custom configs, and encode data.

loaddofiledofilesloadScriptloadRemoteScriptimportStylefileExistsencodedecodeConfig.existConfig.createConfig.listConfig.parseConfig.loadConfig.loadRawConfig.saveConfig.removeConfig.setup

`load`

load(source)

Loads Lua source in the macro context.

Returns: function
Aliases: loadstring

`dofile`

dofile(relativePath)

Runs a Lua file from the current config folder.

Returns: mixed

`dofiles`

dofiles(path)

Runs all Lua files in a config subfolder recursively.

Returns: nil

`loadScript`

loadScript(pathOrUrl, onLoad)

Loads a local or remote script.

Returns: mixed

`loadRemoteScript`

loadRemoteScript(url, onLoad)

Downloads and runs a remote script.

Returns: nil

`importStyle`

importStyle(otuiPathOrString)

Imports an OTUI style from file or string.

Returns: mixed

`fileExists`

fileExists(path)

Checks whether a mapped macro file exists.

Returns: boolean
Aliases: mauFileExists

`encode`

encode(data, indent)

Serializes data to text.

Returns: string

`decode`

decode(text)

Parses serialized text. Returns empty table on failure.

Returns: table

`Config.exist`

Config.exist(dir)

Checks whether a config directory exists.

Returns: boolean

`Config.create`

Config.create(dir)

Creates a config directory.

Returns: boolean

`Config.list`

Config.list(dir)

Lists config names in a directory.

Returns: table

`Config.parse`

Config.parse(data)

Parses saved config text.

Returns: table

`Config.load`

Config.load(dir, name)

Loads a saved config.

Returns: table|nil

`Config.loadRaw`

Config.loadRaw(dir, name)

Loads raw config text.

Returns: string|nil

`Config.save`

Config.save(dir, name, value, forcedExtension)

Saves table data.

Returns: boolean

`Config.remove`

Config.remove(dir, name)

Deletes saved files for a config.

Returns: boolean

`Config.setup`

Config.setup(dir, widget, extension, callback)

Connects config list UI controls to load, save, add, edit, and remove actions.

Returns: table|nil

API REFERENCE

Events

Register callbacks for client events. Each registration returns a handle with remove().

callbackonKeyDownonKeyUponKeyPressonTalklistenonTextMessageonPlayerPositionChangeonPlayerHealthChangeonPlayerInventoryChangeonCreatureAppearonCreatureDisappearonCreaturePositionChangeonCreatureHealthPercentChangeonAttackingCreatureChangeonTurnonWalkonUseonUseWithonContainerOpenonContainerCloseonContainerUpdateItemonAddItemonRemoveItemonManaChangeonStatesChangeonInventoryChangeonSpellCooldownonGroupSpellCooldownonModalDialogonAddThingonRemoveThingonMissleonAnimatedTextonStaticTextonChannelListonOpenChannelonCloseChannelonChannelEventonLoginAdviceonImbuementWindowonGameEditText

`callback`

callback(type, function(...) end)

Low-level event registration.

Returns: handle

`onKeyDown`

onKeyDown(function(keyDesc) end)

Key down event.

Returns: handle

`onKeyUp`

onKeyUp(function(keyDesc) end)

Key up event.

Returns: handle

`onKeyPress`

onKeyPress(function(keyDesc, autoRepeatTicks) end)

Key press event.

Returns: handle

`onTalk`

onTalk(function(name, level, mode, text, channelId, pos) end)

Chat message event.

Returns: handle

`listen`

listen(name, function(text, channelId, pos) end)

onTalk filtered by speaker name.

Returns: handle

`onTextMessage`

onTextMessage(function(mode, text) end)

Text message event.

Returns: handle

`onPlayerPositionChange`

onPlayerPositionChange(function(newPos, oldPos) end)

Local player position event.

Returns: handle

`onPlayerHealthChange`

onPlayerHealthChange(function(healthPercent) end)

Local player health event.

Returns: handle

`onPlayerInventoryChange`

onPlayerInventoryChange(function(slot, item, oldItem) end)

Local player inventory event.

Returns: handle

`onCreatureAppear`

onCreatureAppear(function(creature) end)

Creature appear event.

Returns: handle

`onCreatureDisappear`

onCreatureDisappear(function(creature) end)

Creature disappear event.

Returns: handle

`onCreaturePositionChange`

onCreaturePositionChange(function(creature, newPos, oldPos) end)

Creature movement event.

Returns: handle

`onCreatureHealthPercentChange`

onCreatureHealthPercentChange(function(creature, percent) end)

Creature health percent event.

Returns: handle

`onAttackingCreatureChange`

onAttackingCreatureChange(function(creature, oldCreature) end)

Attack target change event.

Returns: handle

`onTurn`

onTurn(function(creature, direction) end)

Creature turn event.

Returns: handle

`onWalk`

onWalk(function(creature, oldPos, newPos) end)

Creature walk event.

Returns: handle

`onUse`

onUse(function(pos, itemId, stackPos, subType) end)

Use action event.

Returns: handle

`onUseWith`

onUseWith(function(pos, itemId, target, subType) end)

Use-with action event.

Returns: handle

`onContainerOpen`

onContainerOpen(function(container, previous) end)

Container open event.

Returns: handle

`onContainerClose`

onContainerClose(function(container) end)

Container close event.

Returns: handle

`onContainerUpdateItem`

onContainerUpdateItem(function(container, slot, item, oldItem) end)

Container slot update event.

Returns: handle

`onAddItem`

onAddItem(function(container, slot, item) end)

Container item added event.

Returns: handle

`onRemoveItem`

onRemoveItem(function(container, slot, item) end)

Container item removed event.

Returns: handle

`onManaChange`

onManaChange(function(player, mana, maxMana, oldMana, oldMaxMana) end)

Mana change event.

Returns: handle

`onStatesChange`

onStatesChange(function(player, states, oldStates) end)

Player states change event.

Returns: handle

`onInventoryChange`

onInventoryChange(function(player, slot, item, oldItem) end)

Inventory slot change event.

Returns: handle

`onSpellCooldown`

onSpellCooldown(function(spellId, delay) end)

Spell cooldown event.

Returns: handle

`onGroupSpellCooldown`

onGroupSpellCooldown(function(groupId, delay) end)

Group cooldown event.

Returns: handle

`onModalDialog`

onModalDialog(function(id, title, message, buttons, enter, escape, choices, priority) end)

Modal dialog event.

Returns: handle

`onAddThing`

onAddThing(function(tile, thing) end)

Thing added to tile event.

Returns: handle

`onRemoveThing`

onRemoveThing(function(tile, thing) end)

Thing removed from tile event.

Returns: handle

`onMissle`

onMissle(function(missile) end)

Missile event.

Returns: handle

`onAnimatedText`

onAnimatedText(function(...) end)

Animated text event.

Returns: handle

`onStaticText`

onStaticText(function(...) end)

Static text event.

Returns: handle

`onChannelList`

onChannelList(function(...) end)

Channel list event.

Returns: handle

`onOpenChannel`

onOpenChannel(function(...) end)

Open channel event.

Returns: handle

`onCloseChannel`

onCloseChannel(function(...) end)

Close channel event.

Returns: handle

`onChannelEvent`

onChannelEvent(function(...) end)

Channel event.

Returns: handle

`onLoginAdvice`

onLoginAdvice(function(message) end)

Login advice event.

Returns: handle

`onImbuementWindow`

onImbuementWindow(function(...) end)

Imbuement window event.

Returns: handle

`onGameEditText`

onGameEditText(function(...) end)

Game edit text event.

Returns: handle

API REFERENCE

NPC And Bot Controls

NPC trade helpers and simple bot toggles.

NPC.talkNPC.isTradingNPC.getSellItemsNPC.getBuyItemsNPC.getSellQuantityNPC.canTradeItemNPC.sellNPC.buyNPC.sellAllNPC.closeTradeCaveBot.setOnCaveBot.setOffCaveBot.isOnCaveBot.isOffCaveBot.delayTargetBot.setOnTargetBot.setOffTargetBot.isOnTargetBot.isOffBotServer.initBotServer.terminateBotServer.listenBotServer.sendBotServer.isConnectedBotServer.hasListenBotServer.resetReconnect

`NPC.talk`

NPC.talk(text)

Sends NPC chat.

Returns: nil
Aliases: NPC.say

`NPC.isTrading`

NPC.isTrading()

True when NPC trade is open.

Returns: boolean
Aliases: NPC.hasTrade, NPC.hasTradeWindow, NPC.isTradeOpen

`NPC.getSellItems`

NPC.getSellItems()

Returns current NPC sell items.

Returns: table

`NPC.getBuyItems`

NPC.getBuyItems()

Returns current NPC buy items.

Returns: table

`NPC.getSellQuantity`

NPC.getSellQuantity(itemOrId)

Returns sellable amount.

Returns: number

`NPC.canTradeItem`

NPC.canTradeItem(itemOrId)

Checks whether the item can be traded.

Returns: boolean

`NPC.sell`

NPC.sell(itemOrId, count, ignoreEquipped)

Sells an item.

Returns: boolean

`NPC.buy`

NPC.buy(itemOrId, count, ignoreCapacity, withBackpack)

Buys an item.

Returns: boolean

`NPC.sellAll`

NPC.sellAll()

Runs sell all.

Returns: boolean

`NPC.closeTrade`

NPC.closeTrade()

Closes NPC trade.

Returns: boolean
Aliases: NPC.close, NPC.finish, NPC.endTrade, NPC.finishTrade

`CaveBot.setOn`

CaveBot.setOn()

Enables CaveBot.

Returns: boolean

`CaveBot.setOff`

CaveBot.setOff()

Disables CaveBot.

Returns: boolean

`CaveBot.isOn`

CaveBot.isOn()

True when CaveBot is enabled.

Returns: boolean

`CaveBot.isOff`

CaveBot.isOff()

True when CaveBot is disabled.

Returns: boolean

`CaveBot.delay`

CaveBot.delay(durationMs)

Alias for delay.

Returns: nil

`TargetBot.setOn`

TargetBot.setOn()

Enables TargetBot.

Returns: boolean

`TargetBot.setOff`

TargetBot.setOff()

Disables TargetBot.

Returns: boolean

`TargetBot.isOn`

TargetBot.isOn()

True when TargetBot is enabled.

Returns: boolean

`TargetBot.isOff`

TargetBot.isOff()

True when TargetBot is disabled.

Returns: boolean

`BotServer.init`

BotServer.init(name, channel)

Connects to the bot server.

Returns: boolean|nil

`BotServer.terminate`

BotServer.terminate()

Disconnects and clears listeners.

Returns: boolean

`BotServer.listen`

BotServer.listen(topic, callback)

Listens to a bot server topic.

Returns: boolean|nil

`BotServer.send`

BotServer.send(topic, message)

Sends a bot server message.

Returns: boolean|nil

`BotServer.isConnected`

BotServer.isConnected()

Connection status.

Returns: boolean

`BotServer.hasListen`

BotServer.hasListen(topic)

Checks whether a topic has listeners.

Returns: boolean

`BotServer.resetReconnect`

BotServer.resetReconnect()

Stops reconnect attempts.

Returns: boolean

API REFERENCE

Utility

Small helpers for text, tables, dialogs, screenshots, sounds, and status messages.

getDistanceBetweengetFirstNumberInTextrelogOnCharacterburstDamageValuereindexTablewhiteInfoMessagestatusMessagebroadcastMessagedisplayGeneralBoxdoScreenshotgetVersiongetSoundChannelmauSoundExistsplaySoundstopSoundplayAlarmpingteststring.explodestring.startstable.findtable.isList

`getDistanceBetween`

getDistanceBetween(p1, p2)

Chebyshev distance between two positions.

Returns: number

`getFirstNumberInText`

getFirstNumberInText(text)

Returns the first integer in text.

Returns: number|nil

`relogOnCharacter`

relogOnCharacter(namePart)

Attempts to login a character matching text.

Returns: boolean|nil

`burstDamageValue`

burstDamageValue()

Recent incoming damage per second estimate.

Returns: number

`reindexTable`

reindexTable(values)

Assigns sequential index fields to table entries.

Returns: table|nil

`whiteInfoMessage`

whiteInfoMessage(text)

Displays a white game message or logs info.

Returns: nil

`statusMessage`

statusMessage(text, logInConsole)

Displays a status/failure message or logs info.

Returns: nil

`broadcastMessage`

broadcastMessage(text)

Displays a broadcast message or warning.

Returns: nil

`displayGeneralBox`

displayGeneralBox(title, message, buttons, onEnter, onEscape)

Shows a dialog when available.

Returns: mixed

`doScreenshot`

doScreenshot(filename)

Takes a screenshot.

Returns: boolean
Aliases: screenshot

`getVersion`

getVersion()

Runtime version string.

Returns: string

`getSoundChannel`

getSoundChannel()

Bot sound channel.

Returns: channel|nil

`mauSoundExists`

mauSoundExists(file)

Checks whether a sound file exists.

Returns: boolean

`playSound`

playSound(file)

Plays a sound.

Returns: mixed

`stopSound`

stopSound()

Stops sound playback.

Returns: mixed

`playAlarm`

playAlarm()

Plays the alarm sound.

Returns: mixed

`ping`

ping()

Current ping.

Returns: number

`test`

test()

Writes test to the info log.

Returns: nil

`string.explode`

string.explode(text, separator)

Splits text by separator.

Returns: table
Aliases: string.split

`string.starts`

string.starts(text, prefix)

Checks a text prefix.

Returns: boolean

`table.find`

table.find(list, value, ignoreCase)

Finds a value in a table.

Returns: key|nil
Aliases: table.contains

`table.isList`

table.isList(value)

True for sequential numeric tables.

Returns: boolean

CONSTANTS

Directions

Named values available in your macro context.

North0

East1

South2

West3

NorthEast4

SouthEast5

SouthWest6

NorthWest7

CONSTANTS

Inventory Slots

Named values available in your macro context.

SlotOther0

SlotHead1

SlotNeck2

SlotBack3

SlotBody4

SlotRight5

SlotLeft6

SlotLeg7

SlotFeet8

SlotFinger9

SlotAmmo10

SlotPurse11

InventorySlotFirst1

InventorySlotLast10

CONSTANTS

PlayerStates

Named values available in your macro context.

PlayerStates.Poison1

PlayerStates.Burn2

PlayerStates.Energy4

PlayerStates.Drunk8

PlayerStates.ManaShield16

PlayerStates.Paralyze32

PlayerStates.Haste64

PlayerStates.Swords128

PlayerStates.Drowning256

PlayerStates.Freezing512

PlayerStates.Dazzled1024

PlayerStates.Cursed2048

PlayerStates.PartyBuff4096

PlayerStates.PzBlock8192

PlayerStates.Pz16384

PlayerStates.Bleeding32768

PlayerStates.Hungry65536

PlayerStates.Rooted524288

PlayerStates.Feared1048576

PlayerStates.NewManaShield67108864

PlayerStates.Agony134217728

SEARCH