Temporary Session Data

BatClient data belongs to the current MUD session and is kept in memory. It is not saved into your profile settings or settings exports. Resuming a retained session restores its latest accepted data; a new MUD session starts fresh. Different MUD sessions have separate state.

Oversized updates are ignored while the previous valid data remains available. This bounds session memory, including growing collections such as locations and objects. Values you deliberately copy into normal saved variables are saved as usual.

Reading Data

local hp = batclient.vitals.hp
local maxhp = batclient.vitals.hpmax
local room = batclient.mapper.current

if room then
  echo("<green>" .. room.areaName .. ": " .. room.shortName)
end

batclient is available to Lua triggers, Lua aliases, Lua script libraries, and direct status widget bindings such as batclient.vitals.hp. The table is read-only; copy values into state or normal variables when your Lua trigger or alias needs to change them.

Common Tables

batclient.vitals.hp
batclient.character.name
batclient.status.stunned
batclient.target.target
batclient.party.members.Killer.hp
batclient.effects.haste.timeLeft
batclient.mapper.current.roomId
batclient.prompt.text
state.prompt

Party member status flags are converted into booleans such as leader, creator, idle, invisible, stunned, and unconscious. Mapper data is stored under batclient.mapper.current. BatMUD prompt text is copied into temporary state.prompt.

Use the Inspector tab or /print_var batclient to inspect the live table for the current visible server.

Vitals

batclient.vitals = {
  hp = 621,
  hpmax = 621,
  sp = 1126,
  spmax = 1126,
  ep = 455,
  epmax = 455,
}

local v = batclient.vitals
if v then
  state.hp = v.hp
  state.maxhp = v.hpmax
  state.sp = v.sp
  state.maxsp = v.spmax
  state.ep = v.ep
  state.maxep = v.epmax
end

Character And Status

batclient.character = {
  name = "Bamot Kamot",
  firstName = "Bamot",
  surname = "Kamot",
  race = "coder",
  level = 101,
  gender = 1,
  genderName = "male",
  experience = 399688,
  freeExperience = 12345,
}

batclient.status = {
  unconscious = false,
  stunned = false,
  dead = false,
}

if batclient.status and batclient.status.stunned then
  echo("<red>You are stunned!<reset>")
end

if batclient.character then
  state.level = batclient.character.level
end

Prompt And Target

The prompt stays visible until it changes. Identical BatClient prompt updates are suppressed by the server; changes to its text or kind still reach the client, including while you are idle. Reopening a retained connection restores the latest prompt. When server-side logging is enabled, only the first readable BatClient prompt after a submitted command is saved.

batclient.prompt = {
  kind = "spec_prompt",
  text = "~/workroom @ ~/ >>",
}

state.prompt = "~/workroom @ ~/ >>"

batclient.target = {
  active = true,
  target = "orc warrior",
  percentage = 45,
}

local prompt = state.prompt or ""
local target = batclient.target

if target and target.active then
  echo("<yellow>Target: " .. target.target .. " " .. target.percentage .. "%<reset>")
end

Mapper And Location

batclient.mapper.current = {
  areaName = "smurville",
  roomId = "$apr1$dF!!_X#W$A2RUTT6SmMO5xtJRjs38Q/",
  entryCommand = "south",
  shortName = "The center of the village",
  descriptionFirstLine = "Center of the village",
}

batclient.location = {
  name = "Bamot",
  race = "coder",
  gender = 1,
  genderName = "male",
  continent = "Laenor",
  x = 123,
  y = 456,
  z = 0,
}

local room = batclient.mapper and batclient.mapper.current
if room then
  state.area = room.areaName
  state.room = room.shortName
end

Party

batclient.party.members.Killer = {
  action = "member",
  player = "Killer",
  race = "orc",
  gender = 1,
  genderName = "male",
  level = 50,
  hp = 101,
  hpmax = 200,
  sp = 202,
  spmax = 303,
  ep = 404,
  epmax = 504,
  partyName = "expaa",
  placeX = 1,
  placeY = 1,
  leader = true,
  creator = true,
  following = false,
  linkdead = false,
  resting = false,
  idle = false,
  invisible = false,
  stunned = false,
  unconscious = false,
}

batclient.party.locations.Killer = {
  player = "Killer",
  x = 10,
  y = 22,
}

local party = batclient.party
if party and party.members then
  for name, member in pairs(party.members) do
    if member.leader then
      state.partyLeader = name
    end
  end
end

Effects And Progress

batclient.effects.haste = {
  effect = "haste",
  timeLeft = 120,
  active = true,
  observedAt = 1790726400000, -- gateway receipt time, Unix milliseconds
}

batclient.progress.spell = {
  kind = "spell",
  name = "heal self",
  roundsLeft = 2,
}

batclient.progress.skill = {
  kind = "skill",
  name = "consider",
  roundsLeft = 1,
}

timeLeft is seconds remaining when the update arrived, not a continuously changing value. observedAt retains that update's time across snapshots. A value of -1 means the duration is variable or unknown; 0 removes the effect. The optional Buff Tracker package displays live countdowns.

local effects = batclient.effects
if effects and effects.haste and effects.haste.active then
  state.hasteLeft = effects.haste.timeLeft
end

local progress = batclient.progress
if progress and progress.spell then
  state.casting = progress.spell.name
end

Communications

BatClient channel frames emit live communication events with kind, channel, plain text, and formatted ansi. These events are temporary and are not retained in the batclient snapshot. The Communications package routes them into tabs without removing the original terminal output.

Familiar And Objects

batclient.familiar = {
  player = "Bamot",
  name = "small raven",
  uniqueId = 1234,
  hp = 80,
  hpmax = 100,
  sp = 40,
  spmax = 60,
  ep = 90,
  epmax = 100,
  stunned = false,
  unconscious = false,
  dead = false,
}

batclient.objects["steel_sword_1"] = {
  id = "steel_sword_1",
  name = "steel sword",
  type = "weapon",
}

Object fields can vary by what BatMUD sends. The only stable rule is that objects are stored by their id under batclient.objects.

Using Updates

-- Lua trigger code
local vitals = batclient.vitals
if vitals and vitals.hp then
  state.hp = vitals.hp
  state.maxhp = vitals.hpmax
end

local room = batclient.mapper.current
if room then
  state.room = room.shortName
end

These variables update as new data arrives. Read them from Lua triggers, Lua aliases, or Script event handlers. See Lua Scripts for lifecycle and BatClient update hooks.

Optional Tables

batclient.connection
batclient.progress
batclient.objects
batclient.familiar
batclient.location
batclient.party.locations
batclient.blocked

Optional tables appear only after BatMUD has sent that kind of data. Always check that a table exists before reading nested fields.

The client ignores unsafe fields or identifiers and excessively nested data. A rejected update leaves the last accepted data in place and does not run its Script event handler. These checks also apply to restored snapshots.