rune

README

Rune

A terminal MUD client built with Go and Lua.

Go handles networking, terminal rendering, and concurrent I/O. Lua scripts define aliases, triggers, key bindings, layouts, and client commands.

Guides, cookbook recipes, and the full API reference live at runemud.com. Questions, ideas, and feedback are welcome in the Rune Discord.

Features

Scripting:

• Aliases - Command expansion with exact match or regex patterns
• Triggers - React to server output with pattern matching and gags
• Timers - One-shot and repeating timers with named management
• Hooks - Event system for connecting to input/output pipeline
• Key Bindings - Bind keys to Lua callbacks
• Groups - Master switches to enable/disable sets of aliases/triggers/timers
• Command Chaining - kill rat;loot sends both; #3 north repeats a command or alias
• Script Error Handling - Failing callbacks are disabled individually; a watchdog interrupts script execution subject to the LuaJIT limits

Protocols:

• GMCP - Structured server data (vitals, room info, channels) with a scriptable rune.gmcp API and automatic Core.Hello handshake
• MCCP2 - Transparent zlib stream compression
• TLS - Encrypted connections (tls://host:port), including self-signed certs
• Telnet Negotiation - TTYPE/MTTS, NAWS, CHARSET (UTF-8), and MNES identification

Quality of life:

• Worlds - Named server bookmarks; /connect with no arguments opens a picker
• Session Logging - /log writes an ANSI-stripped transcript that reads like the screen
• Durable Storage - rune.store persists structured values across restarts
• Tab Completion - Word cache from server output with match cycling
• History - Zsh-style prefix-matching navigation
• Panes & Bars - Multiple output buffers with scrollback, reactive status bars

Installation

Download a binary for Linux, macOS, or Windows from the releases page, unpack it, and put rune on your PATH.

With Go installed, you can instead:

go install github.com/mmcdole/rune/cmd/rune@latest

Or build from source:

git clone https://github.com/mmcdole/rune
cd rune
go build ./cmd/rune/

See the installation guide for details.

Quick Start

Connect straight from your shell:

rune mud.example.com 4000           # plain telnet
rune tls://mud.example.com:4000     # TLS

Then, inside the client:

/world add example mud.example.com 4000    save a bookmark
/connect example                           connect by name (or later: rune example)
/log start                                 log the session to a file
/help                                      everything else

User scripts load from ~/.config/rune/init.lua at startup:

-- Alias with regex captures
rune.alias.regex("^kill (.+)$", "attack %1; murder %1")

-- Trigger: highlight a line in red
rune.trigger.contains("You are hit", function(matches, ctx)
    return rune.style.red(ctx.line:clean())
end)

-- GMCP: warn on low health
rune.gmcp.subscribe("Char")
rune.gmcp.on("Char.Vitals", function(data)
    if data.hp and data.maxhp and data.hp < data.maxhp * 0.25 then
        rune.echo(rune.style.red("[LOW HP] " .. data.hp .. "/" .. data.maxhp))
    end
end)

Everything Rune reads and writes — scripts, saved worlds, state, and logs — lives in ~/.config/rune. Use rune --config-dir <dir> or RUNE_CONFIG_DIR=<dir> to keep it in a different directory.

The scripting basics guide picks up from here.

Documentation

Full guides, cookbook recipes, and reference live at runemud.com:

• First session and scripting basics
• Lua API reference — every rune.* namespace
• Slash commands and keyboard shortcuts
• Migrating from another MUD client

In-repo reference: the architecture overview. The API reference source lives at website/src/content/docs/reference/api/.

License

MIT License - see LICENSE for details.