Skip to content
xxxPublic

About

An LPC compiler and gamedriver

Topics

Resources

Stars

7 stars

Watchers

1 watching

Forks

Latest commit

 

History

3,910 Commits

Folders and files

Repository files navigation

lpc-rs

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.

What's here

  • 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.

Build and install

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-rs

Install the gamedriver from the checkout:

cargo install --locked --path lpc-rs-driver

cargo 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.

Run 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.env

In another terminal, connect with a Telnet client:

telnet 127.0.0.1 24960

Enter 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.

Run your own mudlib

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 .env

Edit 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 .env

Configuration 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-cert

The helper requires a separate Certbot installation; see the secure connections guide for setup.

How execution works

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.

Documentation

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

Develop and debug LPC

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-lsp

The 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.

Work on the driver

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 --locked

The 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 .env

This 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 --workspace

Use --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.

Mutation testing

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-mutants

For 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-mutants

Mutation 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.

Licence

MIT.

About

An LPC compiler and gamedriver

Topics

Resources

Stars

7 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages