Blightmud Setup

Blightmud is a terminal-based MUD client written in Rust with Lua scripting and built-in GMCP support. The quickest setup is the official Icesus package, which adds GMCP status rows and your saved hotkeys with no scripting. 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 is a drop-in Lua configuration for Blightmud. Clone it into your Blightmud config directory and you get:

• Four status rows at the bottom of the terminal, filled from GMCP. They show the room and its exits; your momentum, casting bar and cooldowns; the enemies you are fighting, with HP coloured by the shape buckets consider uses, next to your afflictions, wounds and karma; and your HP, SP, EP, guild resource, exp and the in-game hour. Each row shortens itself to fit a narrow terminal.
• A two-row layout if you want less: /icesus simple shows only the enemies above your pools and exp, and /icesus full switches back. Blightmud remembers the choice.
• Your saved hotkeys on F1 to F12, the same set the browser client edits. Press alt-m to use whatever momentum is up, and alt-s for your special momentum.
• /icesus to list your keys and commands, and /icesus guild to print bonds, souls, charm abilities and devotion.
• A preconfigured TLS server: /connect Icesus opens an encrypted session to icesus.org:4443.
• Example aliases, highlights 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

A green line says the Icesus package loaded, and the status rows fill 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.

To update, run git -C ~/.config/blightmud pull and type /reload in Blightmud.

Put your own aliases, binds and settings in ~/.config/blightmud/local.lua. It loads after the package, and a git pull leaves it alone. The package README lists the settings, and the rest of this guide shows how to write your own Lua. Type /reload after an edit.

Originally written by Tenki as a personal Blightmud starter for Icesus; it is now the official package.

What Blightmud Is

Blightmud is a modern terminal client for Linux, macOS, WSL, and other Unix-like environments supported by Rust and Cargo. Think of it as TinyFugue with Lua: terminal-first, scriptable, fast, and bare until you add your own helpers.

Blightmud supports 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 Does Not Have

Blightmud has no windows, mapper, gauges or buttons. The official Icesus package adds status rows in the terminal and nothing graphical.

If you want panels and gauges, 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 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 cannot bind a key to a UI event 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. With the official package, F1 to F12 already send your saved hotkeys, so pick another key:

blight.bind('alt-i', function()
  mud.send('inventory')
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 reads seven GMCP packages, guards against a zero maximum, and shortens each row to fit the terminal.

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 line and the status rows.
4. Add your own shortcuts, highlights and keybinds to ~/.config/blightmud/local.lua, copying from the examples in icesus/aliases.lua, icesus/lites.lua and icesus/bindings.lua, then type /reload.
5. 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 in Browser