Reference Overview

Macro Context

Clean reference for writing Mau Lua macros.

Choose a category from the left menu. Each view keeps the page focused on one task.

321 API entries
10 Examples
43 Constants

Lua

Examples

Small patterns for the most common macro tasks.

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

Runtime

State and logging values available in every macro file.

storage
storage[key]

Persistent table saved per character and config.

table
configName
configName

Current macro config name.

string
configDir
configDir

Full path to the current macro config folder.

string
now
now

Current macro timestamp in milliseconds.

number
time
time

Alias for now.

number
player
player

Current local player object.

LocalPlayer
panel
panel

Current panel used by UI helpers.

widget
mainTab
mainTab

Main macro panel tab.

widget
MauBot
MauBot

Shared compatibility state table.

table
vBot
vBot

Alias for MauBot.

table
saveConfig
saveConfig()

Marks storage for saving.

nil
reload
reload()

Reloads the current config.

boolean
info
info(text)

Writes to the macro info log.

nil
warn Aliases: warning
warn(text)

Writes to the macro warning log.

nil
error
error(text)

Writes to the macro error log.

nil
logInfo
logInfo(text)

Writes a terminal-style info line.

nil
standTime
standTime()

Milliseconds since the local player last moved.

number
schedule
schedule(timeoutMs, callback)

Runs callback once after the delay.

nil
delay
delay(durationMs)

Pauses the current macro, hotkey, or event callback.

nil

API

Macros

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

macro
macro(timeoutMs, name, callback)

Creates a named macro row.

macro
macro
macro(timeoutMs, name, hotkey, callback)

Creates a named macro row with a hotkey label.

macro
macro
macro(timeoutMs, callback)

Creates a background macro without a row.

macro
macro:isOn
macro:isOn()

True when enabled.

boolean
macro:isOff
macro:isOff()

True when disabled.

boolean
macro:setOn
macro:setOn([value])

Enables the macro. Passing false disables it.

nil
macro:setOff
macro:setOff([value])

Disables the macro. Passing false enables it.

nil
macro:toggle
macro:toggle()

Toggles enabled state.

nil
macro:setTooltip
macro:setTooltip(text)

Sets the row tooltip.

macro
macro:setHotkey
macro:setHotkey(combo)

Updates the displayed hotkey combo.

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

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

macro
macro:openSetup
macro:openSetup()

Opens the setup window.

macro
hotkey
hotkey(keys, name, callback)

Runs callback when the key combo is pressed.

hotkey
singlehotkey
singlehotkey(keys, name, callback)

Hotkey variant for single key-down actions.

hotkey
hotkey:setTooltip
hotkey:setTooltip(text)

Sets the row tooltip.

hotkey
hotkey:setHotkey
hotkey:setHotkey(combo)

Changes the key combo if it is not duplicated.

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

Adds a setup button to the hotkey row.

hotkey
hotkey:openSetup
hotkey:openSetup()

Opens the setup window.

hotkey
addIcon
addIcon(id, options, callbackOrMacro)

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

widget

API

UI

Build controls in the macro panel or inside setSetup.

addTab Aliases: getTab
addTab(name)

Creates or selects a macro panel tab.

panel
setDefaultTab
setDefaultTab(name)

Sets where future UI helpers place widgets.

panel
setupUI
setupUI(otml, parent)

Loads an OTML widget string into a panel.

widget
createWidget
createWidget(name, parent)

Creates and tracks a widget.

widget
addSwitch
addSwitch(id, text, onClick, parent)

Creates a switch row.

widget
addButton
addButton(id, text, onClick, parent)

Creates a button.

widget
addLabel
addLabel(id, text, parent)

Creates a label.

widget
addTextEdit
addTextEdit(id, text, onTextChange, parent)

Creates a text input. Callback receives widget and text.

widget
addSeparator
addSeparator(id, parent)

Creates a separator.

widget
UI.Section
UI.Section(title, parent)

