Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mudpuppy-rs/mudpuppy
A terminal MUD client with a customizable interface and Python scripting.
https://github.com/mudpuppy-rs/mudpuppy
linux macos mud mud-client telnet terminal windows
Last synced: 11 days ago
JSON representation
A terminal MUD client with a customizable interface and Python scripting.
- Host: GitHub
- URL: https://github.com/mudpuppy-rs/mudpuppy
- Owner: mudpuppy-rs
- License: mit
- Created: 2024-10-06T16:40:07.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2024-10-24T01:35:50.000Z (21 days ago)
- Last Synced: 2024-10-24T17:15:49.683Z (20 days ago)
- Topics: linux, macos, mud, mud-client, telnet, terminal, windows
- Language: Rust
- Homepage:
- Size: 234 KB
- Stars: 2
- Watchers: 2
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/mudpuppy-rs/mudpuppy/actions/workflows/rust.yml)
[](https://github.com/mudpuppy-rs/mudpuppy/releases)
[](https://github.com/mudpuppy-rs/mudpuppy?tab=MIT-1-ov-file#readme)
[](https://discord.gg/bRadchaGFq)
# Mudpuppy
A terminal [MUD] client with a customizable interface and Python scripting.
> The mudpuppy (Necturus maculosus) is the only completely aquatic salamander in
> Canada. It is also the largest salamander species in the country.[^1]
[^1]: https://ontarionature.org/programs/community-science/reptile-amphibian-atlas/mudpuppy/
[MUD]: https://en.wikipedia.org/wiki/Multi-user_dungeon
# Status
> [!WARNING]
> Mudpuppy is presently an **unfinished prototype**. Do not attempt to use unless
> you are prepared to fix your own issues.
>
> Documentation is sparse and there is **NO** stability guarantee. Everything is
> subject to change without notice.
>
> Mudpuppy should work for a variety of MUD/MUSH/MUX/MUCK games, but it has
> primarily been tested with LP-style MUDs.
>
> Here be dragons^H^H^H^H^H^H^Hrabid saber-toothed mudpuppys.
# Features
* **Responsive TUI** - Mudpuppy is a terminal client, but it tries to be more
like a GUI app. It has a terminal user-interface (TUI) with built-in support
for panes, resizable sub-windows, and so on. The TUI scales and redraws
as your terminal changes size, making it great for use on mobile over SSH.
* **Python** - the "py" in "Mudpup**py**" stands for Python :) Instead of Lua,
or a custom scripting language, Mudpuppy uses Python for customization and
extension.
* **Async** - triggers, aliases, and other core client functions are
asynchronous. Your scripts can benefit from the Python `asyncio` ecosystem,
making it easy to take complex actions like making HTTP requests without
blocking the client.
* **Multi-Session** - Mudpuppy will let you connect to multiple MUDs with one
client instance. Your triggers/aliases/etc can be global, or specific to
a single MUD. It's easy to send commands from one session to another.
* **Multi-platform** - Mudpuppy runs well on Linux, MacOS, and Windows (with or
without WSL).
* **Small** - Mudpuppy is written in Rust and is less than 8mb in size. It has
no special runtime dependencies other than Python.
# Quick Start
1. Download a release:
```bash
# TODO...
```
Advanced users may want to build from source. TODO: link to instructions.
2. Create a config file with details for your favourite MUD. The location of the
file will differ based on your OS.
| OS | Config file |
|---------|------------------------------------------------------------------|
| Linux | `$HOME/.config/mudpuppy/config.toml` |
| MacOS | `/Users/$USERNAME/Library/Application Support/mudpuppy/config.toml` |
| Windows | `C:\Users\$USER\AppData\Roaming\mudpuppy\config.toml` |
```toml
[[muds]]
name = "Dune (TLS)"
host = "dunemud.net"
port = 6788
tls = "Enabled"
[[muds]]
name = "Dune (Telnet)"
host = "dunemud.net"
port = 6789
tls = "Disabled"
```
See this example config file for more information. TODO: link to config file.
3. Run Mudpuppy from a terminal, and get to hacking'n'slashing:
```bash
mudpuppy
```
# Documentation
## User guide
Mudpuppy offers a [user guide] book that provides detailed information and
examples. It's the best place to get started.
[user guide]: https://mudpuppy-rs.github.io/mudpuppy/user-guide/
## API docs
For scripting purposes you might be interested in seeing [API documentation]
for the `mudpuppy_core` module as well as the other Python interfaces.
[API documentation]: https://mudpuppy-rs.github.io/mudpuppy/api-docs/
# Scripting
Python scripts placed in the Mudpuppy config directory are automatically loaded
when Mudpuppy is started. This is the principle mechanism of scripting: putting
Python code that interacts with Mudpuppy through the `mudpuppy` and
`mudpuppy_core` packages in your config dir.
Mudpuppy supports:
* Aliases, matching on user input.
* Triggers, matching on game output.
* Timers, running on fixed intervals.
* Commands, invoked with a special prefix.
Helpful Python decorators and the async nature of Mudpuppy make creating complex
behaviours easy:
```python
import logging
import asyncio
from mudpuppy import alias
from mudpuppy_core import mudpuppy_core, SessionId, AliasId
@alias(mud_name="Dune", pattern="^kill (.*)$", name="Kill and headbutt")
async def kill_headbutt(session_id: SessionId, _alias_id: AliasId, line: str, groups):
# Send through the original line so that we actually start combat in-game
# with the 'kill' command.
await mudpuppy_core.send_line(session_id, line)
# Wait for a little bit, and then give them a headbutt!
target = groups[0]
logging.info(f"building up momentum for a headbutt attack on {target}")
await asyncio.sleep(5)
await mudpuppy_core.send_line(session_id, f"headbutt {target}")
```
See the _work-in-progress_ [user guide] and [API documentation] for more
information.
# Development
Mudpuppy's development environment is distributed as a [Nix flake] that can be
activated with `nix develop` in the project directory. This will setup the
required Rust and Python dependencies as well as helpful development tools like
pre-commit hooks for formatting/linting.
Using the flake isn't mandatory to contribute to, or build Mudpuppy, but highly
recommended. If you are not using the Nix Flake you will need Rust 1.74+ and
Python 3.12+ (_techincally Python 3.7+ may be compatible, but 3.12 is the most
tested_).
[Nix flake]: https://zero-to-nix.com/concepts/flakes
## Building
```bash
cargo build # debug - compiles faster, runs much slower!
cargo build --release # release - compiles slowwww, runs very fast!
```
## Priorities
Rough development priorities:
* Documentation.
* Persistence for `/trigger`, `/alias`, `/timer`.
* API/config stability.
* Test coverage.
* Styling/themes.
* Multi-line input area support.
* ????
# Alternatives
Mudpuppy is inspired by many other great MUD clients. You may wish to try one of
these if Mudpuppy doesn't strike your fancy.
* **[Blightmud]** - another terminal MUD client written in Rust. You may prefer
this client if you like Lua for scripting.
* **[TinTin++]** - a well established terminal MUD client with a custom
scripting language. You may prefer this client if you value stability and
want a variety of features.
* **[Mudlet]** - the best open-source GUI-based MUD client around. You may
prefer this client if you want to avoid the terminal in favour of a graphical
UI.
[Blightmud]: https://github.com/blightmud/blightmud
[TinTin++]: https://tintin.mudhalla.net/
[Mudlet]: https://www.mudlet.org/