TinyMUX

Frequently Asked Questions

General Questions

Where can I find games that run TinyMUX?

There are many games available across a wide variety of themes and sizes. These directories can help you find active games:

  • MudConnector — Comprehensive MUD/MUSH listing
  • MudStats — Statistics on server and genre popularity
  • Grapevine — Modern MUD network with web-based client capabilities

What is TinyMUX?

TinyMUX is a text-based game server for creating and hosting MUSHes (Multi-User Shared Hallucinations). It provides a platform for text-based role-playing, socializing, and world-building. TinyMUX is part of the MU* family of servers, which includes TinyMUSH, PennMUSH, and RhostMUSH.

The server emphasizes quality, performance, and features, making it suitable for games of all sizes — from small private games to large public worlds with hundreds of players.

What are the current versions?

  • TinyMUX 2.14 is the current ALPHA development branch. It contains major new features including a JIT compiler, SQLite storage backend, Lua scripting, a routing system, and protocol support for GMCP, MSSP, and WebSocket.
  • TinyMUX 2.13 is the current BETA stabilization branch with ongoing bug fixes.

What’s new in TinyMUX 2.14?

TinyMUX 2.14 is the most significant release in the project’s history. Major highlights:

JIT Compiler — Softcode expressions are compiled through an AST → HIR → SSA → optimize → native code pipeline. The dynamic binary translator supports x86-64 (Linux, macOS, Windows) and AArch64 (ARM64). Compile-time constant folding handles 35+ functions. The classic character-by-character parser has been replaced with an AST-based evaluator.

SQLite Storage Backend — The entire database (objects, attributes, comsys, @mail) lives in a single SQLite database with write-through on every mutation. @dump is just a WAL checkpoint — no flatfile serialization, no fork. Crash durability is immediate.

Lua 5.4 Scripting — Sandboxed Lua execution with bytecode cache and mux.* bridge API. Lua bytecode is also JIT-compiled through the same pipeline as softcode.

Routing System — Room-to-room pathfinding with static route tables, per-zone routing with cross-zone gateways, lock-validated paths, and @walk/@patrol NPC movement primitives.

Protocol Support — GMCP (Generic MUD Communication Protocol), MSSP (Mud Server Status Protocol), and WebSocket (RFC 6455) with same-port auto-detection and wss:// support.

Unicode 16.0 — Grapheme cluster indexing throughout, NFC normalization at storage, Unicode collation (UCA/DUCET) as default sort order, CJK width-aware formatting.

50+ New Functions — JSON operations, cryptographic functions, statistical functions, grapheme-cluster string operations, channel query functions, zone listing, Lua bridge, routing queries, and many functions adopted from PennMUSH and RhostMUSH.

Hardening — Async-signal-safe signal handlers, per-site OOM recovery, PCRE2 with JIT, PCG-XSL-RR-128/64 PRNG, and 917 smoke tests.

See the full Version History for complete details.

Do I have to use the SGP minimal database?

No, the SGP (Sandbox Globals Project) minimal database is included as a convenience but is completely optional. If you prefer to start with a truly minimal database, simply delete or rename the netmux.db file before starting your server for the first time. The server will automatically create a minimal database with just two objects (Limbo and Wizard).

How do I get support for my TinyMUX server?

Support for TinyMUX is available through several channels:

Installation & Setup

Do I need Cygwin Tools to run TinyMUX on Windows?

No, TinyMUX is written to run natively on Windows without requiring Cygwin or any other UNIX compatibility layer. Pre-built binaries for Windows are provided in the distribution.

However, it is also possible to take the UNIX distribution of TinyMUX and compile it under Cygwin if you prefer. Both approaches work, but pay attention to which distribution you download (sources for UNIX/OSX, sources for Windows, or pre-built binaries for Windows).

What are the minimum system requirements for TinyMUX?

TinyMUX is designed to be efficient and can run on modest hardware. Minimum requirements:

  • CPU: 1 GHz processor (2 GHz+ recommended)
  • RAM: 512 MB (1 GB+ recommended for JIT-enabled builds)
  • Disk Space: 100 MB for installation, plus space for your database
  • Operating System: Windows 10/11, Linux, macOS, FreeBSD, or most Unix-like systems
  • Network: Stable internet connection with the ability to forward ports

Requirements increase with the size of your game database and number of connected players. The JIT compiler benefits from additional memory for its code cache.

How do I configure TinyMUX to run on a specific port?

Edit your netmux.conf (or GAMENAME.conf) file and look for the port configuration option. Change it to your desired port number:

port 4201

You can also configure TinyMUX to listen on multiple ports by adding additional port lines:

port_ssl 4202

Remember to open/forward these ports in your firewall and router settings.

What are the build requirements for TinyMUX 2.14?