Creates a setup section header.

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

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

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

Same as UI.Field, intended for numeric values.

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

Creates a key combo capture field.

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

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

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

Creates icon item and icon text fields.

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

Creates an item list editor with setItems and getItems.

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

Creates a labeled item list editor.

widget
UI.Label
UI.Label(text, parent)

Creates a label with automatic id.

widget
UI.Button
UI.Button(text, callback, parent)

Creates a button with automatic id.

widget
UI.TextEdit
UI.TextEdit(text, callback, parent)

Creates a text edit with automatic id.

widget
UI.Separator
UI.Separator(parent)

Creates a separator with automatic id.

widget
UI.EditorWindow
UI.EditorWindow(text, options, callback)

Opens an editor window.

window
UI.SinglelineEditorWindow
UI.SinglelineEditorWindow(text, options, callback)

Opens a single-line editor.

window
UI.MultilineEditorWindow
UI.MultilineEditorWindow(text, options, callback)

Opens a multiline editor.

window
UI.ConfirmationWindow
UI.ConfirmationWindow(title, question, callback)

Opens a yes/no confirmation window.

window
UI.createWidget
UI.createWidget(name, parent)

Creates and tracks a widget.

widget
UI.createWindow
UI.createWindow(name, parent)

Creates, shows, raises, and focuses a window.

window
UI.createMiniWindow
UI.createMiniWindow(name, parent)

Creates a mini window.

window
UI.Config
UI.Config(parent)

Creates a small config panel.

panel
UI.DualScrollPanel
UI.DualScrollPanel(params, callback, parent)

Creates a two-slider percent range control.

widget
UI.DualScrollItemPanel
UI.DualScrollItemPanel(params, callback, parent)

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

widget
UI.TwoItemsAndSlotPanel
UI.TwoItemsAndSlotPanel(params, callback, parent)

Creates a two-item and slot selector panel.

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

Creates a left/right label row.

widget
UI.LabelAndTextEdit
UI.LabelAndTextEdit(params, callback, parent)

Creates a label plus text input row.

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

Creates a switch plus button row.

widget
Panels.AttackLeaderTarget
Panels.AttackLeaderTarget(parent)

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

nil

API

Player

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

name
name()

Character name.

string
hp
hp()

Current health.

number
maxhp Aliases: hpmax
maxhp()

Maximum health.

number
hppercent
hppercent()

Current health percent.

number
mana
mana()

Current mana.

number
maxmana Aliases: manamax
maxmana()

Maximum mana.

number
manapercent
manapercent()

Current mana percent.

number
cap
cap()

Current capacity.

number
freecap
freecap()

Free capacity.

number
maxcap Aliases: capmax
maxcap()

Total capacity.

number
exp
exp()

Experience.

number
lvl Aliases: level
lvl()

Level.

number
mlev Aliases: magic, mlevel
mlev()

Magic level.

number
soul
soul()

Soul points.

number
stamina
stamina()

Stamina.

number
voc Aliases: vocation
voc()

Vocation id.

number
bless Aliases: blesses, blessings
bless()

Blessings value.

number
direction
direction()

Facing direction.

number
speed
speed()

Current speed.

number
skull
skull()

Skull value.

number
outfit
outfit()

Current outfit table.

table
setOutfit Aliases: changeOutfit
setOutfit(outfit)

Changes outfit.

boolean|nil
setSpeed
setSpeed(value)

Changes local speed when supported.

boolean
hasCondition
hasCondition(condition)

Checks a PlayerStates flag.

boolean
isPoisoned Aliases: isPoisioned
isPoisoned()

Poison condition.

boolean
isBurning
isBurning()

Burn condition.

boolean
isEnergized
isEnergized()

Energy condition.

boolean
isDrunk
isDrunk()

Drunk condition.

boolean
hasManaShield
hasManaShield()

Mana shield condition.

boolean
isParalyzed
isParalyzed()

Paralyze condition.

boolean
hasHaste
hasHaste()

