A powerful, extensible MUD (Multi-User Dungeon) proxy built with Python 3.12+ and asyncio. BastProxy sits between your MUD client and MUD server, providing features like triggers, aliases, logging, and a rich plugin system.
- Asynchronous Architecture: Built on Python's asyncio for efficient handling of multiple connections
- Plugin System: Highly modular with hot-reload capabilities
- Telnet Protocol Support (planned): GMCP, MSDP, MSSP, MCCP and MXP are not handled yet. The design is in ADR-0001 (Proposed), and the work is tracked in #58 (MCCP), #59 (GMCP and MSDP), #60 (MSSP) and #61 (MXP)
- Event-Driven: Comprehensive event system for plugin interaction
- API Framework: Centralized API registry for plugin communication
- Command System: Flexible command parsing and execution
- Trigger System: Pattern matching on MUD output
- Multiple Clients: Support for multiple simultaneous client connections
- Data Tracking: Comprehensive tracking of data flows and modifications
- Python 3.12 or newer
- uv (for dependency management) or pip
-
Clone the repository:
git clone https://github.com/endavis/bastproxy.git cd bastproxy -
Install dependencies:
uv sync --all-extras
Or for development:
pip install -e ".[dev]"
BASTPROXY_HOME must point at an existing, writable directory. BastProxy keeps its data, plugin settings, user plugins and logs under it, and importing bastproxy fails without it. .envrc defaults it to ~/bastproxy.
Basic usage:
uv run bastproxyWith options:
uv run bastproxy --port 9999 --IPv4-address localhostCommand-line options:
--portor-p: Port to listen on (default: 9999)--IPv4-address: IP address to bind to (default: localhost)--profileor-pf: Enable code profiling--quietor-q: Suppress console output (logs are still written to file)
- Start BastProxy with
uv run bastproxy - Connect your MUD client to
localhost:9999 - BastProxy will prompt you to configure your MUD connection
- Once configured, BastProxy connects to your MUD server
- Run
#bp.core.help.topicto see the in-proxy guides
Configuration files are stored in $BASTPROXY_HOME/data/plugins/. Each plugin maintains its own configuration.
- clients: Manage clients
- colors: Ansi/Xterm color functions
- commands: Parse and handle commands
- errors: Show and manage errors
- events: Handle events
- fuzzy: Do fuzzy matching
- help: Guides to using the proxy (#bp.core.help.topic)
- log: Handles changing and testing of logging configuration
- mudcmds: Queue commands to the mud
- pluginm: Manage plugins
- proxy: Control the proxy
- settings: Plugin to handle settings
- sqldb: Hold the SQL DB baseclass
- ssc: Class to save settings that should not stay in memory
- timers: Handle timers
- triggers: Handle triggers
- utils: Utility functions
- watch: Watch for specific commands from clients
User plugins go in $BASTPROXY_HOME/plugins/<package>/<plugin>; see the plugin system docs.
The Plugin Developer Guide covers the plugin file structure, metadata, the Plugin export, reloading, hooks and events, commands and triggers.
# Install with development dependencies
uv sync --all-extras
# Or through doit
uv run doit install_dev
# Install pre-commit hooks
uv run doit pre_commit_install# Run all tests
uv run doit test
# Run with coverage
uv run doit coverage
# Run a specific test file
uv run pytest tests/libs/test_persistentdict.py# Format code
uv run doit format
# Lint code
uv run doit lint
# Type checking
uv run doit type_check
# Run all checks
uv run doit checkIf ~/bastproxy does not exist, point BASTPROXY_HOME at a directory that does, for example BASTPROXY_HOME=$PWD uv run doit check.
bastproxy/
├── src/bastproxy/ # The package (entry point: bastproxy:main)
│ ├── libs/ # Core libraries
│ │ ├── api/ # API framework
│ │ ├── asynch/ # Async helpers
│ │ ├── info/ # Info helpers
│ │ ├── net/ # Network handling
│ │ ├── plugins/ # Plugin loading system
│ │ └── records/ # Data tracking
│ └── plugins/ # Plugin directory
│ ├── _baseplugin/ # Base plugin class
│ ├── core/ # Core plugins
│ ├── debug/ # Debug plugins
│ └── test/ # Test plugins
├── tests/ # Test suite
│ ├── libs/ # Tests for libs/
│ └── plugins/ # Tests for plugins/
└── docs/ # Documentation
Runtime data is not stored in the repository. It lives under $BASTPROXY_HOME: data/ (plugin data and logs) and plugins/ (user plugins).
Contributions are welcome! Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests. The full issue, branch, commit and PR workflow is in .github/CONTRIBUTING.md.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes following our coding standards
- Write tests for your changes
- Ensure all checks pass (
uv run doit check) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
The networking code is based on:
- telnetlib3 - Telnet protocol implementation
- akrios_frontend - MUD client frontend
This project is licensed under the MIT License - see the LICENSE file for details.
- Issues: GitHub Issues
- Documentation: docs/
- Original BastProxy concept and design by Bast
- Community contributors and testers
- The MUD community for continued support