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 source version: 2.5063-beta (tbaMUD 3.64), declared in configure.ac and src/constants.c.

The game combines character classes, races, feats, spells, and d20 combat with quests, crafting, wilderness exploration, and vessels. Builders create content in game with Oasis OLC and attach local behavior through DG Scripts and named special procedures. MUD clients connect over Telnet; the separate web client provides browser access.

Requirements

• Linux or a compatible environment, including Ubuntu under WSL2.
• A C compiler supporting the GNU C23 features checked by configure.
• Autoconf, Automake, and Make; CMake 3.21+ is a supported alternative.
• MariaDB/MySQL with client development headers, plus crypt, GD, curl, OpenSSL, pthread, and json-c libraries for the standard build.
• Runtime configuration and world data under lib/, plus an initialized database schema, prepared by the setup script below.

Quick Start

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

git clone https://github.com/LuminariMUD/Luminari-Source.git
cd Luminari-Source
./scripts/deployment/deploy.sh --dev

Run this fresh-install setup as your normal user with sudo available for package and database setup. For local development, decline its optional systemd-service prompt and use the repository's autorun supervisor:

MUD_PORT=4100 ./scripts/autorun/autorun.sh
./scripts/autorun/autorun.sh status

Autorun starts in the background and supervises server restarts. Connect a MUD client to localhost:4100; stop the local supervisor and server with ./scripts/autorun/autorun.sh stop. For a direct foreground debugging session, use ./bin/luminari -d lib instead of starting autorun.

The game port is 4100, including local development. Keep existing runtime configuration and autorun's MUD_PORT set to 4100. The loopback health listener defaults to port 8182. Once the server is running, check readiness with:

./scripts/operations/healthcheck.sh

Deployment stops if an existing lib/etc/config selects another game port, including the old generated 4101 default. Set its active DFLT_PORT entries to DFLT_PORT = 4100 and rerun deployment; existing configuration is preserved.

Production uses game port 4100 through luminari.service. Deployment also supports noninteractive and managed-service modes; inspect the options with ./scripts/deployment/deploy.sh --help.

Local headers and credentials are untracked: preserve existing src/campaign.h, src/mud_options.h, src/vnums.h, lib/mysql_config, and lib/.env. Development tooling that checks the environment requires APP_ENV=development in lib/.env; the tracked environment example defaults to production and must be adapted for a local checkout. Ollama, InterMUD-3, and Discord connections are not required for ordinary local development.

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

Build and Test

For an already configured checkout, Autotools is the preferred incremental build:

make -j"$(nproc)"
make test && make install

If configure or Makefile is missing, run autoreconf -fvi and ./configure first. make test runs the production-linked CuTest suite and registered shell regressions. Always follow it with make install, which installs an immutable build under bin/releases/, updates bin/luminari, and removes the root-level luminari artifact. An already running process continues using its current executable until restarted.

The focused protocol parser harness is separate:

make -C unittests/CuTest protocol-parser

For CMake, explicitly enable tests in a fresh build directory:

cmake -S . -B build -DBUILD_TESTS=ON
cmake --build build -j"$(nproc)"
ctest --test-dir build --output-on-failure
cmake --install build

See the testing guide for fixture, database, sanitizer, and subsystem-specific checks. The badges above report the latest matching workflow runs on master; workflow path filters may skip README-only commits.

Architecture

One select-based game loop connects player commands, scheduled updates, and a shared world. Game systems run inside the server; DG Scripts add behavior to rooms, mobiles, and objects, while Oasis OLC lets builders edit the world in game. Special-procedure gateways support typed handlers and legacy callbacks under src/spec/ and the owning feature directories.

flowchart TB
    players["Players and builders<br/>MUD clients"]

    subgraph server["LuminariMUD server | GNU C23"]
        loop["Network and game loop<br/>comm.c"]
        commands["Command dispatch<br/>interpreter.c"]
        ticks["Heartbeat and events<br/>Scheduled world updates"]
        game["Game systems<br/>Characters, combat, magic, quests<br/>Wilderness, vessels, crafting"]
        scripts["DG Scripts<br/>Room, mobile, object triggers"]
        specials["Special procedures<br/>Typed and legacy gateways"]
        olc["Oasis OLC<br/>In-game world editing"]
    end

    database[("MariaDB / MySQL<br/>Accounts, characters, help<br/>and subsystem data")]
    world[("World files | lib/world/<br/>Rooms, mobiles, objects<br/>Zones, shops, quests, triggers")]

    players <-->|"Commands / text"| loop
    loop --> commands
    loop --> ticks
    commands --> game
    ticks --> game
    commands --> scripts
    ticks --> scripts
    commands --> specials
    ticks --> specials
    commands --> olc
    game <-->|"Persist / load"| database
    olc -->|"Save authored content"| world
    game ---|"World loaded by db.c"| world

    classDef entry fill:#172c43,stroke:#80b9d8,color:#ffffff
    classDef runtime fill:#173e44,stroke:#6dbcb4,color:#ffffff
    classDef content fill:#3e334b,stroke:#bc9acd,color:#ffffff
    classDef storage fill:#493d28,stroke:#d4a853,color:#ffffff
    class players,loop entry
    class commands,ticks,game runtime
    class scripts,specials,olc content
    class database,world storage
    style server fill:#f0f5f8,stroke:#7893a7,color:#172c43

Loading

This overview shows the main execution and content paths, rather than every subsystem dependency. See the architecture guide for details.

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/MySQL stores accounts, characters, help, and subsystem data. Flat files under lib/world/ remain the authored room, mobile, object, zone, shop, quest, and trigger sources. Help content is maintained in both the database and lib/text/help/help.hlp. See environment boundaries for local and production data handling.

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 is complete through Phase 07: registry validation, event gateways, declarative assignments, source ownership, shared helpers, and initial typed handlers are implemented. Legacy callback compatibility and single-name world bindings remain supported. Phase 06 retained the existing runtime shop/quest wrappers and closed without adding general persisted procedure chains or new zone/world hooks.

See the architecture guide, Phase 06 decisions, and Phase 07 validation. For broader development history and current work, see the changelog and GitHub Issues.

LuminariMUD Ecosystem

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.