Haste condition.

boolean
hasSwords Aliases: isInFight
hasSwords()

In-fight condition.

boolean
canLogout
canLogout()

True when not in fight.

boolean
isInProtectionZone Aliases: hasPz, isInPz
isInProtectionZone()

Protection zone condition.

boolean
hasPzLock Aliases: hasPzBlock, isPzLocked, isPzBlocked
hasPzLock()

PZ lock/block condition.

boolean
isDrowning
isDrowning()

Drowning condition.

boolean
isFreezing
isFreezing()

Freezing condition.

boolean
isDazzled
isDazzled()

Dazzled condition.

boolean
isCursed
isCursed()

Cursed condition.

boolean
hasPartyBuff
hasPartyBuff()

Party buff condition.

boolean
isBleeding
isBleeding()

Bleeding condition.

boolean
isHungry
isHungry()

Hungry condition.

boolean
isBuffed
isBuffed()

Checks active party buff effect.

boolean
killsToRs
killsToRs()

Remaining unjustified kills before red skull.

number

API

Movement

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

pos
pos()

Current player position.

position
posx
posx()

Current x coordinate.

number
posy
posy()

Current y coordinate.

number
posz
posz()

Current floor.

number
getPos
getPos(x, y, z)

Builds a position table.

position|nil
walk
walk(direction)

Walks one direction.

boolean
turn
turn(direction)

Turns to a direction.

boolean
findAllPaths Aliases: findEveryPath
findAllPaths(start, maxDist, params)

Finds reachable path nodes.

table|nil
translateAllPathsToPath Aliases: translateEveryPathToPath
translateAllPathsToPath(paths, destPos)

Converts path nodes into directions.

table|nil
findPath Aliases: getPath
findPath(startPos, destPos, maxDist, params)

Finds directions to a destination.

table|nil
autoWalk
autoWalk(destination, maxDist, params)

Walks to a destination or along a direction list.

boolean
distanceFromPlayer
distanceFromPlayer(coords, fromPos)

Chebyshev distance from player or another position.

number|false
getMapView Aliases: getMapPanel
getMapView()

Returns the map panel.

widget|nil
zoomIn
zoomIn()

Zooms map panel in.

nil
zoomOut
zoomOut()

Zooms map panel out.

nil

API

Combat And Speech

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

attack
attack(creature)

Attacks a creature.

nil
cancelAttack
cancelAttack()

Stops attacking.

nil
follow
follow(creature)

Follows a creature.

nil
cancelFollow
cancelFollow()

Stops following.

nil
cancelAttackAndFollow
cancelAttackAndFollow()

Stops attack and follow.

nil
target Aliases: getTarget
target()

Current attack target.

creature|nil
targetPos
targetPos([distance])

Target position, or distance when distance is true.

position|number|nil
say Aliases: talk
say(text)

Sends normal chat.

nil
sayNpc Aliases: talkNpc, sayNPC, talkNPC
sayNpc(text)

Sends NPC chat.

nil
yell
yell(text)

Sends yell chat.

nil
talkChannel Aliases: sayChannel
talkChannel(channelId, text)

Sends channel chat.

nil
talkPrivate Aliases: sayPrivate
talkPrivate(receiver, text)

Sends private chat.

nil
getChannels
getChannels()

Returns known channels.

table
getChannelId Aliases: getChannel
getChannelId(name)

Finds a channel id by name.

number|nil
saySpell
saySpell(text, timeoutMs)

Says spell words if timeout passed.

boolean
setSpellTimeout
setSpellTimeout()

Updates the local spell timeout.

nil
getSpellData
getSpellData(spell)

Returns spell data by words or name.

table|false
getSpellCoolDown
getSpellCoolDown(text)

True when spell or group cooldown is active.

boolean
canCast
canCast(spell, ignoreRL, ignoreCd)

Checks cooldown, level, and mana when data exists.

boolean
cast
cast(text, delayMs)