TinyMUX 2.14 requires:

  • C++17 compiler (GCC 9+, Clang 10+, MSVC 2019+)
  • OpenSSL (Unix) or Schannel (Windows) — SSL is always enabled
  • PCRE2 — regular expression library (replaces PCRE)
  • SQLite3 (bundled)
  • Lua 5.4 (optional, bundled)

Optional configure flags:

  • --enable-jit — Enable the JIT compiler for softcode expressions
  • --enable-realitylvls — Enable Reality Levels

What is a JAR file and how do I unzip it?

Some TinyMUX distributions are compressed in JAR format (not to be confused with Java’s JAR archives). You’ll need the JAR utility from ARJ Software to extract them.

Alternatively, you can download TinyMUX in ZIP or tar.gz format, which can be extracted with more common tools.

Configuration

How do I change the name of my game?

There are two places to change your game’s name:

  1. In mux.config (Unix) or muxconfig.vbs (Windows), change the GAMENAME variable
  2. In your GAMENAME.conf file, edit the mud_name parameter to set the formal name of your game

For example: mud_name My Awesome MUSH

How do I set up SSL/TLS encryption?

In TinyMUX 2.14, SSL is always enabled. Add these options to your configuration file:

port_ssl 4202
ssl_certificate_file mygame.crt
ssl_certificate_key mygame.key
# If your key is password-protected
ssl_certificate_password yourpassword

You’ll need to generate SSL certificates using OpenSSL or a similar tool, or obtain them from a certificate authority.

How do I set up guest characters?

To configure guest characters:

  1. Create a prototype guest character using @pcreate
  2. Add these lines to your configuration file:
guest_char_num #dbref
guest_prefix Guest
number_guests 5

Where #dbref is the database reference number of your prototype guest character. For more details, see the GUESTS file.

Database Management

How do I back up my database?

TinyMUX includes a Backup script that creates comprehensive backups. To use it:

  1. @shutdown the game
  2. Change to the game directory: cd game
  3. Run: ./Backup (Unix) or Backup.bat (Windows)
  4. Restart the game with ./Startmux or Startmux.bat

In TinyMUX 2.14, the database is a SQLite file. The Backup script creates a safe copy. You can also use SQLite’s .backup command or simply copy the database file while the server is stopped.

What happened to memory-based vs. disk-based operation?

In TinyMUX 2.14, the MEMORY_BASED build option has been removed. SQLite is the only storage backend. The database uses write-through on every mutation with WAL (Write-Ahead Logging) for performance. @dump performs a WAL checkpoint — there is no flatfile serialization step and no fork. Crash durability is immediate.

For TinyMUX 2.13 and earlier, see the MEMORY file for information about memory-based vs. disk-based operation.

