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.

BattleTech Architecture

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

BattleTech is a domain-oriented package rooted at src/btech. Its public boundary is src/btech/include/btech; MUX code must not include any other BattleTech directory.

Ownership

Each domain owns both its state and the operations that change that state:

Domain	Primary ownership
`core`	Runtime context, xoshiro256** random generator, events, and heartbeat
`special`	Native special-object registry and typed object operations
`map`	Battle maps, terrain, map objects, and cached LOS state
`unit`	Mechs, templates, parts, sections, critical slots, and weapons
`movement`	Ground, jump, aerospace, DropShip, and landing behavior
`sensors`	Contacts, LOS, scanners, ECM, C3, TAG, and spotting
`combat`	Attacks, damage, criticals, missiles, artillery, and ejection
`repair`	Repair facilities, jobs, validation, and repair events
`autopilot`	Autopilot state, commands, paths, targeting, and autogun
`economy`	Stores, cargo, and part costs
`character`	Skills, experience, advantages, and personal combat
`ui`	Shared menu, notification, and presentation primitives
`scripting`	Native XCODE-value and script-function adapters
`persistence`	SQLite schema and domain persistence adapters
`integration`	Narrow adapters to MUX-owned services

The context-owned gameplay generator is xoshiro256**, seeded once from Linux OS entropy during BTech startup. Its runtime state is not persisted.

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[/]
@attribute/set drone/Desc=A shell of [fg=#d78700]burnished amber[/] metal.
@attribute/set dropship/Idesc=[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.

Player account state

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

Player authentication and activity metadata are typed server state rather than object attributes. The SQLite player_state table stores password hashes, aliases, the last login and site, and aggregate login counters. Login attempts are normalized in player_login_history; remembered page recipients are stored in player_last_page_recipients.

All wall-clock values use signed Unix epoch seconds in SQLite. Commands that show login history render those values as ISO 8601 UTC. Game ticks and elapsed durations are not wall-clock timestamps and remain in their native units.