Says text with a local cooldown.

boolean|nil
castSpell
castSpell(text)

Casts only when canCast returns true.

boolean|nil
useRune Aliases: userune
useRune(itemId, target, timeoutMs)

Uses a rune item on a target with local timeout.

boolean
scheduleNpcSay
scheduleNpcSay(text, delayMs)

Schedules an NPC message.

nil|false
isAttSpell
isAttSpell(text)

True when text starts with exori or exevo.

boolean

API

Items

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

use
use(thingOrItemId, subtype)

Uses an item, thing, or inventory item id.

mixed
usewith Aliases: useWith
usewith(thingOrItemId, target, subtype)

Uses an item on a target.

mixed
findItem
findItem(itemId, subType)

Finds an item in open containers or inventory.

item|nil
itemAmount
itemAmount(itemId)

Counts player items by id.

number
getContainers
getContainers()

Returns open containers.

table
getContainer
getContainer(index)

Returns a container by index.

container|nil
getContainerByName
getContainerByName(name, notFull)

Finds an open container by exact name.

container|nil
getContainerByItem
getContainerByItem(itemId, notFull)

Finds an open container by container item id.

container|nil
containerIsFull
containerIsFull(container)

Checks whether a container is full.

boolean
getInventoryItem Aliases: getSlot
getInventoryItem(slot)

Returns the item in an inventory slot.

item|nil
getHead
getHead()

Head slot item.

item|nil
getNeck
getNeck()

Neck slot item.

item|nil
getBack
getBack()

Backpack slot item.

item|nil
getBody
getBody()

Body slot item.

item|nil
getRight
getRight()

Right hand slot item.

item|nil
getLeft
getLeft()

Left hand slot item.

item|nil
getLeg
getLeg()

Leg slot item.

item|nil
getFeet
getFeet()

Feet slot item.

item|nil
getFinger
getFinger()

Ring slot item.

item|nil
getAmmo
getAmmo()

Ammo slot item.

item|nil
getPurse
getPurse()

Purse slot item.

item|nil
openPurse
openPurse()

Uses the purse slot item.

boolean|nil
reopenPurse
reopenPurse()

Reopens purse-related containers.

boolean|nil
moveToSlot
moveToSlot(itemOrId, slot, count)

Moves an item to an inventory slot.

boolean|nil
dropItem
dropItem(itemOrId)

Drops an item on the player position.

boolean|nil
getActiveItemId
getActiveItemId(id)

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

number|false
getInactiveItemId
getInactiveItemId(id)

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

number|false
getNearTiles
getNearTiles(positionOrCreature)

Returns the eight neighboring tiles.

table
findItemOnGround
findItemOnGround(itemId)

Finds a visible ground item by id.

item|nil
isOnTile
isOnTile(itemId, tileOrPos)

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

boolean
useGroundItem
useGroundItem(itemId)

Uses the first visible ground item with id.

boolean|nil
reachGroundItem
reachGroundItem(itemId)

Walks toward the first visible ground item with id.

boolean
useOnGroundItem
useOnGroundItem(toolItemId, groundItemId)

Uses an inventory item on a visible ground item.

boolean|nil
useOnInventoryItem Aliases: useOnInvertoryItem
useOnInventoryItem(toolItemId, targetItemId)

Uses an item on an inventory item.

boolean|nil
getTileUnderCursor
getTileUnderCursor()

Returns the tile under the mouse cursor.

tile|nil
canShoot
canShoot(pos, distance)

Checks if a tile can be shot.

boolean
isTrapped
isTrapped([creature])

True when no neighboring tile is walkable.

boolean

API

Creatures

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

getSpectators
getSpectators([positionOrCreatureOrPattern], [multifloor])

Returns visible spectators.

table
getCreatureById
getCreatureById(id, multifloor)

Finds a visible creature by id.

creature|nil
getCreatureByName
getCreatureByName(name, multifloor)

Finds a visible creature by exact name.

