Where To Find Them

Open Automation and click Add Script. Scripts live in the same tree as triggers and aliases.

Scripts are useful when you want one function to be reused by several Lua triggers or Lua aliases. If a parent folder is disabled, scripts inside that folder do not load.

Library Pattern

function captureVitals(text)
  local hp, maxhp = string.match(text, "^Hp:(%d+)/(%d+)")
  if hp then
    state.hp = hp
    state.maxhp = maxhp
  end
end

function showTarget(name)
  echo("<cyan>Target:<reset> " .. tostring(name))
end

function delayedLook()
  return timer(5, [[ send("look") ]])
end

A function is a named recipe. For example, captureVitals(text) takes one piece of text, looks for hit point numbers, and stores them in temporary state values.

Compile validates a Script before it can be enabled. Defining functions at the top level is allowed. Sending commands, echoing text, highlighting lines, changing widgets, and writing variables at the top level are blocked because the script is only being loaded, not responding to a MUD event yet.

Helper functions may create timers when a Lua trigger or Lua alias calls them. Timers are temporary browser-side automation and are not saved as profile settings.

Use print_var(value, label) from Scripts, Lua triggers, or Lua aliases to print readable recursive debug output in the current terminal.

Lifecycle Hooks

function CreateGauges()
  gauge.create("health", {
    label = "HP",
    value = "state.hp",
    maximum = "state.maxhp",
    location = { zone = "top", width = 4 },
  })
end

function onLoad()
  CreateGauges()
end

function onConnect()
  echo("<green>Connected automation ready.<reset>")
end

function onBatVitals(data)
  state.hp = data.hp
  state.maxhp = data.hpmax
end

function onDisconnect()
  status.remove("target")
end

onLoad() runs after an enabled Script loads and may define gauges or status widgets owned by that Script. onConnect() and onDisconnect() run on MUD session lifecycle changes. Widgets can bind directly to scalar GMCP and BatClient paths; use onGMCP() or BatClient handlers such as onBatVitals() when you want to normalize read-only data into custom state keys. Uppercase handler names such as OnLoad() and OnBatVitals() are also accepted.

Calling Helpers

-- Lua trigger code
captureVitals(line)

-- Lua alias code
showTarget(matches[2])

Lua triggers and Lua aliases load enabled Scripts first, then run their own code. Calling captureVitals(line) means "run the recipe named captureVitals and give it the current MUD line."

Helper functions can send commands, echo text, highlight output, update variables, update state, and define widgets when called from a trigger, alias, or Script lifecycle hook.

Structured Data

function currentRoomName()
  local room = batclient.mapper.current
  return room and room.shortName or ""
end

function currentHP()
  return gmcp.Char and gmcp.Char.Vitals and gmcp.Char.Vitals.hp
end

Scripts can read the latest gmcp, batclient, vars, and state snapshots while preloading. See GMCP and BatMUD Variables.

Shared Scope

function luashow(name)
  echo("<cyan>Lua:<reset> " .. tostring(name))
end

Every enabled Script is loaded before Lua triggers and Lua aliases run. This is the place for reusable functions such as luashow().

Function and table globals stay inside the Lua sandbox. Scalar globals such as strings, numbers, and booleans update persistent Variables only when assigned by a Lua trigger or Lua alias, not during Script preload.

Detached Sessions

Browser-side Lua automation does not run while the browser is detached, and replayed output does not fire triggers. Widgets retain their last browser value until fresh output updates state after resuming.