Guides

LP MUD with LPC

LP MUDs separate the game engine (driver) from game logic (mudlib) using the LPC language. This guide assumes Ubuntu 22.04 LTS and targets FluffOS 3.x with the Dead Souls 3.0 mudlib. You will compile the driver from source, establish secure runtime permissions, and configure live reloading workflows for rapid iteration without player disconnections.

60-90 minutes7 steps
FluffOS driver logo on dark terminal background
FluffOS maintains active development with modern LPC extensions
1

Compile FluffOS driver from tagged release

Clone the FluffOS repository and checkout a stable release tag rather than the development branch to avoid breaking changes. Create a build directory outside the source tree to keep the git repository clean. Run cmake with -DPACKAGE_ASYNC=ON and -DPACKAGE_DB=ON to enable async I/O and database support required by modern mudlibs.

build_fluffos.sh
git clone https://github.com/fluffos/fluffos.git
cd fluffos && git checkout v3.0.2023
mkdir build && cd build
cmake -DPACKAGE_ASYNC=ON -DPACKAGE_DB=ON ..
make -j$(nproc)

⚠ Common Pitfalls

  • •Do not compile as root; build permissions affect runtime security
  • •Missing libmysqlclient-dev causes cryptic cmake errors about MYSQL_LIBRARY
  • •Building in the source directory pollutes git status and complicates updates
2

Acquire and validate Dead Souls mudlib structure

Download Dead Souls 3.0 from the distribution archive and verify the directory hierarchy matches FluffOS expectations. The mudlib must contain cmds/, daemons/, std/, and log/ directories at minimum. Check that secure/, tmp/, and save/ directories exist with write permissions for the driver user, as FluffOS enforces strict path validation in master.c.

setup_mudlib.sh
wget tar -xzf dead-souls-3.0.tar.gz ls -la dead-souls/lib/secure/ chmod 755 dead-souls/lib/log dead-souls/lib/save

⚠ Common Pitfalls

  • •Dead Souls 2.x uses incompatible master.c hooks for older MudOS drivers
  • •Missing secure/ directory causes immediate boot failure with 'Cannot find master.c' errors
  • •Windows line endings in .c files break compilation on Linux drivers
3

Configure runtime directories and driver config

Create a runtime directory structure that separates volatile data (logs, player saves) from version-controlled mudlib code. Copy the example config file from the FluffOS build directory and edit the mudlib directory path, port number, and address settings. Set valid_write_path and valid_read_path restrictions to prevent LPC code from escaping the mudlib root.

config.local.ini
mudlib directory : /opt/mud/lib
port number : 6666
address : 0.0.0.0
master file : /secure/master
call out memory : 4096
max cost : 5000000

⚠ Common Pitfalls

  • •Using relative paths in the config file breaks when starting the driver from different working directories
  • •Port numbers below 1024 require root privileges and should be avoided or proxied
  • •Forgetting to create the log directory before first boot causes silent startup failures
4

Initialize master object and security validation

The master.c object acts as the kernel for your LPC world. Before first boot, verify that master.c contains valid_write and valid_read functions that restrict file access to the mudlib tree. Test the configuration by running the driver with -d flag for debug output. Check stderr immediately for 'Cannot load master' errors which indicate path or permission issues in the secure/ directory.

test_boot.sh
./driver -d config.local.ini 2>&1 | tee boot.log
grep -i 'master\|error\|fail' boot.log

⚠ Common Pitfalls

  • •master.c syntax errors crash the driver before the telnet port opens
  • •Overly permissive valid_write paths allow players to overwrite system files via eval
  • •Missing simul_efun.c causes all inherited objects to fail compilation silently
5

Establish live coding workflow

LP MUDs support hot-reloading of LPC objects without player disconnection. Connect via telnet localhost 6666, create a wizard character, then modify a command file in cmds/wiz/. Use the update command in-game to reload the specific object. Verify changes by running the command immediately; syntax errors appear in the driver's stderr rather than to the player.

/lib/cmds/wiz/test.c
#include <lib.h>
inherit LIB_COMMAND;
int cmd(string str) {
    write("Testing live reload at " + ctime(time()) + "\n");
    return 1;
}

⚠ Common Pitfalls

  • •update command requires absolute path: update /cmds/wiz/test.c not update test
  • •Inheritance changes in parent classes require updating all children manually
  • •Destructing clones while players hold references causes runtime errors
6

Debug runtime errors via driver logs

When LPC code throws errors, FluffOS writes tracebacks to stderr with line numbers and object paths. Redirect stderr to a log file during production operation. Use the eval command as an immortal to test expressions and catch errors before deploying to command files. Check the driver log for 'Too deep recursion' or 'Out of ticks' which indicate infinite loops or expensive operations blocking the event loop.

debug_workflow.txt
tail -f /var/log/mud/driver.err | grep -A 5 'Error in'
# In-game:
eval return 1+1
eval return all_inventory(this_player())

⚠ Common Pitfalls

  • •Missing semicolons in eval statements crash the parsing thread for that user
  • •Stack traces reference compiled line numbers which may differ from .c files if #include directives shift offsets
  • •Catching errors in catch() blocks suppresses driver logging unless DEBUG is defined
7

Implement backup strategy for persistent state

Player data persists in save/player/ as individual .o files containing serialized LPC variable states. Before deploying code updates that change object structures, archive the save directory. Schedule rsync or tar operations via cron to remote storage, excluding tmp/ and log/ directories which contain transient data. Test restoration by copying .o files to a staging instance and verifying player login works before touching production.

backup.sh
tar -czf backup-$(date +%F).tar.gz /opt/mud/lib/save/ /opt/mud/lib/data/
rsync -avz --exclude='tmp/' /opt/mud/lib/save/ backup-server:/mud-backups/

⚠ Common Pitfalls

  • •Backing up while the driver is actively writing save files produces corrupted .o archives
  • •Changing struct definitions in inherited classes invalidates existing player save files
  • •cron jobs running as wrong user create permission mismatches on restoration

What you built

Your LP MUD now runs with compiled FluffOS driver and Dead Souls mudlib. The separation of driver and mudlib allows you to update game logic without recompiling C code, while the live reloading workflow enables rapid iteration. Monitor stderr logs for LPC runtime errors and maintain automated backups of the save/ directory before deploying structural changes to inherited objects.