Neolith LPMud Driver

Neolith is a LPMud driver forked from the MudOS v22pre5 codebase, maintained as an independent project since 2004. It focuses on improving code structure, style consistency, portability, multi-core host performance, testability, and long-term maintainability.

The name Neolith reflects our core goal: enabling tool-use in both the driver and LPC layers:

• Driver:
  • Refactored to use CMake and Ninja for C/C++ builds.
  • Supports console mode (or single-user mode), which enables command-line tools written in LPC.
  • Uses GoogleTest for unit testing.
  • Uses Python for automated integration tests (for example, smoke tests).
• LPC:
  • Preserves backward compatibility with the MudOS LPC language.
  • Hardens memory management, the mudlib execution loop, and core LPC primitives.
  • Adds foundational LPC/efun extensions for tool-use.

As LLM technology advances, text-first MUD frameworks, especially LPMud, are well suited for hosting LPC AI agents and facilitating information exchange in multi-agent AI systems. This positions Neolith as a general-purpose LPC platform for building a wide range of multi-user applications.

Features

• Platforms: Linux (primary), Windows (native MSVC and Clang-CL); Apple Clang (arm64).
• Async Workers: Blocking I/O (DNS, HTTP) is offloaded to worker threads through a unified event loop, so mudlib execution stays single-threaded and responsive. Rule of thumb: Concurrency lives in C/C++; LPC stays deterministic.
• Console Mode: Treats stdin/stdout as an interactive user; enables test automation, local debugging, and standalone MUD applications without a telnet client.
• UTF-8: Strings are counted byte-spans. Wide literals, explode(str, "") by character, and wide-char strsrch() work correctly across all string operators.
• JSON (PACKAGE_JSON): to_json() / from_json() efuns with explicit UTF-8 and embedded-null handling; from_json() accepts buffer for large payloads.
• CURL (PACKAGE_CURL): Non-blocking HTTP requests (perform_using(), perform_to(), in_perform()) without blocking the backend.
• Upgraded int / float / string: int is 64-bit everywhere; float uses native double precision; string is a true counted byte-span preserving embedded nulls.
• C99-Style Mixed Local Declarations Local variables can be declared after statements inside any { ... } block. See LPC Guide for details and current limits.
• Driver Robustness: LPC error handling migrated from longjmp() to C++ exceptions; heap allocation and string memory management hardened with RAII wrappers and const-correct APIs.

How To Build

Neolith is always released as source code. You need to build the Neolith executable from source code on your target platform. See INSTALL for detailed instructions on setting up build environment.

To utilize modern compiler toolchains and adding features from other packages, the build system of Neolith has been migrated to CMake. Several CMake presets are added to enable WSL + VS Code development:

cmake --preset linux
cmake --build --preset ci-linux

If the build finishes successfully, the neolith executable can be found in out/linux/src/RelWithDebInfo/.

See CMakePresets.json for details.

Usage

To start a MUD using Neolith LPMud Driver, you need a Neolith configuration file. Make a copy from src/neolith.conf and customize the settings for your needs. You can launch the MUD by the command:

neolith -f /path/to/neolith.conf

Quick Start & Testing

Neolith includes a minimal mudlib testsuite in examples/m3_mudlib/ and a pexpect-based testing framework in examples/m3_testbots.

# Start the M3 mudlib and login as console user
cd examples
/path/to/neolith -f m3.conf -c

For automated testing, first build Neolith with pr-* or ci-* preset, and run (requires hatch):

# Run automated testbots against M3 mudlib using locally built LPMud driver
cd examples/m3_testbots
hatch run smoke_test

See examples/README.md for comprehensive usage examples and troubleshooting.

If you are new to Neolith, the follow documentations are for you:

• Neolith Administrator Guide
• Neolith LPC Guide

Contributing

The decades-old C codes from MudOS/LPMud is quite messy and buggy in terms of modern C/C++ standards. Neolith project intended to make a good minimalist LPMud code base where open source contributors can start their LPMud not only with mudlibs, but also extensions to the LPMud Driver.

Please take a look into the following documents before you jump in:

• Neolith LPMud Driver Internals
• Neolith Developor Reference

License

Neolith is licensed under a fair-code architecture that balances permissive modification rights with non-commercial use requirements:

• Permissive Modifications: You may freely modify, refactor, and optimize the driver source code. There is no copyleft enforcement; your custom code changes remain entirely closed-source and proprietary if you choose.
• Non-Commercial Use: In accordance with the original copyright claims by Lars Pensjö, the driver may not be used for monetary gain or commercial purposes without explicit written permission from the original copyright holders.
• Community Contribution: While closed research forks and private deployments are fully permitted, contributors are encouraged to submit upstream pull requests to maintain core compatibility with the primary Neolith toolchain.

See LICENSE for the complete legal text.

Credits

Neolith is a LPMud Driver that powered the Eastern Stories 2 MUD (running since 1995). The code was modified from MudOS v22pre5, which is derived from the original LPMud by Lars Pensjö. Credits to original authors can be found in Credits.LPmud and Credits.MudOS.