creature|nil
getPlayerByName
getPlayerByName(name, multifloor)

Finds a visible player by exact name.

creature|nil
getMonstersInRange
getMonstersInRange(position, range)

Counts monsters near a position.

number|false
getMonsters
getMonsters(range, multifloor)

Counts monsters around the player.

number
getPlayers
getPlayers(range, multifloor)

Counts nearby non-party players.

number
getAllPlayers
getAllPlayers(range, multifloor)

Counts all nearby non-local players.

number
getNpcs
getNpcs(range, multifloor)

Counts nearby NPCs.

number
getCreaturesInArea
getCreaturesInArea(positionOrPattern, patternOrMultifloor, type)

Counts spectators, monsters, or players in an area.

number
isFriend
isFriend(creatureOrName)

Checks friend list, party, and shared member state.

boolean
isEnemy
isEnemy(creatureOrName)

Checks enemy list, marks, and emblem state.

boolean
getPlayerDistribution
getPlayerDistribution()

Splits visible players into three lists.

friends, neutrals, enemies
getFriends
getFriends()

Returns visible friends.

table
getNeutrals
getNeutrals()

Returns visible neutral players.

table
getEnemies
getEnemies()

Returns visible enemies.

table
isBlackListedPlayerInRange
isBlackListedPlayerInRange(range)

Checks storage.playerList.blackList around the player.

boolean
getBestTileByPattern Aliases: getBestTileByPatern
getBestTileByPattern(pattern, specType, maxDist, safe)

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

table|false
isSafe
isSafe(range, multifloor, padding)

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

boolean

API

Files And Config

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

load Aliases: loadstring
load(source)

Loads Lua source in the macro context.

function
dofile
dofile(relativePath)

Runs a Lua file from the current config folder.

mixed
dofiles
dofiles(path)

Runs all Lua files in a config subfolder recursively.

nil
loadScript
loadScript(pathOrUrl, onLoad)

Loads a local or remote script.

mixed
loadRemoteScript
loadRemoteScript(url, onLoad)

Downloads and runs a remote script.

nil
importStyle
importStyle(otuiPathOrString)

Imports an OTUI style from file or string.

mixed
fileExists Aliases: mauFileExists
fileExists(path)

Checks whether a mapped macro file exists.

boolean
encode
encode(data, indent)

Serializes data to text.

string
decode
decode(text)

Parses serialized text. Returns empty table on failure.

table
Config.exist
Config.exist(dir)

Checks whether a config directory exists.

boolean
Config.create
Config.create(dir)

Creates a config directory.

boolean
Config.list
Config.list(dir)

Lists config names in a directory.

table
Config.parse
Config.parse(data)

Parses saved config text.

table
Config.load
Config.load(dir, name)

Loads a saved config.

table|nil
Config.loadRaw
Config.loadRaw(dir, name)

Loads raw config text.

string|nil
Config.save
Config.save(dir, name, value, forcedExtension)

Saves table data.

boolean
Config.remove
Config.remove(dir, name)

Deletes saved files for a config.

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

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

table|nil

API

Events

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

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

Low-level event registration.

handle
onKeyDown
onKeyDown(function(keyDesc) end)

Key down event.

handle
onKeyUp
onKeyUp(function(keyDesc) end)

Key up event.

handle
onKeyPress
onKeyPress(function(keyDesc, autoRepeatTicks) end)

Key press event.

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

Chat message event.

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

onTalk filtered by speaker name.

handle
onTextMessage
onTextMessage(function(mode, text) end)

Text message event.

handle
onPlayerPositionChange
onPlayerPositionChange(function(newPos, oldPos) end)

Local player position event.

handle
onPlayerHealthChange
onPlayerHealthChange(function(healthPercent) end)

Local player health event.

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

Local player inventory event.

handle
onCreatureAppear
onCreatureAppear(function(creature) end)

Creature appear event.

handle
onCreatureDisappear
onCreatureDisappear(function(creature) end)

