LuminariMUD

LuminariMUD is a text-based multiplayer game server implementing Pathfinder and D&D 3.5 mechanics on the tbaMUD/CircleMUD foundation. The supported server is written in GNU C23 and requires MariaDB or MySQL at runtime.

Current version: 2.5054-beta (tbaMUD 3.64).

Quick Start

On Ubuntu, Debian, or WSL2, the repository's one-command setup installs dependencies, prepares local configuration and world data, provisions MariaDB, builds the server, and installs bin/circle:

./scripts/deployment/deploy.sh

Then start the server:

./bin/circle -d lib

The checked-in runtime configuration defaults to game port 4100. Connect a MUD client to localhost:4100. The deployment script supports noninteractive, development, production, and managed-systemd modes; inspect the exact options with ./scripts/deployment/deploy.sh --help.

For a fresh clone, start with the onboarding checklist or the setup and build guide.

Development Check

Autotools is the preferred incremental build. The authoritative one-command test and installation gate is:

make test && make install

make test builds the production-linked CuTest suite and shell regressions. make install activates the tested immutable build under bin/releases/ and removes the root-level circle artifact.

Repository Structure

.
|-- src/          # GNU C23 server and game systems
|-- lib/          # Runtime configuration, text, and flat-file world data
|-- sql/          # Master schema and component migrations/verifiers
|-- scripts/      # Deployment, operations, debugging, and world tools
|-- unittests/    # Production-linked CuTest and focused harnesses
`-- docs/         # Maintained developer, builder, and operator documentation

MariaDB stores accounts, characters, help, and subsystem data. Flat files under lib/world/ remain the authored room, mobile, object, zone, shop, quest, and trigger sources. The server uses a single select-based game loop; DG Scripts provide content-local behavior and Oasis OLC provides in-game world editing.

Documentation

• Documentation index
• Architecture
• Development commands
• Deployment and CI/CD
• Environment boundaries
• Testing guide
• Incident response
• Operational API contracts
• Contributing

Player and builder orientation remains in Getting Started and the builder quickstart.

Project Status

The special-procedure architecture initiative completed Phases 00-02: registry safety and observability, call-site gateways, and validated declarative legacy assignments. Content extraction, shared mechanics, typed handlers, and conditional composition remain planned in the special-procedure refactor PRD.

LuminariMUD Eco-System

What we call the "Lumiverse":

• Sage GraphRAG lore and world building
• Luminari web client
• InterMUD-3 client
• Discord bridge
• Wilderness editor
• Mudlet interface

Contributing and Community

Read CONTRIBUTING.md before opening a pull request and CODE_OF_CONDUCT.md before participating in project spaces. Questions and bug reports can be raised through GitHub Issues.

License

Custom LuminariMUD code is dedicated to the public domain under the Unlicense. Inherited tbaMUD, CircleMUD, DikuMUD, and licensed game content retain their respective terms. See LICENSE and the legal notes for the project's complete notice.