How do I reset the password for Wizard (#1)?

If you’ve forgotten the Wizard password, you have several options:

  1. Use the Omega Flatfile Converter to modify your flatfile and reset the password
  2. Edit the encrypted password directly in your flatfile if you have a backup
  3. Start with a clean database and rebuild your game

Remember to change the default password (potrzebie) immediately after installation.

Conversion & Migration

How do I convert my database from another MUSH server?

The easiest way to convert between different MUSH server formats is to use the Omega Flatfile Converter. This tool supports conversion between TinyMUSH 3.x, PennMUSH, RhostMUSH, and TinyMUX formats.

Follow the instructions in the CONVERSION file for detailed steps on importing databases from other server platforms.

When I try to move my flatfile from a Unix box to a Windows box, I get assertion errors. Why?

This typically happens when you transfer the flatfile via FTP in ASCII mode instead of binary mode. The line endings get converted (CRLF/NL), which corrupts the file format.

Always transfer database files in BINARY mode. Newer flatfile formats are more tolerant of line ending differences, but it’s still best practice to use binary mode for all database transfers.

Troubleshooting

My server crashes with a ‘SIGSEGV’ error. What does this mean?

A SIGSEGV (Segmentation Fault) error indicates that the server tried to access memory it shouldn’t. This is usually caused by one of the following:

  • Database corruption
  • A bug in the server code
  • Memory issues on your server

Check your log files for more details about what was happening when the crash occurred. Report crashes to brazilofmux@gmail.com with as much information as possible, including log files and steps to reproduce the issue.

Players are getting “Connection refused” errors when trying to connect. How do I fix this?

This usually means players can’t reach your server’s port. Check these items:

  1. Verify the server is running (ps aux | grep netmux on Unix)
  2. Confirm the port configuration in your .conf file
  3. Check that your firewall allows incoming connections on that port
  4. Ensure you’ve set up port forwarding on your router if behind NAT
  5. Test locally first with telnet localhost portnumber

My @mail and channels aren’t working after upgrading. What’s wrong?

In TinyMUX 2.14, comsys and @mail are always present (the have_comsys and have_mailer config options have been removed). If upgrading from 2.13 or earlier, the migration to SQLite storage will convert your mail.db and comsys.db automatically.

If you’re upgrading from a much older version, you might need to convert your mail and comsys databases. See the CONVERSION file for details.

Platform-Specific Questions

Are there any issues with macOS/OS X?

TinyMUX generally runs well on macOS, including Apple Silicon (M1/M2/M3/M4). The JIT compiler supports AArch64 natively on ARM64 Macs.

A few notes:

  • The -E option in gcc on macOS may be broken. Skip the make depend step in the compilation instructions.
  • TinyMUX sees macOS as another flavor of Unix/BSD, so most Unix instructions apply.

How do I start TinyMUX automatically on server boot?

The method depends on your operating system:

Linux (systemd):

[Unit]
Description=TinyMUX Game Server
After=network.target

[Service]
Type=forking
User=mush
WorkingDirectory=/path/to/mux/game
ExecStart=/path/to/mux/game/Startmux
ExecStop=/path/to/mux/game/Shutdown

[Install]
WantedBy=multi-user.target

Then enable with: systemctl enable tinymux

Windows: Create a scheduled task to run Startmux.bat at system startup, or use a service wrapper like NSSM.

Advanced Features

What are Reality Levels and how do I use them?

Reality Levels allow you to create multiple “layers” of reality in the same room. This is useful for games that need to represent different planes of existence, such as World of Darkness settings with the Umbra, Shadowlands, or Faerie realms.

To use Reality Levels, you need to enable them at compile time with ./configure --enable-realitylvls. Then configure them in your conf file according to the instructions in the REALITY.SETUP file.

How do I extend TinyMUX with custom code?

TinyMUX can be extended in several ways:

  • Lua scripting (2.14): Use @lua for server-side Lua 5.4 scripts with the mux.* bridge API. The most accessible extension method.
  • Softcode: Use MUSHcode to create in-game systems and commands. The traditional approach.
  • Modules: Dynamically-loadable COM modules for adding functionality without modifying the core code.
  • local.cpp extensions: Add custom C++ code to extend the server’s functionality. See the LOCAL file for details.

How does the JIT compiler work?

The JIT compiler in TinyMUX 2.14 automatically compiles frequently-executed softcode expressions into native machine code. The pipeline:

  1. Tokenization: A Ragel-generated scanner tokenizes the expression.
  2. Parsing: Tokens are parsed into an Abstract Syntax Tree (AST).
  3. HIR: The AST is lowered to a High-level Intermediate Representation.
  4. SSA: HIR is converted to Static Single Assignment form.
  5. Optimization: Constant folding, peephole optimization, superblock merging.
  6. RV64 Codegen: Optimized SSA is lowered to RISC-V 64-bit virtual instructions.
  7. Dynamic Binary Translation: RV64 instructions are translated to the host platform’s native code (x86-64 or AArch64).

Compiled code is cached in SQLite. The JIT is transparent — softcode works identically whether interpreted or compiled. Enable with ./configure --enable-jit.

Use jitstats() to monitor JIT performance and astbench() for head-to-head AST vs. JIT benchmarking.

How do I use the routing system?

The routing system in TinyMUX 2.14 provides room-to-room pathfinding:

@route/set <source room>=<destination room>/<next hop exit>

Query routes with route(<source>, <destination>) for the next hop and routepath(<source>, <destination>) for the full path.

For NPC movement:

@walk <object>=<destination room>
@patrol <object>=<room1> <room2> <room3>

Routing supports per-zone tables, cross-zone gateways, and lock validation on exits.

How do I use GMCP?

GMCP (Generic MUD Communication Protocol) allows structured data exchange between the server and compatible clients (Mudlet, etc.):

  • Clients that support GMCP negotiate it automatically via telnet option 201.
  • Inbound GMCP packets trigger the A_GMCP attribute on the player with %0 = package name and %1 = JSON data.
  • Send GMCP frames from softcode: gmcp(<player dbref>, <package>, <json>)

How do I use @cron for scheduled tasks?

@cron uses standard Unix cron syntax to trigger attributes on a schedule:

@cron <object>/<attribute>=<minute> <hour> <day> <month> <dow>

For example, to run an attribute every day at midnight:

@cron me/DAILY_TASK=0 0 * * *

Supports ranges, lists, steps, and month/day-of-week names. View scheduled tasks with @crontab and remove them with @crondel.

Note: Cron entries are in-memory and not persisted across restarts. Use @startup to recreate them.

How do I use SSL encryption with TinyMUX?

In TinyMUX 2.14, SSL support is always compiled in. Configure it in your config file:

port_ssl 4202
ssl_certificate_file mygame.crt
ssl_certificate_key mygame.key
ssl_certificate_password yourpassword  # If needed

Players can connect securely using SSL-capable clients like MUSHclient, Atlantis, Mudlet, or via WebSocket (wss://).