{"id":18162290,"url":"https://github.com/mudpuppy-rs/mudpuppy","last_synced_at":"2025-05-07T15:01:40.133Z","repository":{"id":258854867,"uuid":"868540960","full_name":"mudpuppy-rs/mudpuppy","owner":"mudpuppy-rs","description":"A terminal MUD client with a customizable interface and Python scripting.","archived":false,"fork":false,"pushed_at":"2025-04-28T13:43:29.000Z","size":607,"stargazers_count":8,"open_issues_count":3,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-28T14:46:26.008Z","etag":null,"topics":["linux","macos","mud","mud-client","telnet","terminal","windows"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mudpuppy-rs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-10-06T16:40:07.000Z","updated_at":"2025-04-28T13:43:31.000Z","dependencies_parsed_at":"2025-04-21T13:43:08.749Z","dependency_job_id":"b9b55cb2-35ac-4acb-8915-4221cad82f6b","html_url":"https://github.com/mudpuppy-rs/mudpuppy","commit_stats":null,"previous_names":["mudpuppy-rs/mudpuppy"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mudpuppy-rs%2Fmudpuppy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mudpuppy-rs%2Fmudpuppy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mudpuppy-rs%2Fmudpuppy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mudpuppy-rs%2Fmudpuppy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mudpuppy-rs","download_url":"https://codeload.github.com/mudpuppy-rs/mudpuppy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252902604,"owners_count":21822259,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["linux","macos","mud","mud-client","telnet","terminal","windows"],"created_at":"2024-11-02T09:04:40.066Z","updated_at":"2025-05-07T15:01:40.069Z","avatar_url":"https://github.com/mudpuppy-rs.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![GitHub branch status](https://img.shields.io/github/actions/workflow/status/mudpuppy-rs/mudpuppy/rust.yml?style=for-the-badge)](https://github.com/mudpuppy-rs/mudpuppy/actions/workflows/rust.yml)\n[![GitHub Release](https://img.shields.io/github/v/release/mudpuppy-rs/mudpuppy?include_prereleases\u0026style=for-the-badge)](https://github.com/mudpuppy-rs/mudpuppy/releases)\n[![GitHub License](https://img.shields.io/github/license/mudpuppy-rs/mudpuppy?style=for-the-badge\u0026label=License)](https://github.com/mudpuppy-rs/mudpuppy?tab=MIT-1-ov-file#readme)\n[![Discord](https://img.shields.io/discord/1292557013276168203?style=for-the-badge\u0026label=Discord)](https://discord.gg/bRadchaGFq)\n\n# Mudpuppy\n\nA terminal [MUD] client with a customizable interface and Python scripting.\n\n\u003e The mudpuppy (Necturus maculosus) is the only completely aquatic salamander in\n\u003e Canada. It is also the largest salamander species in the country.[^1]\n\n[^1]: https://ontarionature.org/programs/community-science/reptile-amphibian-atlas/mudpuppy/\n\n[MUD]: https://en.wikipedia.org/wiki/Multi-user_dungeon\n\n# Status\n\n\u003e [!WARNING]\n\u003e Mudpuppy is presently an **unfinished prototype**. Do not attempt to use unless\n\u003e you are prepared to fix your own issues.\n\u003e\n\u003e Documentation is sparse and there is **NO** stability guarantee. Everything is\n\u003e subject to change without notice.\n\u003e\n\u003e Mudpuppy should work for a variety of MUD/MUSH/MUX/MUCK games, but it has\n\u003e primarily been tested with LP-style MUDs.\n\u003e\n\u003e Here be dragons^H^H^H^H^H^H^Hrabid saber-toothed mudpuppys.\n\nhttps://github.com/user-attachments/assets/d89ade8d-7a36-4f14-8e76-17598aaac9a2\n\n# Features\n\n* **Responsive TUI** - Mudpuppy is a terminal client, but it tries to be more\n  like a GUI app. It has a terminal user-interface (TUI) with built-in support\n  for panes and resizable sub-windows. The TUI scales and redraws as your\n  terminal changes size, making it great for use on mobile over SSH.\n\n* **Python** - the \"py\" in \"Mudpup**py**\" stands for Python :) Instead of Lua,\n  or a custom scripting language, Mudpuppy uses Python for customization and\n  extension.\n\n* **Async** - triggers, aliases, and other core client functions are\n  asynchronous. Your scripts can benefit from the Python `asyncio` ecosystem,\n  making it easy to take complex actions like sending HTTP requests without\n  blocking the client.\n\n* **Multi-Session** - Mudpuppy will let you connect to multiple MUDs with one\n  client instance. Your triggers/aliases/etc can be global, or specific to\n  a single MUD. It's easy to send commands from one session to another.\n\n* **Multi-platform** - Mudpuppy runs well on Linux, MacOS, and Windows (with or\n  without WSL).\n\n* **Small** - Mudpuppy is written in Rust and is less than 8mb in size. It has\n  no special runtime dependencies other than Python.\n\n# Quick Start\n\n1. Build the client from source.\n\nBinary releases will be provided in the future, but for now you will need to\nbe comfortable installing Rust and building Mudpuppy from source.\n\n2. Create a config file with details for your favourite MUD. The location of the\n   file will differ based on your OS.\n\n| OS      | Config file                                                      |\n|---------|------------------------------------------------------------------|\n| Linux   | `$HOME/.config/mudpuppy/config.toml`                             |\n| MacOS   | `/Users/$USERNAME/Library/Application Support/mudpuppy/config.toml` |\n| Windows | `C:\\Users\\$USER\\AppData\\Roaming\\mudpuppy\\config.toml`            |\n\nYou can also customize the location with the `MUDPUPPY_CONFIG` and\n`MUDPUPPY_DATA` environment variables.\n\n```toml\n[[muds]]\nname = \"Dune (TLS)\"\nhost = \"dunemud.net\"\nport = 6788\ntls = \"Enabled\"\n\n[[muds]]\nname = \"Dune (Telnet)\"\nhost = \"dunemud.net\"\nport = 6789\ntls = \"Disabled\"\n```\n\n3. Run Mudpuppy from a terminal, and get to hacking'n'slashing:\n\n```bash\nmudpuppy\n```\n\n# Documentation\n\n## User guide\n\nMudpuppy offers a [user guide] book that provides detailed information and\nexamples. It's the best place to get started.\n\n[user guide]: https://mudpuppy-rs.github.io/mudpuppy/user-guide/\n\n## API docs\n\nFor scripting purposes you might be interested in seeing [API documentation]\nfor the `mudpuppy_core` module as well as the other Python interfaces.\n\n[API documentation]: https://mudpuppy-rs.github.io/mudpuppy/api-docs/\n\n# Scripting\n\nPython scripts placed in the Mudpuppy config directory are automatically loaded\nwhen Mudpuppy is started. This is the principle mechanism of scripting: putting\nPython code that interacts with Mudpuppy through the `mudpuppy` and\n`mudpuppy_core` packages in your config dir.\n\nMudpuppy supports:\n\n* Aliases, matching on user input.\n* Triggers, matching on game output.\n* Timers, running on fixed intervals.\n* Commands, invoked with a special prefix.\n\nHelpful Python decorators and the async nature of Mudpuppy make creating complex\nbehaviours easy:\n\n```python\nimport logging\nimport asyncio\nfrom mudpuppy import alias\nfrom mudpuppy_core import mudpuppy_core\n\n@alias(mud_name=\"Dune\", pattern=\"^kill (.*)$\")\nasync def kill_headbutt(session_id: int, _alias_id: int, line: str, groups):\n    # Send through the original line so that we actually start combat in-game\n    # with the 'kill' command.\n    await mudpuppy_core.send_line(session_id, line)\n\n    # Wait for a little bit, and then give them a headbutt!\n    target = groups[0]\n    logging.info(f\"building up momentum for a headbutt attack on {target}\")\n\n    await asyncio.sleep(5)\n    await mudpuppy_core.send_line(session_id, f\"headbutt {target}\")\n```\n\nSee the _work-in-progress_ [user guide] and [API documentation] for more\ninformation.\n\n# Development\n\nMudpuppy's development environment is distributed as a [Nix flake] that can be\nactivated with `nix develop` in the project directory. This will setup the\nrequired Rust and Python dependencies as well as helpful development tools like\npre-commit hooks for formatting/linting.\n\nUsing the flake isn't mandatory to contribute to, or build Mudpuppy, but highly\nrecommended. If you are not using the Nix Flake you will need Rust 1.75+ and\nPython 3.12+ (_techincally Python 3.7+ may be compatible, but 3.12 is the most\ntested_).\n\n[Nix flake]: https://zero-to-nix.com/concepts/flakes\n\n## Building\n\n```bash\ncargo build           # debug - compiles faster, runs much slower!\ncargo build --release # release - compiles slowwww, runs very fast!\n```\n\n## Priorities\n\nRough development priorities:\n\n* Documentation.\n* Persistence for `/trigger`, `/alias`, `/timer`.\n* API/config stability.\n* Test coverage.\n* Styling/themes.\n* Multi-line input area support.\n* ????\n\n# Alternatives\n\nMudpuppy is inspired by many other great MUD clients. You may wish to try one of\nthese if Mudpuppy doesn't strike your fancy.\n\n* **[Blightmud]** - another terminal MUD client written in Rust. You may prefer\n  this client if you like Lua for scripting.\n\n* **[TinTin++]** - a well established terminal MUD client with a custom\n  scripting language. You may prefer this client if you value stability and\n  want a variety of features.\n\n* **[Mudlet]** - the best open-source GUI-based MUD client around. You may\n  prefer this client if you want to avoid the terminal in favour of a graphical\n  UI.\n\n[Blightmud]: https://github.com/blightmud/blightmud\n[TinTin++]: https://tintin.mudhalla.net/\n[Mudlet]: https://www.mudlet.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmudpuppy-rs%2Fmudpuppy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmudpuppy-rs%2Fmudpuppy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmudpuppy-rs%2Fmudpuppy/lists"}