| Build status |
|---|
 |
 |
  |
 |
 |
TinyMUSH 4 is a modern, actively maintained Multi-User Shared Hallucination (MUSH) server. It represents a comprehensive modernization of the TinyMUSH codebase, focusing on robustness, maintainability, and alignment with contemporary C standards.
TinyMUSH 4 builds upon decades of MUSH development heritage while introducing significant architectural improvements, enhanced safety mechanisms, and a more flexible module system. Whether you're running a social roleplaying game, an educational environment, or a creative collaborative space, TinyMUSH 4 provides a solid, extensible foundation.
Current Status: Active development (Alpha)
- Modern Build System: CMake-based build with fast incremental compilation (ccache, LTO support)
- LMDB Database Backend: Lightning Memory-Mapped Database replaces GDBM as default (see Database Backend)
- Enhanced Safety: Comprehensive stack-safe string operations, memory tracking, bounds checking
- Modular Architecture: Dynamic module loading system with template skeleton for rapid development
- Improved Robustness: Fixed critical bugs, eliminated buffer overflows, crash prevention
- Better Developer Experience: Streamlined API, clear documentation, regression test suites
- Code Modernization: Aligned with modern C standards, cleaned up legacy code patterns
- Simplified Configuration: Centralized module management, easier customization
TinyMUSH 4 uses LMDB (Lightning Memory-Mapped Database) as the default storage backend, replacing the legacy GDBM backend. LMDB offers significant advantages:
Performance Benefits:
- Memory-mapped I/O: Direct memory access eliminates serialization overhead
- Zero-copy reads: Data accessed directly from mapped memory pages
- MVCC (Multi-Version Concurrency Control): Readers never block writers
- Crash resilience: Full ACID transactions with automatic recovery
- Optimized writes: Copy-on-write B+ tree structure minimizes disk I/O
Operational Advantages:
- No corruption: Atomic operations prevent partial writes and database corruption
- Concurrent access: Multiple readers without locking, consistent snapshots
- Small footprint: Minimal overhead, efficient memory usage
- Cross-platform: Portable across Linux, macOS, BSD, Windows
- Active maintenance: Modern, well-maintained library with ongoing development
Migration from GDBM:
GDBM remains available for backward compatibility but is considered legacy and will be removed in a future release. To migrate existing databases:
# 1. Build with GDBM backend
mkdir -p build && cd build
cmake -DUSE_LMDB=OFF -DUSE_GDBM=ON ..
cmake --build . --target install-upgrade# 2. Export flatfile with GDBM backend
cd ../game
./netmush --dbconvert < game/db/netmush.db > migration.flat# 3. Rebuild with LMDB backend
rm -rf build && cd build
cmake ..
cmake --build . --target install-upgrade# 4. Load flatfile with LMDB backend
cd ../game
./netmush --load-flatfile ../migration.flatImportant: Migrate to LMDB as soon as possible. GDBM support will be deprecated and eventually removed from TinyMUSH.
See INSTALL.md for detailed backend configuration and migration instructions.
# Clone repository
git clone https://github.com/TinyMUSH/TinyMUSH.git
cd TinyMUSH
# Install dependencies (Ubuntu/Debian)
apt install build-essential cmake libcrypt-dev liblmdb-dev libgdbm-dev libpcre2-dev
# Build and install
mkdir -p build && cd build
cmake ..
cmake --build . --target install-upgrade
# Start server
cd ../game
./netmush
# Connect: telnet localhost 6250
# Login as God: connect #1 potrzebieSee INSTALL.md for comprehensive installation instructions and backend selection (LMDB by default, GDBM optional). The dbconvert utility converts databases between formats.
- Rich Softcode Language: Powerful scripting with 200+ built-in functions
- Flexible Permissions: Granular control with flags, powers, and locks
- Persistent Storage: LMDB-backed database with automatic checkpointing, crash resilience, and zero-copy reads
- Zone-based Organization: Hierarchical object management
- Attribute System: Extensible object properties with inheritance
- Module System: Load custom C modules dynamically at runtime (mail and comsys included by default)
- Regression Testing: Comprehensive test suites for functions and commands
- Memory Debugging: Built-in allocation tracking and leak detection
- Safe String API: Prevent buffer overflows with XSAFE* macros
- API Documentation: Auto-generated Doxygen docs at https://tinymush.github.io/TinyMUSH/
- Flexible Configuration: Text-based config with runtime @admin adjustments
- Backup Tools: Automated database dumps and flatfile conversion
- Logging System: Configurable logging with multiple log types
- Command Aliases: Customize command names for user preference
- Compatibility Modes: Support for MUX/Penn command variations
TinyMUSH 4 is guided by four core principles:
- Modernize codebase to ensure long-term viability
- Align with current C standards (C11+)
- Replace deprecated APIs and unsafe functions
- Support contemporary build tools and platforms
- Reduce code complexity and technical debt
- Improve code organization and modularity
- Enhance documentation at all levels
- Simplify contribution process for new developers
- Eliminate undefined behavior and memory safety issues
- Add comprehensive bounds checking
- Implement thorough error handling
- Build extensive regression test coverage
- Provide clean module API for custom extensions
- Maintain backward compatibility where feasible
- Enable easy feature addition without core modifications
- Support diverse use cases through configuration
TinyMUSH 3 emerged from a merger of the TinyMUSH 2.2 and TinyMUX codebases, combining the strengths of both servers. The project maintained near-complete backward compatibility while introducing stability improvements and new features.
TinyMUSH 3 Development Team:
- David Passmore (core developer)
- Lydia Leong (lead developer, 3.1-3.2)
- Robby Griffin (joined 3.0 beta 18)
- Scott Dorr (joined 3.0 beta 23)
- Eddy Beaupré (joined 3.1 p1, continuing into 4.0)
TinyMUSH 3 went through several major versions:
- 3.0: Initial merged release, bug fixes, feature additions
- 3.1: Enhanced stability, GDBM database, improved caching
- 3.2: Performance optimizations, additional features
- 3.3: Experimental branch (never released, discontinued)
TinyMUSH 4 represents a significant evolution, focusing on modernization rather than feature additions. While maintaining the essence of TinyMUSH 3, version 4 prioritizes code quality, safety, and developer experience.
Major Changes:
- Complete CMake conversion (removed Autoconf/Make)
- Stack-safe string operations throughout codebase
- Modular architecture with dynamic loading
- Enhanced error handling and crash prevention
- Modern memory management patterns
- Comprehensive documentation overhaul
- Active regression testing framework
The server is currently in alpha development, with ongoing work to ensure stability before beta release.
See INSTALL.md for complete installation instructions.
Quick install:
mkdir -p build && cd build
cmake ..
cmake --build . --target install-upgrade
cd ../game && ./netmush| Document | Description |
|---|---|
| README.md | This document - project overview and quick start |
| INSTALL.md | Comprehensive installation guide |
| CONTRIBUTING.md | How to contribute to TinyMUSH |
| CODE_OF_CONDUCT.md | Community guidelines and code of conduct |
| SECURITY.md | Security policy and vulnerability reporting |
| KNOWN_BUGS.md | Current known issues and recent fixes |
| NEWS.md | Important announcements and updates |
| COPYING.md | License information (Artistic License) |
| AUTHORS.md | Credits and acknowledgments |
Located in docs/Code/:
| Document | Description |
|---|---|
| MODULES_DEVELOPMENT.md | Complete guide to module development |
| ALLOC_DOCUMENTATION.md | Memory management and safe string APIs |
| COMMANDS_AND_REGISTRIES_REFERENCE.md | Commands, functions, flags, powers, attributes |
TinyMUSH 4 includes the following modules enabled by default:
| Module | Description |
|---|---|
| Internal mail system with PennMUSH-compatible syntax | |
| comsys | Communication channels for multi-user chat |
| skeleton | Template for creating new modules (README) |
See INSTALL.md for module configuration and docs/Code/MODULES_DEVELOPMENT.md for creating custom modules.
Note: Historical documents are preserved for reference but may not reflect current TinyMUSH 4 practices.
Located in docs/Historical/:
| Document | Description |
|---|---|
| ChangeLog.md | TinyMUSH 3 version history |
| ChangeLog.History.md | TinyMUSH 2.x and TinyMUX 1.0 history |
| FAQ.md | Frequently asked questions (TinyMUSH 3 era) |
| MODULES.md | Legacy module documentation |
| CONVERTING.md | Database conversion guide |
Auto-generated Doxygen source code documentation:
https://tinymush.github.io/TinyMUSH/
Includes detailed API references for functions, structures, and macros used throughout the codebase.
We welcome contributions! See CONTRIBUTING.md for:
- How to report bugs and request features
- Development setup and workflow
- Code style guidelines
- Testing requirements
- Pull request process
For security vulnerabilities, see SECURITY.md.
- Check INSTALL.md and KNOWN_BUGS.md
- Search GitHub issues
- Email: tinymush@googlegroups.com
TinyMUSH is distributed under the Artistic License. See COPYING.md for details.
TinyMUSH 4.0 - Copyright © 1989-2025 TinyMUSH Development Team
Repository: https://github.com/TinyMUSH/TinyMUSH
Website: https://tinymush.github.io/TinyMUSH/