Creature disappear event.

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

Creature movement event.

handle
onCreatureHealthPercentChange
onCreatureHealthPercentChange(function(creature, percent) end)

Creature health percent event.

handle
onAttackingCreatureChange
onAttackingCreatureChange(function(creature, oldCreature) end)

Attack target change event.

handle
onTurn
onTurn(function(creature, direction) end)

Creature turn event.

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

Creature walk event.

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

Use action event.

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

Use-with action event.

handle
onContainerOpen
onContainerOpen(function(container, previous) end)

Container open event.

handle
onContainerClose
onContainerClose(function(container) end)

Container close event.

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

Container slot update event.

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

Container item added event.

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

Container item removed event.

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

Mana change event.

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

Player states change event.

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

Inventory slot change event.

handle
onSpellCooldown
onSpellCooldown(function(spellId, delay) end)

Spell cooldown event.

handle
onGroupSpellCooldown
onGroupSpellCooldown(function(groupId, delay) end)

Group cooldown event.

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

Modal dialog event.

handle
onAddThing
onAddThing(function(tile, thing) end)

Thing added to tile event.

handle
onRemoveThing
onRemoveThing(function(tile, thing) end)

Thing removed from tile event.

handle
onMissle
onMissle(function(missile) end)

Missile event.

handle
onAnimatedText
onAnimatedText(function(...) end)

Animated text event.

handle
onStaticText
onStaticText(function(...) end)

Static text event.

handle
onChannelList
onChannelList(function(...) end)

Channel list event.

handle
onOpenChannel
onOpenChannel(function(...) end)

Open channel event.

handle
onCloseChannel
onCloseChannel(function(...) end)

Close channel event.

handle
onChannelEvent
onChannelEvent(function(...) end)

Channel event.

handle
onLoginAdvice
onLoginAdvice(function(message) end)

Login advice event.

handle
onImbuementWindow
onImbuementWindow(function(...) end)

Imbuement window event.

handle
onGameEditText
onGameEditText(function(...) end)

Game edit text event.

handle

API

NPC And Bot Controls

NPC trade helpers and simple bot toggles.

NPC.talk Aliases: NPC.say
NPC.talk(text)

Sends NPC chat.

nil
NPC.isTrading Aliases: NPC.hasTrade, NPC.hasTradeWindow, NPC.isTradeOpen
NPC.isTrading()

True when NPC trade is open.

boolean
NPC.getSellItems
NPC.getSellItems()

Returns current NPC sell items.

table
NPC.getBuyItems
NPC.getBuyItems()

Returns current NPC buy items.

table
NPC.getSellQuantity
NPC.getSellQuantity(itemOrId)

Returns sellable amount.

number
NPC.canTradeItem
NPC.canTradeItem(itemOrId)

Checks whether the item can be traded.

boolean
NPC.sell
NPC.sell(itemOrId, count, ignoreEquipped)

Sells an item.

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

Buys an item.

boolean
NPC.sellAll
NPC.sellAll()

Runs sell all.

boolean
NPC.closeTrade Aliases: NPC.close, NPC.finish, NPC.endTrade, NPC.finishTrade
NPC.closeTrade()

Closes NPC trade.

boolean
CaveBot.setOn
CaveBot.setOn()

Enables CaveBot.

boolean
CaveBot.setOff
CaveBot.setOff()

Disables CaveBot.

boolean
CaveBot.isOn
CaveBot.isOn()

True when CaveBot is enabled.

boolean
CaveBot.isOff
CaveBot.isOff()

True when CaveBot is disabled.

boolean
CaveBot.delay
CaveBot.delay(durationMs)

Alias for delay.

nil
TargetBot.setOn
TargetBot.setOn()

Enables TargetBot.

boolean
TargetBot.setOff
TargetBot.setOff()

Disables TargetBot.

boolean
TargetBot.isOn
TargetBot.isOn()

True when TargetBot is enabled.

