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

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,
}

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

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

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

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.