86 lines
4.2 KiB
Markdown
86 lines
4.2 KiB
Markdown
# Mistle Mudbot
|
|
|
|
Python-based Telnet helper for connecting to MUD servers, handling login flows, and optionally running automated "agents" 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 always-on agent mode plus an on-demand `#execute <agent>` escape hatch for ad-hoc automations.
|
|
- Built-in agents (`SimpleAgent`, `ExploreAgent`) with a pluggable interface for custom behaviours.
|
|
|
|
## Requirements
|
|
|
|
- Python 3.10+
|
|
- A reachable Telnet-based MUD server
|
|
|
|
## Quick Start
|
|
|
|
1. Create a virtual environment and install dependencies:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
5. When *not* running in agent mode you can kick off one-off automations from the prompt:
|
|
|
|
```text
|
|
#execute explore
|
|
```
|
|
|
|
The command remains interactive while the agent works in the background and stops automatically a few seconds after things quiet down.
|
|
|
|
## 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 full-time 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` for `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.
|
|
- `ExploreAgent` showcases a richer workflow: it sends `schau`, identifies German nouns, inspects each with `untersuche`, and prints `[Agent]` progress updates like `Explored 3/7 — untersuche Tisch`.
|
|
|
|
## On-Demand Agents
|
|
|
|
- When `MISTLE_AGENT_MODE` is **off**, you can trigger an ephemeral agent at any time with `#execute <agent_spec>`.
|
|
- The syntax accepts the same values as `MISTLE_AGENT` and reuses the `build_agent` helper, so `#execute simple`, `#execute explore`, or `#execute mypackage.mymodule:CustomAgent` are all valid.
|
|
- On-demand runs share the current session, respect the one-command-per-second limit, and stop automatically after a few seconds of inactivity.
|
|
|
|
## 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!
|