Blightmud Setup

Blightmud is a terminal-based MUD client written in Rust with Lua scripting and built-in GMCP support. The fast path is to drop in the official Icesus package for a GMCP status bar and connect — no scripting required. The rest of this guide shows how to extend it (or start from scratch) with your own Lua aliases, triggers, timers, and keybinds.

Official Icesus Package (Recommended)

The Icesus-mud/blightmud-package repository ships a small, drop-in Lua configuration for Blightmud. Clone it into your Blightmud config directory and you get:

• Two-row terminal status area — Hp / Sp / Ep (and Psp if you have set psp_on), Exp with progress to next advancement, and the named in-game hour. Above it, per-enemy HP percentages coloured by the server’s consider shape buckets so the bar can’t pretend to know more than the game does.
• Preconfigured TLS server — /connect Icesus opens an encrypted session to icesus.org:4443.
• Example aliases, lites, and keybindings to copy from when you start writing your own.

Fresh install (no existing Blightmud config):

git clone https://github.com/Icesus-mud/blightmud-package.git ~/.config/blightmud
blightmud
/connect Icesus

You should see a green [Icesus] package loaded. line and the bottom two-row status area populate within a few seconds of connecting. If you already have a Blightmud config you want to keep, copy the files in side-by-side and merge settings.ron and servers.ron by hand — both are RON dictionaries you can extend.

Edit any file under ~/.config/blightmud/icesus/ and type /reload in Blightmud to re-run the whole config. The package is intentionally small — the rest of this guide shows the patterns you would use to extend it.

Originally written by Tenki as a personal Blightmud starter for Icesus, then adopted as the official package with additional polish.

What Blightmud Is

Blightmud is a modern terminal client for Linux, macOS, WSL, and other Unix-like environments supported by Rust and Cargo. A useful mental model is "Lua-powered TinyFugue": terminal-first, scriptable, fast, and intentionally sparse until you add your own helpers.

Blightmud includes the protocol pieces expected from a serious modern terminal MUD client: TLS, GMCP, MSDP, MCCP2, NAWS, and GA. For Icesus, the most immediately useful pieces are TLS for encrypted connections, GMCP for structured client data, and MCCP2 for compression.

What Blightmud Is Not

Blightmud is not a graphical package with windows, mappers, gauges, and prebuilt buttons. The official Icesus package gets you a terminal status bar, but there is no sidebar, no clickable HUD, no mapper. That is the point of running in a terminal.

If you want a polished visual client with widgets, start with the Icesus browser client or Icesus Mudlet package. Choose Blightmud when you live in a terminal, want to mosh into a remote tmux session and play from anywhere, or prefer Lua over a GUI workflow.

Connect to Icesus

The simplest encrypted Icesus connection is:

/connect icesus.org 4443 tls

In environments with TLS interception, such as some corporate networks, you may need no-verify. Use that only when you understand the trade-off: it defeats the certificate verification that makes TLS meaningful.

To save Icesus as a named Blightmud server, run:

/lua servers.add('Icesus', 'icesus.org', 4443, true, true)

After that, connect with:

/connect Icesus

Where Lua Files Live

Blightmud loads .lua files from its configuration directory. On Linux this is typically:

~/.config/blightmud/

A simple Icesus setup can live in ~/.config/blightmud/icesus.lua, or you can use that file as an entrypoint that loads the rest of your aliases, triggers, GMCP display, and storage helpers.

A Simple Trigger

This example highlights a line bright green and reports a useful state change to the party:

trigger.add([=[^You feel safer\.$]=], {}, function(_, line)
  line:replace(C_BGREEN .. line:line() .. C_RESET)
  mud.send('party report Life boost UP')
end)

The pattern uses Lua long bracket quoting: [=[...]=]. It is not required, but it makes regular expressions easier because you do not need to double-escape every backslash. This is also valid for the same simple pattern:

trigger.add("^You feel safer\\.$", {}, function(_, line)
  line:replace(C_BGREEN .. line:line() .. C_RESET)
  mud.send('party report Life boost UP')
end)

Timers and Keybinds

Timers run Lua functions after a delay or on an interval. This intentionally useless example prints a local client message once after five minutes:

local function timer_function()
  blight.output('5 minutes passed')
end

timer.add(300, 1, timer_function)

You can also bind keys. Blightmud’s blight.bind takes a key and a Lua function — it does not bind keys to UI events directly. To rebind a key to a built-in UI action (scrolling, cursor motion, line history) you wrap blight.ui(event) in a small helper and pass that. The official package uses this ui_bind helper:

local function ui_bind(cmd, event)
  blight.bind(cmd, function()
    blight.ui(event)
  end)
end

By default Blightmud uses Home and End for split-screen scrolling. This rebinds them to move the cursor to the start and end of the input line instead:

ui_bind('home', 'step_to_start')
ui_bind('end', 'step_to_end')

For binds that send a MUD command, skip the helper and pass the function directly:

blight.bind('f1', function()
  mud.send('use strike')
end)

GMCP Status Line

Blightmud supports GMCP natively, but it leaves the handling to your Lua. This example listens for Char.Vitals and writes HP/SP/EP into the status area:

local function update_from_vitals(vitals)
  local status = string.format('Hp: %d/%d Sp: %d/%d Ep: %d/%d',
    vitals.hp,
    vitals.maxhp,
    vitals.mana,
    vitals.maxmana,
    vitals.moves,
    vitals.maxmoves
  )
  blight.status_line(0, status)
end

gmcp.register('Char.Vitals')
gmcp.receive('Char.Vitals', function(data)
  update_from_vitals(json.decode(data))
end)

This updates the top status line whenever Icesus sends new vitals. Build from there: room data, party state, casting progress, cooldowns, and momentums are better displayed from GMCP than scraped from prose when the data exists. The official package’s status.lua is a working reference — it adds divide-by-zero guards, a per-pool colour band, and the per-enemy HP strip on top of this skeleton.

Good First Blightmud Setup

1. Install Blightmud from your distribution package, Cargo, or the project GitHub page.
2. Install the official Icesus package: git clone https://github.com/Icesus-mud/blightmud-package.git ~/.config/blightmud.
3. Connect with /connect Icesus. Confirm you see the green load banner and the two-row status area.
4. Edit ~/.config/blightmud/icesus/aliases.lua to add your own shortcuts, then type /reload.
5. Add highlights to icesus/lites.lua and keybinds to icesus/bindings.lua as you find lines worth flagging.
6. Keep a raw log so you can copy exact Icesus wording before writing triggers.

Building from scratch instead? Skip step 2, create ~/.config/blightmud/icesus.lua, and add aliases, triggers, and a GMCP status line as you go. The patterns above show what each piece looks like.

Related Guides

• Icesus-mud/blightmud-package on GitHub
• MUD Clients for Icesus
• TinTin++ Setup for Icesus
• TinyFugue Setup for Icesus
• Icesus Mudlet Package
• Mudlet Setup for Icesus
• Icesus Mudlet GMCP
• Accessibility and screen reader support
• Play Icesus in the browser