Skip to content
BranchesTags

Repository files navigation

NeXusMUDBOT

A standalone bot for MajorMUD, HellaMUD, and other games running on The Major BBS / Worldgroup platforms. Connects to your BBS via Telnet, logs in automatically, stays in-game, and responds to player commands sent via in-game telepaths.

No Python install required. No database server required. Runs on Windows, Mac, or Linux.

Quick Video: https://www.youtube.com/watch?v=QSkWlknB8jA

Created with Love <3 by Mark Laudenbach in Iowa USA!

Features

  • Telnet connection to any Major BBS / Worldgroup server with full ANSI color support
  • Configurable login sequence — no code changes needed for different BBS systems
  • In-game telepath command handling — players telepath @commands to the bot
  • @freecoin command — give players free in-game currency when they're in the same room (configurable name, amount, currency, and rate limiting)
  • @heal command — cast a healing spell on players in the same room (configurable spell, cooldown, and confirmation message)
  • Room presence tracking — room-required commands verify the player is there via a live look, handling silent teleports like sys goto
  • Per-command enable/disable — each command can be toggled in config.cfg; disabled commands are silently ignored and excluded from @help
  • Sysop dashboard — browser-based data dashboard with filterable tables for all logged data, protected by Basic Auth
  • Gossip logging — all public gossip messages logged to the database
  • Auction logging — all public auction messages logged to the database
  • Discord relay — gossip and auction messages forwarded to a Discord channel via webhook
  • SQLite logging — sessions, players, commands, telepaths, gossips, auctions, money log, heal log (single file, zero setup)
  • Auto-reconnect on disconnect with configurable delay
  • Keepalive pings to prevent BBS session timeout
  • Periodic in-game gossip ad — configurable message posted on a schedule
  • First-time player welcome — sends a telepath to new players when they enter the realm
  • Embedded web terminal — live ANSI browser terminal, no local client needed
  • Headless mode — web terminal still available, no browser auto-open (great for servers)
  • Orphaned session cleanup — hard-killed sessions are closed cleanly on next startup

Getting Started

⚠️ Run as Administrator — The bot binds to a local port for the web terminal and dashboard. On Windows, right-click → Run as administrator on both NeXusMUDBOT-setup.exe and NeXusMUDBOT.exe.

Option A — Pre-built Executable (recommended)

  1. Download and extract NeXusMUDBOT-1.1.2.zip
  2. Right-click NeXusMUDBOT-setup.exe → Run as administrator — creates your config.cfg
  3. Right-click NeXusMUDBOT.exe → Run as administrator — the bot starts and your browser opens automatically

That's it. No Python, no database server, nothing else to install.

Option B — Run from Source

git clone https://github.com/laudenbachm/NeXusMUDBOT.git
cd MUDBOT
pip install -r requirements.txt
python setup.py          # First-time config wizard
python bot.py            # Normal mode (browser opens automatically)
python bot.py --headless # Headless mode (URL printed to console)

Running Modes

Mode Command Browser
Normal NeXusMUDBOT.exe Opens dashboard automatically
Headless NeXusMUDBOT.exe --headless Open manually at http://localhost:8765/dashboard

In both modes the web terminal and dashboard are available. Connect any browser to watch the bot live, send commands, and view logged data.

Web Terminal

The embedded web terminal streams live BBS output — full ANSI color, scrollback, command input.

  • Normal mode: opens automatically in your default browser
  • Headless mode: connect from any browser to http://localhost:PORT/
  • Multiple browser tabs can connect at once — all see the same feed
  • Commands typed in the input bar are forwarded directly to the BBS
  • Port is set in config.cfg → [bot] → web_port (default 8765)

Sysop Dashboard

The dashboard is available at http://localhost:8765/dashboard. It is protected by Basic Auth — use the same username and password as your bot's BBS account.

NeXusMUDBOT Dashboard

The dashboard is read-only and does not send any commands to the BBS. Data is loaded on demand — click Refresh on any tab to fetch the latest records.

Tabs