boolean
TargetBot.isOff
TargetBot.isOff()

True when TargetBot is disabled.

boolean
BotServer.init
BotServer.init(name, channel)

Connects to the bot server.

boolean|nil
BotServer.terminate
BotServer.terminate()

Disconnects and clears listeners.

boolean
BotServer.listen
BotServer.listen(topic, callback)

Listens to a bot server topic.

boolean|nil
BotServer.send
BotServer.send(topic, message)

Sends a bot server message.

boolean|nil
BotServer.isConnected
BotServer.isConnected()

Connection status.

boolean
BotServer.hasListen
BotServer.hasListen(topic)

Checks whether a topic has listeners.

boolean
BotServer.resetReconnect
BotServer.resetReconnect()

Stops reconnect attempts.

boolean

API

Utility

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

getDistanceBetween
getDistanceBetween(p1, p2)

Chebyshev distance between two positions.

number
getFirstNumberInText
getFirstNumberInText(text)

Returns the first integer in text.

number|nil
relogOnCharacter
relogOnCharacter(namePart)

Attempts to login a character matching text.

boolean|nil
burstDamageValue
burstDamageValue()

Recent incoming damage per second estimate.

number
reindexTable
reindexTable(values)

Assigns sequential index fields to table entries.

table|nil
whiteInfoMessage
whiteInfoMessage(text)

Displays a white game message or logs info.

nil
statusMessage
statusMessage(text, logInConsole)

Displays a status/failure message or logs info.

nil
broadcastMessage
broadcastMessage(text)

Displays a broadcast message or warning.

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

Shows a dialog when available.

mixed
doScreenshot Aliases: screenshot
doScreenshot(filename)

Takes a screenshot.

boolean
getVersion
getVersion()

Runtime version string.

string
getSoundChannel
getSoundChannel()

Bot sound channel.

channel|nil
mauSoundExists
mauSoundExists(file)

Checks whether a sound file exists.

boolean
playSound
playSound(file)

Plays a sound.

mixed
stopSound
stopSound()

Stops sound playback.

mixed
playAlarm
playAlarm()

Plays the alarm sound.

mixed
ping
ping()

Current ping.

number
test
test()

Writes test to the info log.

nil
string.explode Aliases: string.split
string.explode(text, separator)

Splits text by separator.

table
string.starts
string.starts(text, prefix)

Checks a text prefix.

boolean
table.find Aliases: table.contains
table.find(list, value, ignoreCase)

Finds a value in a table.

key|nil
table.isList
table.isList(value)

True for sequential numeric tables.

boolean

Constants

Directions

Values exposed in the macro context.

North 0
East 1
South 2
West 3
NorthEast 4
SouthEast 5
SouthWest 6
NorthWest 7

Constants

Inventory Slots

Values exposed in the macro context.

SlotOther 0
SlotHead 1
SlotNeck 2
SlotBack 3
SlotBody 4
SlotRight 5
SlotLeft 6
SlotLeg 7
SlotFeet 8
SlotFinger 9
SlotAmmo 10
SlotPurse 11
InventorySlotFirst 1
InventorySlotLast 10

Constants

PlayerStates

Values exposed in the macro context.

PlayerStates.Poison 1
PlayerStates.Burn 2
PlayerStates.Energy 4
PlayerStates.Drunk 8
PlayerStates.ManaShield 16
PlayerStates.Paralyze 32
PlayerStates.Haste 64
PlayerStates.Swords 128
PlayerStates.Drowning 256
PlayerStates.Freezing 512
PlayerStates.Dazzled 1024
PlayerStates.Cursed 2048
PlayerStates.PartyBuff 4096
PlayerStates.PzBlock 8192
PlayerStates.Pz 16384
PlayerStates.Bleeding 32768
PlayerStates.Hungry 65536
PlayerStates.Rooted 524288
PlayerStates.Feared 1048576
PlayerStates.NewManaShield 67108864
PlayerStates.Agony 134217728