An LPC compiler, virtual machine and gamedriver for multi-user dungeons (MUDs).
LPC is a language for building persistent, multiplayer text worlds. You write rooms, creatures, player commands and game rules in LPC; the driver compiles and runs those objects, manages their lifetimes and connects them to players. The collection of LPC code that defines a game is its mudlib.
lpc-rs combines that model with a concurrent, transactional runtime. Player commands and scheduled callbacks can execute in parallel, while the runtime commits their game-state changes atomically and retries conflicts.
The project is under active development. It has a working compiler and networked server, but its LPC dialect and interfaces are still evolving. Existing mudlibs may need changes; the language and efun documentation describe the behaviour implemented here.
Start with Learn LPC if you have not written the language before: run a small program, then build objects and commands in a live game.
- LPC compilation and execution: preprocessing, type checking, multiple inheritance, closures, function pointers, arrays, mappings and byte strings, with diagnostics tied to source locations.
- Object lifecycle and world structure: loading and cloning, environments and inventories, scheduled call-outs, garbage collection, object cleanup and save/restore support. Objects can be loaded into the running game.
- Player interaction: login and input hooks, actions and grammar-based command rules, text formatting, terminal colour and Markdown rendering.
- MUD networking: Telnet, GMCP, MXP, MSSP and terminal capability negotiation; optional TLS connections and a certificate helper for Certbot-based renewal.
- Development tools: a command-line compiler/runner and a language server with editor diagnostics, built-in function completion and hover documentation.
You need a current stable Rust toolchain and your platform's native build tools
(a C compiler, linker and make). CI builds and tests on Linux. The commands
below use a POSIX shell.
Clone the repository:
git clone https://github.com/xxx/lpc-rs.git
cd lpc-rsInstall the gamedriver from the checkout:
cargo install --locked --path lpc-rs-drivercargo install builds optimised release binaries by default and installs them
in Cargo's binary directory, normally ~/.cargo/bin. Ensure that directory is
on your PATH. The game examples below use the installed driver.
The installed driver can run from any directory. Your mudlib and configuration are managed separately from the executable; the next section uses the bundled ulib to start a game.
The distribution includes ulib (microlib), a tiny mudlib for guest login and chat. Its documented source and apply examples provide a starting point for writing your own mudlib.
From the repository root, copy it somewhere you can edit and start it:
cp -R ulib ~/my-mud
cd ~/my-mud
lpc-rs-driver --env driver.envIn another terminal, connect with a Telnet client:
telnet 127.0.0.1 24960Enter a guest name when prompted. You should receive a welcome message,
The Common Room and a prompt bearing your name. Connect a second client with
another name and try say Hello!, who and emote waves.. Use help for the
command list and quit to disconnect. Stop the driver with Ctrl-C in its terminal.
Run from the copied directory so its relative configuration paths resolve.
It listens on loopback by default. Names last for the connection; no accounts
or conversations are saved. ulib/ ships with the source distribution, and
is copied separately from the installed driver binary. Its
guide covers configuration and adding commands, and its
apply reference maps every driver hook to an implementation
or disabled example.
Adapt ulib or supply your own master object for driver policy
and login, along with the objects that make up the game. Start with the
master hooks, especially
connect, and the player object's
logon hook.
Copy the configuration example:
cp default.env .envEdit LIB_DIR to point to your mudlib and MASTER_OBJECT to name its master
object. LIB_DIR is a host filesystem path; MASTER_OBJECT and other in-game
paths are rooted inside it. Set BIND_ADDRESS=127.0.0.1 for local development;
the default listens on all interfaces.
Then start the driver with that file:
lpc-rs-driver --env .envConfiguration comes from environment variables, optionally supplemented by an
explicitly selected dotenv file. No .env file is loaded automatically.
Process variables override file entries with the same name; LPC_-prefixed
settings take precedence over their unprefixed forms. Use absolute paths in
your configuration when starting the driver from another directory.
See default.env for configuration options, including include paths, simulated efuns, execution limits and logging. The compiler cache guide covers retention budgets, idle expiration and native usage counters.
NULL_MODE=zero preserves zero-as-null behavior; NULL_MODE=distinct enables
a separate nil value. See null values for defaults, type
checks, and save-file behavior. Examples assume zero mode unless stated otherwise.
For TLS certificate issuance and renewal, install the optional certificate helper from the repository checkout:
cargo install --locked --path lpc-rs-certThe helper requires a separate Certbot installation; see the secure connections guide for setup.
A player command or scheduled callback starts a transaction. It reads a snapshot of the world and stages its changes privately; calls into other LPC objects share the same transaction. A single committer validates the reads and publishes accepted changes atomically. Conflicting attempts are discarded and run again against a fresh snapshot, within the task's execution allowance.
Player output and other deferred effects are delivered after a successful commit, so a discarded attempt does not send its messages to players. External I/O delivery is separate from the state commit and can still fail.
Transaction Town is an interactive explanation
of snapshots, conflicts, retries and committed output. Open
doc/transaction-town/index.html locally in
a browser; it works offline without a build or server. For runtime measurements
and troubleshooting, see transaction diagnostics.
| If you want to… | Start here |
|---|---|
| Write LPC for the first time | Learn LPC: a first program, then objects and player commands |
| Run and adapt a tiny mudlib | ulib guide, add a command, apply examples |
| Compare LPC drivers | Driver comparison and porting notes |
| Port Lima | Lima mudlib guide and port history |
| Learn the project's LPC terminology | Glossary |
| Look up compiler pragmas and their scope | Pragma reference |
| Understand values and callable functions | Types, functions and closures, references, argument spreading |
| Look up a built-in function | Efun reference |
| Inspect or replace named globals | variable_info, store_variable |
| Implement callbacks the driver calls | Master hooks, object hooks, living hooks, connection hooks |
| Add player commands | add_action, add_rule, parse_sentence |
| See how the parsing frontends share one engine | Parser Town · open the interactive tour locally in a browser |
| Explore garbage collection, roots, and cycles | Collector Town · open the interactive tour locally in a browser |
| Save and restore game data | save_object, restore_object, save_value, restore_value, save format |
| Upgrade live objects, clones, or the master and simulated efuns | request_object_recompile |
The command-line compiler helps you check LPC files, inspect their compiled instructions and run small examples while developing a mudlib. The language server adds editor diagnostics, completion and hover documentation. Install either tool as needed from the repository checkout:
cargo install --locked --path lpc-rs-lpcc
cargo install --locked --path lpc-rs-lspThe compiler guide covers running a single object,
checking files with --check and inspecting instructions with -S. Use
--config /path/to/driver.env to load your mudlib's configuration. See the
language server guide for editor setup.
The repository is a Cargo workspace. Its executable crates are:
| Crate / binary | Purpose |
|---|---|
lpc-rs-lpcc |
Run an LPC file, check it with --check, or print instructions with -S |
lpc-rs-driver |
Run the game server |
lpc-rs-lsp |
Run the language server over stdio |
lpc-rs-cert |
Manage TLS certificates, with issuance and renewal via Certbot |
The root lpc-rs crate contains the compiler,
interpreter, transactional runtime,
efuns and command system.
Supporting crates provide core types, bytecode instructions, function metadata,
errors, configuration and Telnet protocol handling.
To build the whole workspace without installing it:
cargo build --release --workspace --lockedThe executables are in target/release/ and can be run directly, for example
./target/release/lpc-rs-driver --env /path/to/mud.env.
During development, Cargo can rebuild and run a binary from the checkout:
cargo run -p lpc-rs-driver -- --env .envThis uses the debug profile by default; add --release before -- to run an
optimised build.
Run the workspace checks from the repository root:
cargo build --workspace
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --check
RUSTDOCFLAGS="-D warnings" cargo doc --workspaceUse --workspace for builds, tests and Clippy: the root package alone does not
check the sibling crates. The formatting configuration uses nightly-only
options; stable rustfmt's warnings about those options are expected.
Tests live alongside the Rust code and in tests; performance workloads live in benches and examples. See AGENTS.md for repository conventions and profiling commands.
cargo-mutants checks whether tests detect changes to
production code. The current scope and exclusion rationales are maintained in
.cargo/mutants.toml. CI selection, sharding, tool versions
and job limits are defined in the mutation workflow.
Install the cargo-mutants version pinned by that workflow and cargo-nextest. From the repository root, list or test the configured scope:
cargo mutants --workspace --list
CARGO_TARGET_DIR="$PWD/target" cargo mutants --workspace --jobs 1 --output /tmp/lpc-rs-mutantsFor a local run limited to changed production lines, compare the working tree
with the desired base and pass the resulting patch to --in-diff:
git diff --no-ext-diff --no-textconv --unified=0 origin/master -- '*.rs' > /tmp/lpc-rs-mutants.diff
CARGO_TARGET_DIR="$PWD/target" cargo mutants --workspace --jobs 1 \
--in-diff /tmp/lpc-rs-mutants.diff --output /tmp/lpc-rs-mutantsMutation runs first check the unmodified tests, then test each change using
nextest. Continue using the workspace checks above for normal validation,
including doctests. Reports and per-mutation logs are written under
/tmp/lpc-rs-mutants/mutants.out/.
Inspect missed.txt for undetected changes and check timeout.txt and
unviable.txt separately; a timeout or compilation failure does not demonstrate
that an assertion caught the change. Verify mutants.json when narrowing a run.
Select downstream consumers when needed with --test-workspace=true or
--test-package. Keep exclusions narrow and document their rationale beside the
configuration entry.
MIT.