Tab What it shows
Terminal Embedded live web terminal
Players Every player the bot has interacted with — alignment, command count, first/last seen
Commands Every bot command received — who, what, when
Gossips All public gossip messages
Auctions All public auction messages
Sessions Bot connect/disconnect history with duration
Money Log Free coin grant history per player
Heal Log Heal cast history per player

Each tab supports filtering by player name, date range, and result limit.

Commands

Players send commands by telepathying @command to the bot in-game.

Command What it does
@saint Set player alignment to Saint
@good Set player alignment to Good
@neutral Set player alignment to Neutral
@evil <points> Add evil points (e.g. @evil 50)
@retrain Flag player for stat retraining on next login
@lawful Set player to Lawful status
@unlawful Set player to Unlawful status
@discord Telepath the Discord invite link
@stats Telepath player's usage stats from the database
@help Telepath the full command list (enabled commands only)
@freecoin Give free in-game currency — player must be in the same room as the bot
@heal Cast a healing spell — player must be in the same room as the bot

Command names for @freecoin and @heal are configurable in config.cfg. Unknown commands receive: INVALID COMMAND — for a list of commands type @help

Enabling and Disabling Commands

Each command can be toggled in config.cfg [commands]:

[commands]
heal     = true
freecoin = false   # players who use this command are silently ignored

Configuration

All settings live in config.cfg. The setup wizard (NeXusMUDBOT-setup.exe) creates this for you.

[bbs] — Connection Settings

Key Description
host BBS hostname or IP address
port Telnet port (usually 23)
encoding Character encoding (usually cp437 for BBS systems)
terminal_type Terminal type reported during negotiation (use ansi for ANSI color)
bot_username Username the bot logs in with
bot_password Password for that account
bot_char_name In-game character name as shown in gossip (may differ from login name)

[game] — Game Settings

Key Description
name Game name as it appears in BBS menus (e.g. HELLAMUD)
enter_command Command to enter the game from the main menu (usually E)

[login_sequence] — Login Steps

Define each step of the BBS login flow as step_N = prompt_text|response. Steps are matched in order — when the bot sees prompt_text it sends response and advances.

Available placeholders: {username}, {password}, {game_name}, {enter_command}

[login_sequence]
step_1 = Please Enter your User-ID|{username}
step_2 = Enter your PASSWORD|{password}
step_3 = for help, or X to Exit|/go {game_name}
step_4 = [{game_name}]|{enter_command}

[always_respond] — Persistent Prompts

These prompts are answered every time they appear anywhere in the session — perfect for (N)onstop, (Q)uit, or (C)ontinue? which can appear repeatedly.

[always_respond]
prompt_1 = (N)onstop, (Q)uit, or (C)ontinue?|N

[bot] — Bot Behavior

Key Default Description
keepalive_interval 120 Seconds between keepalive pings
reconnect_delay 30 Seconds to wait before reconnecting after disconnect
log_level INFO Log verbosity: DEBUG, INFO, WARNING, ERROR
web_port 8765 Port for the embedded web terminal and dashboard
discord_link Discord invite URL sent by the @discord command
discord_gossip_webhook Discord webhook URL for gossip/auction relay (leave blank to disable)
gossip_ad_message Message to gossip periodically in-game (leave blank to disable)
gossip_ad_interval 21600 Seconds between gossip ads (default 6 hours)
welcome_message Telepath sent to first-time players (leave blank to disable)

Placeholders available in gossip_ad_message and welcome_message:

Placeholder Resolves to
{username} Player's name (welcome message only, substituted per player)
{discord_link} [bot] discord_link value
{game_name} [game] name value

[room] — Room Settings

Used by commands that require the player to be in the same room as the bot. If a player uses @freecoin or @heal from a different room, the bot tells them where to find it.

Key Description
room_name Display name of the room the bot is stationed in
room_message Navigation hint shown to players (e.g. Type "sys goto sil" to meet me.)

[heal] — Heal Command

Key Default Description
command @heal The telepath command players use
spell_command cast "heal" {player} The in-game command to run. Use {player} as the target placeholder
cooldown_amount 30 Time between heals per player. Set to 0 for no cooldown
cooldown_unit minutes seconds, minutes, hours, or days
heal_message Confirmation message sent to the player after healing

[givemoney] — Free Coin Command

Key Default Description
command @freecoin The telepath command players use
currency Runic Coin Currency name used in the in-game give command
amount 1 How many units to give per request
limit interval none (unlimited), once (ever), or interval (once per time window)
interval_amount 24 Number of time units between allowed requests (used when limit = interval)
interval_unit hours hours or days

Discord Relay

The bot forwards gossip and auction messages to a Discord channel in real time:

PlayerName gossips: Hello world! PlayerName auctions: WTS Dragon Armor 50k

Setup

  1. In Discord, go to your channel → Edit Channel → Integrations → Webhooks → New Webhook
  2. Copy the Webhook URL
  3. Add it to config.cfg:
[bot]
discord_gossip_webhook = https://discord.com/api/webhooks/your-id/your-token

The bot's own gossips (including ad messages) are filtered out automatically — only player messages are relayed.

Database

SQLite — a single mudbot.db file in the same folder as the executable. Created automatically on first run. No server, no credentials, no setup.

Table Description
sessions Bot connect/disconnect times and reasons
players Every player seen — alignment, command count, first/last seen, welcomed flag
commands Every bot command received (who, what, when, raw line)
telepaths All telepath messages (not just bot commands)
gossips All public gossip messages
auctions All public auction messages
room_occupants Players currently in the same room as the bot
money_log Free coin grant history per player
heal_log Heal cast history per player
game_log Reserved for future use

Sessions left open by a hard-kill (window X'd) are automatically closed as Terminated on the next startup.

Building from Source

Requires Python 3.10+ and PyInstaller:

pip install pyinstaller
python build.py          # Build
python build.py --clean  # Clean build artifacts first, then build

Output is in dist/NeXusMUDBOT-VERSION/. Zip that folder for distribution.

File Structure

NeXusMUDBOT/
├── bot.py                  # Entry point
├── setup.py                # First-time setup wizard
├── build.py                # PyInstaller build helper
├── config.cfg              # Your config (not committed — see config.cfg.example)
├── config.cfg.example      # Config template
├── requirements.txt        # Python dependencies
├── nexusmudbot.spec        # PyInstaller build spec
│
├── core/
│   ├── connection.py       # Telnet, reconnect, keepalive, room tracking,
│   │                       #   telepath/gossip/auction dispatch, Discord relay
│   ├── login.py            # Configurable login sequence + always-respond engine
│   ├── parser.py           # ANSI + control character stripping
│   └── database.py         # SQLite logging layer (aiosqlite)
│
├── commands/
│   ├── registry.py         # Command registration and dispatch
│   ├── alignment.py        # @saint @good @neutral @evil @retrain @lawful @unlawful
│   ├── info.py             # @discord @help @stats
│   ├── money.py            # @freecoin
│   └── heal.py             # @heal
│
└── web/
    ├── server.py           # Embedded aiohttp server (terminal, dashboard, API)
    ├── terminal.html       # xterm.js browser terminal
    └── dashboard.html      # Sysop dashboard

Adding New Commands

Create a .py file in commands/ and import it in core/connection.py:

from commands.registry import command
import logging

logger = logging.getLogger('mudbot.commands.mycommands')

@command("@mycommand")
async def cmd_mycommand(bot, player: str, args: str):
    """Brief description of what this command does."""
    await bot.send(f"/{player} Your response here.\r")
    logger.info(f"Ran @mycommand for {player}")

Then in core/connection.py, add one import line in the "Load command modules" section:

import commands.mycommands  # noqa: F401 - registers @mycommand

License

MIT License — free to use, modify, and share. See LICENSE for details.

Created with Love <3 by Mark Laudenbach in Iowa USA!

About

Modern bot for MajorMUD written in Python with its own webserver and Discord support!

Resources

Readme
MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages