Concepts on StompyMUX Documentation

Source layout

Mon, 01 Jan 0001 00:00:00 +0000

The MUX server is organized by responsibility beneath src/mux.

server contains platform definitions, configuration parsing, server state, lifecycle, logging, timers, signals, and file caches.
support contains reusable containers, buffer helpers, and string utilities.
objects owns game objects, exact-name Lua storage, flags, and powers.
world owns player, object, matching, movement, and presentation behavior.
commands owns native command dispatch, queues, literal parsing, and macros.
communication owns channels and speech.
network owns client descriptors, Telnet, sockets, and event scheduling.
persistence owns SQLite-backed MUX data.
lua owns the Lua runtime integration.
help owns indexing, rendering, and command handlers for the markdown help system (see Help system).

Project code includes MUX interfaces through paths rooted at mux/; it does not depend on the include-directory search order. Types exposed by MUX use descriptive PascalCase names. Functions use snake_case, and implementation details remain private to their owning module unless another translation unit needs them.

Help system

Mon, 01 Jan 0001 00:00:00 +0000

The help command serves markdown articles with TOML frontmatter, indexed and rendered entirely inside stompymux (see src/mux/help). There is no separate indexing binary and no distinction between help and wizhelp - per-article visibility is controlled by the wizard_only frontmatter key instead.

This page documents the engine side of the system, for contributors to the StompyMUX codebase itself. It is not the place to document any particular game’s help content - that content lives in game/help/ and is up to each game’s admins to write and maintain.

Channel administration

Mon, 01 Jan 0001 00:00:00 +0000

Wizards administer communication channels with @chan. Running it without a self-management must provide Lua commands that enforce its desired policy and switch prints the available operations. Mortals cannot invoke @chan. A game that wants to offer mortal self-management must provide Lua commands that enforce its desired policy and self-management must provide Lua commands that enforce its desired policy and call the appropriate channel functionality.

Create and inspect channels

Create a channel, make it public if desired, and inspect the result:

Styled object text

Mon, 01 Jan 0001 00:00:00 +0000

Object names, descriptions, and inside descriptions support a small, declarative markup language. It replaces the old dependency on softcode color escapes without restoring softcode evaluation; OSC link actions occur only when a user activates a rendered link.

@name drone=[fg=bright-cyan]Aegis[/]
@desc drone=A shell of [fg=#d78700]burnished amber[/] metal.
@idesc dropship=[fg=#8090ff bold]Cool blue light[/] fills the cabin.

Syntax

[color=COLOR] changes the foreground; the existing fg name remains an alias. [bg=COLOR] changes the background. [bold], [blink], [underline], and [inverse] enable formatting. Multiple directives can share one tag when separated by whitespace, for example [fg=blue bg=white bold]. A grouped tag creates one style scope, so one [/] restores every setting that it changed. [reset] restores terminal defaults and closes all open styles. Use [[ for a literal opening bracket.

Text encoding

Mon, 01 Jan 0001 00:00:00 +0000

The server uses UTF-8 for all client text. Telnet connections default to UTF-8 and negotiate UTF-8 with the CHARSET option when the client supports it. Malformed UTF-8 commands are rejected instead of being partially interpreted.

Messages, descriptions, attribute values, room and thing names, exit names and aliases, macro expansions, channel history, help files, and Lua-generated text may contain UTF-8. SQLite text loaded by the server must contain valid UTF-8. Legacy ANSI styling remains supported because its escape sequences are ASCII bytes within the UTF-8 stream.

Telnet negotiation

Mon, 01 Jan 0001 00:00:00 +0000

The game uses libtelnet for Telnet command framing and option negotiation. A new connection negotiates terminal type (TTYPE), window size (NAWS), UTF-8 character set, server status (MSSP), output compression (MCCP2), GMCP, and the RFC 1572 NEW-ENVIRON option.

TTYPE and MTTS

The server requests the Telnet Terminal-Type option and sends up to three TTYPE SEND sub-negotiations after the client agrees. This follows the MUD Terminal Type Standard (MTTS) convention: the first response names the MUD client, the second identifies its terminal emulation, and the third can be an MTTS <bitvector> capability report.