Mistle Mudbot

Python-based Telnet helper for connecting to MUD servers, handling login flows, and optionally running an automated "agent" alongside interactive play.

Features

• Lightweight wrapper (TelnetClient) around telnetlib with sane defaults and context-manager support.
• Loads credentials and connection settings from a local .env file.
• Interactive console session that mirrors server output and lets you type commands directly.
• Optional agent mode that runs on a background thread and can dispatch automated commands without blocking manual input.
• Pluggable agent selection via environment variables (built-in SimpleAgent, extendable with custom classes).

Requirements

• Python 3.10+
• A reachable Telnet-based MUD server

Quick Start

1. Create a virtual environment and install dependencies:

   pip install -e .
   

2. Copy .env.example (if available) or create a .env file in the project root, then fill in the connection details described below.

3. Run the client:

   python app.py
   

4. Type commands directly into the console. Press Ctrl-C to exit; the client will send any configured shutdown command to the MUD.

Environment Variables

All variables can be placed in the .env file (one KEY=value per line) or provided through the shell environment.

Variable	Required	Description
MISTLE_HOST	✅	DNS name or IP of the target MUD server.
MISTLE_PORT	✅	Telnet port number (will be cast to int).
MISTLE_USER	❌	Username or character name; sent automatically after login banner, if provided.
MISTLE_PASSWORD	❌	Password sent after the username. Leave blank for manual entry.
MISTLE_LOGIN_PROMPT	❌	Prompt string that signals the client to send credentials (e.g., "Name:"). When omitted, the client just waits for the initial banner.
MISTLE_EXIT_COMMAND	❌	Command issued during graceful shutdown (after pressing Ctrl-C). Useful for quit/save macros.
MISTLE_AGENT_MODE	❌	Enable agent thread when set to truthy values (1, true, yes, on). Defaults to interactive-only mode.
MISTLE_AGENT	❌	Select which agent class to instantiate when agent mode is active. Accepted values: simple (default), explore (requires ExploreAgent inside agent.py), or custom spec module:ClassName.

Agent Development

• Implement new agents by subclassing agent.Agent and overriding observe() and decide().
• Register the agent by either:
  • Adding the class to agent.py and referencing it in MISTLE_AGENT (e.g., explore if the class is named ExploreAgent).
  • Placing the class elsewhere and configuring MISTLE_AGENT to your_module:YourAgent.
• observe(output) receives the latest server text; decide() returns the next command string or None to stay idle.
• Commands issued by the agent are throttled to one per second so manual commands can still interleave smoothly.

Danger Zone

• The Telnet session runs until you interrupt it. Make sure the terminal is in a state where Ctrl-C is available.
• When adding new agents, guard any long-running logic to avoid blocking the agent thread.

Contributing

Feel free to open issues or submit pull requests for additional MUD-specific helpers, new agents, or quality-of-life improvements.

---

Happy MUDding!