API Reference

Looks up a recorded Razor macro (case-insensitive name match) and plays it. Returns false with a warning if no macro with that name exists. Returns: true if the macro was found and started, false otherwise.

if not ExecuteMacro('BankRun') then
    Messages.Warning('Macro missing!')
end

The argument must be a plain file name (no paths, no '..'); the '.lua' extension is added automatically. The imported script runs in the same environment, so its global functions and variables become available. Returns the imported script's first return value, if any. Returns: The imported script's return value, or nothing.

-- loads helpers.lua from the same scripts folder
local lib = Import('helpers')

While paused, the engine automatically pumps Script-UI callbacks and bindings in 50 ms slices, so button clicks and bound labels keep working during the wait. Use this between game actions instead of busy loops.

Player.Say('Starting...')
Pause(1000)
Player.Say('One second later.')

Accepts any number of arguments (strings, numbers, booleans, tables); they are joined with tabs. Handy for quick debugging.

print('Hits:', Player.Hits, 'of', Player.HitsMax)

Cancels script execution. Any open Script-UI windows are destroyed when the script ends. Returns: true

if Player.IsDead then
    Messages.Error('Player died - stopping.')
    StopScript()
end

Registered by the assistant, but not documented yet.

Console.clear()

Registered by the assistant, but not documented yet.

Console.debug('state = idle')

Registered by the assistant, but not documented yet.

Console.error('target not found')

Registered by the assistant, but not documented yet.

Console.info('found ' .. 3 .. ' corpses')

Unlike print, Console output goes only to the debug console, not to the in-game message area.

Console.log('loot pass started')

Registered by the assistant, but not documented yet.

Console.warn('backpack almost full')

The serial must belong to a mobile; item serials are rejected. Returns: true on success, false otherwise.

local enemy = Mobiles.FindByName('a lich')
if enemy then
    Player.Attack(enemy.Serial)
end

Accepts 'left', 'right' or 'both'. Items blocked by the pickup filter are not moved. With 'both', a short delay is inserted between the two moves. Returns: true on success, false otherwise.

Player.ClearHands('both')
Pause(600)
Spells.Cast('Recall')

Triggers the object's name/properties display, just like a manual single click. Returns: true on success, false if the serial is invalid.

Player.ClickObject(0x40001234)

Works on the item lifted by Player.PickUp (including one still queued for lifting). Returns false if you are not holding an item. Returns: true on success, false otherwise.

Player.PickUp(0x40001234)
Pause(600)
Player.DropInBackpack()

The container may be inside your backpack (searched recursively), on the ground within 2 tiles, or a nearby mobile (its backpack is used, e.g. a pack horse). Returns false if no container is found or nothing is held. Returns: true on success, false otherwise.

Player.PickUp(0x40001234)
Pause(600)
Player.DropInContainer(0x40005678)

Returns: true on success, false if nothing is held.

Player.PickUp(0x40001234)
Pause(600)
Player.DropOnGround()

Returns false if the serial is invalid or the item type is blocked from assistant pickup. Returns: true on success, false otherwise.

local sword = Items.FindByType(0x0F5E)
if sword then
    Player.Equip(sword.Serial)
end

Follow up with Player.DropInBackpack, Player.DropInContainer or Player.DropOnGround. Amount defaults to 1. Items blocked by the pickup filter cannot be lifted. Returns: true on success, false otherwise.

local gold = Items.FindByType(0x0EED)
if gold then
    Player.PickUp(gold.Serial, gold.Amount)
    Pause(600)
    Player.DropInBackpack()
end

Finds a trapped pouch (graphic 0x0E79, hue 0x0025) in your backpack and double-clicks it. Returns false if you are dead or no trapped pouch is found. Returns: true on success, false otherwise.

if Player.IsParalyzed then
    Player.PopPouch()
end

With only the text argument, speaks normally. Optional hue, message type and font can be passed for advanced use. Returns: true on success, false on error.

Player.Say('bank')

Returns: true on success, false on error.

Player.SayAlliance('Meet at the moongate.')

Returns: true on success, false on error.

Player.SayChat('hello')

Returns: true on success, false on error.

Player.SayEmote('waves')

Returns: true on success, false on error.

Player.SayGuild('Rare spawn up!')

Returns: true on success, false on error.

Player.SayParty('Healing in 3 seconds!')

Returns: true on success, false on error.

Player.SayWhisper('psst')

Returns: true on success, false on error.

Player.SayYell('Guards!')

Returns: true on success, false on error.

Player.ToggleWarMode()

Direction is a name like 'North', 'East', 'Down' etc. The call is rate-limited (about 200 ms mounted, 400 ms on foot) and returns false when called too quickly. If you already face that direction, nothing happens. Returns: true on success, false if rate-limited or the name is invalid.

Player.Turn('North')

Returns false if the serial does not exist in the game world, or if the item type is blocked by the shard's scripting restrictions. Returns: true on success, false otherwise.

local bandage = Items.FindByType(0x0E21)
if bandage then
    Player.UseObject(bandage.Serial)
end

Searches your hands first, then your own items, then world items within 2 tiles. Returns false if nothing matches or the type is blocked by scripting restrictions. Returns: true if an item was found and used, false otherwise.

-- use a bandage without searching manually
Player.UseObjectByType(0x0E21)

Sums stack amounts, so 3 stacks of 100 gold return 300. Searches recursively through bags inside your backpack. Returns: total amount as a number (0 if none).

local bandages = Items.CountType(0x0E21)
if bandages < 10 then
    Messages.Warning('Restock bandages!')
end

Returns: total amount as a number (0 if none or container not found).

local ingots = Items.CountTypeInContainer(0x40005678, 0x1BF2)
print('Ingots in chest: ' .. ingots)

The filter is a table; every key is optional and all given conditions must match. Supported keys: graphic (number), graphics (number or list of numbers), hue (number), hues (number or list), rangemin/rangemax (distance in tiles), container (container serial), onground (boolean), corpse (boolean), iscontainer (boolean), movable (boolean), name (substring, case-insensitive), layers (number or list of layer numbers). Returns a Lua array of item tables (empty when nothing matches). Returns: array of item tables (possibly empty).

-- all corpses within 2 tiles
local corpses = Items.FindByFilter({ corpse = true, rangemax = 2 })
for i, corpse in ipairs(corpses) do
    print(i, corpse.Name)
end

Layer is the numeric equipment layer (e.g. 1 = right hand, 2 = left hand, 21 = backpack). Returns nil if the layer is empty. Returns: item table or nil.

local weapon = Items.FindByLayer(1)
if weapon then
    print('Wielding: ' .. weapon.Name)
end

Returns: item table or nil.

local key = Items.FindByName('a house key')
if key then
    Player.UseObject(key.Serial)
end

Returns an item table (see the Item object reference) or nil if the item does not exist or its type is hidden by the shard's scripting restrictions. Returns: item table or nil.

local item = Items.FindBySerial(0x40001234)
if item then
    print(item.Name, item.Amount)
end

Searches your own items first, then the rest of the world. Returns an item table or nil. Returns: item table or nil.

local bandage = Items.FindByType(0x0E21)
if bandage == nil then
    Messages.Warning('Out of bandages!')
end

Accepts a container serial or a mobile serial (its backpack is used). Only direct children are returned, not the contents of nested containers. Returns nil if the serial is not a container. Returns: array of item tables, or nil if the container was not found.

local pack = Player.Backpack
local regs = Items.FindInContainer(pack.Serial, 0x0F7A)
print('Black pearl stacks: ' .. #regs)

Same as Items.FindInContainer without filters: direct children only, mobile serials resolve to the mobile's backpack. Returns nil if the serial is not a container. Returns: array of item tables, or nil.

local loot = Items.GetContainerItems(corpse.Serial)
for _, item in ipairs(loot) do
    print(item.Name)
end

The filter is a table; every key is optional and all given conditions must match. Supported keys: dead (boolean), female (boolean), human (boolean), poisoned (boolean), paralized (boolean - note the spelling), rangemin/rangemax (distance in tiles), names (list of exact names), hues (list of numbers), bodies (list of body graphic ids), notorieties (list of strings: 'Innocent', 'Ally', 'Gray', 'Criminal', 'Enemy', 'Murderer', 'Invulnerable'), serials (list of serials). Returns a Lua array of mobile tables (empty when nothing matches). Returns: array of mobile tables (possibly empty).

-- hostile reds within 8 tiles
local reds = Mobiles.FindByFilter({ notorieties = { 'Murderer' }, rangemax = 8, dead = false })
for _, m in ipairs(reds) do
    print(m.Name, m.Distance)
end

Returns: mobile table or nil.

local healer = Mobiles.FindByName('a wandering healer')
if healer then
    print('Healer at ' .. healer.X .. ',' .. healer.Y)
end

Returns: mobile table or nil.

local pet = Mobiles.FindBySerial(0x00012345)
if pet then
    print(pet.Name .. ': ' .. pet.Hits .. '/' .. pet.HitsMax)
end

Returns: mobile table or nil.

local horse = Mobiles.FindByType(0x00C8)
if horse then
    Player.UseObject(horse.Serial)
end

Sends a rename request to the server; the server decides whether the mobile can actually be renamed. Returns: true if the request was sent, false otherwise.

Mobiles.Rename(0x00012345, 'Lightning')

Returns: true if a gump was closed.

Gumps.Close()

See also Gumps.CloseGump

With no argument (or 0), closes the first open server gump found. Returns false if no matching gump is open. Returns: true if a gump was closed.

Gumps.CloseGump(0x1F2E4C1D)

Returns a gump table with Serial, X, Y, Width, Height and Texts (a 1-indexed array of the gump's text lines) — see the Gump object reference. With no argument (or 0), the first open server gump is used. Returns nil if no matching gump is open. Returns: gump table or nil.

local gump = Gumps.GetGump()
if gump then
    for i, text in ipairs(gump.Texts) do
        print(i, text)
    end
end

With a gump id, checks for that specific gump. With no argument (or 0), returns true if any server gump is open. Returns: true if a matching gump is open.

if Gumps.HasGump(0x1F2E4C1D) then
    Gumps.Reply(0x1F2E4C1D, 1)
end

Returns: true if a matching gump is open.

if Gumps.IsActive() then print('a gump is open') end

See also Gumps.HasGump

Returns: true if the button press was queued, false otherwise.

Gumps.PressButton(0x554B87F3, 1)

See also Gumps.Reply

Returns false with a warning if the gump is not open. Returns: true if the button press was queued, false otherwise.

Gumps.Reply(0x554B87F3, 1)

Currently only the button press is applied; the switches and textEntries tables are accepted but not yet forwarded to the gump. For plain button presses, prefer Gumps.Reply. Returns: true if the response was queued, false otherwise.

Gumps.Send(0x554B87F3, 1)

Polls roughly every 100 ms. Pass 0 as gumpId to wait for any server gump. Returns: true if the gump appeared, false on timeout.

Player.UseObject(runebook.Serial)
if Gumps.WaitForGump(0x554B87F3, 3000) then
    Gumps.Reply(0x554B87F3, 5)
end

Returns: true on success.

if Targeting.IsTargeting() then
    Targeting.CancelTarget()
end

Returns a table with at least Serial; if the last target is a mobile in view, X, Y, Z and Name are included too. Returns nil if no last target is set. Returns: table { Serial [, X, Y, Z, Name] } or nil.

local last = Targeting.GetLastTarget()
if last then
    print('Last target serial: ' .. string.format('0x%08X', last.Serial))
end

Opens a client-side pick cursor so the user can select an item or mobile. Returns the picked serial as a number, or nil on timeout. Default timeout is 10000 ms. The picked serial also becomes the last target. Returns: picked serial (number) or nil.

Messages.Info('Select your loot container...')
local serial = Targeting.GetNewTarget(15000)
if serial then
    Config.Save('MyLooter', { container = serial })
end

Returns: true if a target cursor is up.

if Targeting.IsTargeting() then
    Targeting.Last()
end

If the last target is a mobile or item, it is targeted by serial. Static and land tiles (e.g. a tree you chopped or a mining spot) are replayed from the last target packet - click the tile once by hand, then repeat it from the script. Returns: true on success, false if no last target is available.

Player.UseObjectByType(0x0F43) -- axe
if Targeting.WaitForTarget(3000) then
    Targeting.Last() -- chop the same tree again
end

Answers the active target cursor with your own character. Returns: true on success.

Spells.Cast('Cure')
if Targeting.WaitForTarget(3000) then
    Targeting.Self()
end

Returns: true on success.

Targeting.SetLast(enemy.Serial)

Answers an active target cursor with the given mobile or item. Returns false if the entity is not in the game world. Returns: true on success, false otherwise.

Spells.Cast('Lightning')
if Targeting.WaitForTarget(3000) then
    Targeting.TargetSerial(enemy.Serial)
end

Polls roughly every 50 ms until the server asks for a target or the timeout expires. Typical pattern: cast a spell, wait for the cursor, then target something. Returns: true when a target cursor is active, false on timeout.

Spells.Cast('Greater Heal')
if Targeting.WaitForTarget(3000) then
    Targeting.Self()
end

Names are normalized, so 'Greater Heal', 'greater-heal' and 'GreaterHeal' all work. A numeric spell id is accepted too. Returns false with a warning for unknown spell names. Returns: true if the cast was started, false otherwise.

Spells.Cast('Greater Heal')
if Targeting.WaitForTarget(3000) then
    Targeting.Self()
end

Returns: true if the cast was started, false on error.

Spells.CastById(29)

The result is keyed by skill name; each entry is a table with Name, Index, Value, Base, Cap and Lock ('Up'/'Down'/'Locked'). Returns: table of skill tables keyed by skill name.

local all = Skills.GetAll()
for name, s in pairs(all) do
    if s.Base >= s.Cap and s.Cap > 0 then
        print(name .. ' is capped')
    end
end

Returns: base value as a number (0 if unknown).

print('Base Magery: ' .. Skills.GetBase('Magery'))

Returns: skill cap as a number (0 if unknown).

if Skills.GetBase('Mining') >= Skills.GetCap('Mining') then
    Messages.Info('Mining is capped.')
end

Returns: 'Up', 'Down' or 'Locked' (nil if the skill is unknown).

print(Skills.GetLock('Magery'))

Returns: skill value as a number (0 if the skill is unknown).

if Skills.GetValue('Magery') >= 62.5 then
    Spells.Cast('Greater Heal')
end

lockState is a string: 'up' (skill can raise), 'down' (skill lowers), or 'locked' (also accepts 'lock'). Case-insensitive; unrecognized values fall back to locked. Returns: true on success, false if the skill is unknown.

Skills.SetLock('Wrestling', 'locked')
Skills.SetLock('Magery', 'up')

The name is matched case-insensitively against the skill list (e.g. 'Hiding', 'Meditation'). Returns false if the skill is unknown. Returns: true on success, false otherwise.

Skills.Use('Hiding')
Pause(10000)

Entries received before this call are ignored by Journal.Contains, ContainsFrom and GetAll. The clear is shared across all scripting engines. Returns: true.

Journal.Clear()
Player.UseObject(forge.Serial)
if Journal.WaitForText('You fail', 5000) then
    print('failed')
end

Case-insensitive substring search over all entries received since the script started (or since the last Journal.Clear). Returns: true if found.

if Journal.Contains('You have been poisoned') then
    Spells.Cast('Cure')
end

Like Journal.Contains, but the entry's speaker name must also match (case-insensitive, exact name). Returns: true if found.

if Journal.ContainsFrom('I will train you', 'Gareth') then
    Player.Say('train magery')
end

Entries are in chronological order; each is a table with Text, Name, Hue and Time ('HH:mm:ss'). Returns: array of entry tables.

for _, entry in ipairs(Journal.GetAll()) do
    Console.log(entry.Text)
end

Returns up to count entries, newest first (default 1). Each entry is a table with Text, Name (speaker), Hue and Time ('HH:mm:ss'). Note: GetLast ignores the Journal.Clear filter. Returns: array of entry tables, newest first.

local last = Journal.GetLast(5)
for i, entry in ipairs(last) do
    print(entry.Time, entry.Name, entry.Text)
end

Only entries received after this call is made are considered; older entries never match. Polls roughly every 100 ms. Case-insensitive substring search. Returns: true if the text appeared, false on timeout.

Skills.Use('Tracking')
if Journal.WaitForText('You see no evidence', 4000) then
    Messages.Info('Nothing nearby.')
end

Returns: true on success.

Messages.Error('Runebook not found - stopping.')

Returns: true on success.

Messages.Info('Script started.')

Returns: true on success.

Messages.Overhead('Healing!', 68)

Returns false if the mobile is not in view. Returns: true on success, false otherwise.

Messages.OverheadMobile(pet.Serial, 'Low HP!', 33)

Returns: true on success.

Messages.Print('Loot pass done.', 68)

Returns: true on success.

Messages.Warning('Low on reagents!')

Returns: true if a file was deleted, false otherwise.

Config.Delete('MyLooter')

Returns: true if the config file exists.

if not Config.Exists('MyLooter') then
    Messages.Info('First run - using defaults.')
end

Returns the saved table, or nil if the config does not exist. JSON objects and arrays become tables, numbers become Lua numbers. Returns: table or nil.

local cfg = Config.Load('MyLooter')
if cfg == nil then
    cfg = { enabled = true }
end

Supports strings, numbers, booleans, nested tables and arrays. Files are stored as .json in the Config subfolder of the Lua scripts folder (Data/LuaScripts/Config/) and can be edited by hand. The name must be a plain file name without paths. Returns: true on success, false otherwise.

Config.Save('MyLooter', {
    container = 0x40001234,
    enabled = true,
    graphics = { 0x0EED, 0x0F7A }
})

Returns: true.

UI.DestroyAll()

Usually not needed: Pause() pumps automatically and win:Run() pumps in a loop. Use UI.Pump() only in custom loops that never call Pause. Returns: true.

while myWindowOpen do
    UI.Pump()
    Pause(50)
end

Also accepts a table form: UI.Window{ title = 'Helper', x = 100, y = 100, width = 250, height = 300 }. Elements stack vertically with auto-layout (use win:Row() for a horizontal group). Callbacks and bindings are pumped automatically during Pause(); win:Run() is the convenience loop that waits until the window is closed. All windows are destroyed when the script ends. Returns: window table, or nil on error.

local win = UI.Window('Helper')
win:Label(function() return 'HP: ' .. Player.Hits end)
local status = win:Label('Ready')
win:Button('Heal', function()
    status:SetText('Casting...')
    Spells.Cast('Greater Heal')
end)
local auto = win:Checkbox('Auto-heal', false)
win:Run()  -- pumps callbacks until the window is closed