stompymux.toml reference

game/stompymux.toml controls the running game server. It is TOML, organized into sections ([server], [battletech], [security], and so on). Configuration changes can be made through the appropriate wizard configuration commands (@admin) or by editing the file before starting the server. stompymux.toml includes game/aliases.toml (the stock command and flag abbreviations) via a top-level include array; add local aliases to stompymux.toml’s own [aliases.*] tables rather than editing aliases.toml directly, since an including file’s keys always win over anything pulled in through include.

Sections

Lua callbacks run with LuaJIT compilation enabled. Consequently, [lua] has no per-callback instruction limit: use bounded loops in trusted Lua modules. state_value_limit caps one persistent string, state_entry_limit caps the number of state entries on an object, and state_object_limit caps the total bytes of keys and values on an object. Their defaults are 65536, 1024, and 1048576 respectively.

Most directives are plain scalars (port = 5555, or, under [database], fork_dump = true). A few directives take other shapes:

• Flag/bitmask directives (mux.default_player_flags, mux.default_exit_flags, mux.default_room_flags, mux.default_thing_flags, and logging.log_options) are TOML arrays of strings. Logging event categories instead use individual booleans such as [logging.topics] security = true and all_commands = false.
• Alias directives ([aliases.*]) are tables mapping the alias to its target, e.g. "@cr" = "@create".
• Access directives ([access.*]) are tables mapping a command or list name to one or more permissions, e.g. "@dig" = ["wizard", "need_location"].
• Building commands are restricted to Wizards. There is no global building toggle or global_build command-access permission.
• Site directives ([sites]) are arrays of { address = "...", mask = "..." } tables, applied in file order.
• Named colors ([colors]) map a color name to an array of three integer RGB channels. Each channel must be from 0 through 255.
• OSC 8 presets ([osc8.presets]) map a preset name to a string of the flattened directives accepted on a styled link.

An unrecognized key is logged to stderr and skipped rather than aborting the whole file; a syntax error in the TOML itself aborts loading.

Named colors

The [colors] table defines custom names accepted by [fg=NAME], [color=NAME], and [bg=NAME] styled-text markup:

[colors]
"brand-blue" = [32, 96, 192]

Names are case-insensitive and may contain letters, digits, hyphens, and underscores. A name may be at most 60 characters. Custom names must not overlap an opaque CSS/X11 built-in name; a case-insensitive collision is a fatal configuration error and stops server startup. Built-ins are immutable and do not need entries in this table.

RGB colors are emitted directly for truecolor clients and mapped to the nearest xterm-256 or ANSI-16 color for less capable clients. A built-in name collision stops startup; other malformed entries are logged and skipped. When configuration files are included, normal table merge rules apply, so a color in the including file overrides a color with the same TOML key in an included file.

OSC 8 presets

The [osc8.presets] table defines reusable Tier 2–5 link configuration:

[osc8.presets]
button = 'color=white bg=green bold hover.bg=darkgreen'
poll = 'selection.group="demo-poll" selection.exclusive'

Names are case-sensitive, contain 1–60 URI-safe letters, digits, dots, underscores, tildes, or hyphens, and must begin with a letter or digit. Values use the same flattened directives accepted inside a styled link tag. Presets may be partial templates, but every link’s merged result must be valid. Invalid preset configuration stops startup. Definitions are immutable while the server runs and are sent once to each capable connection.

Default Lua parents

The [mux] section can assign an object-logic module to each newly created object type:

Paths are relative to game/lua/object_logic. Empty values disable automatic assignment for that type. Configuration changes apply only to objects created afterward and never backfill the database. @clone preserves the source object’s Lua parent, including an empty one, instead of using the configured type default.

Password and login security

Passwords are stored as Argon2id hashes through the vendored libsodium library. Each stored hash includes its salt, algorithm, and work factors. Password hashes are never recoverable, and legacy crypt(3) password hashes are not accepted.

These live under [security] in stompymux.toml.

The per-source tracker has room for 1,024 recent addresses and evicts the least recently refilled entry when full. A throttled connection receives the same generic failure response as an invalid login and is disconnected. Keep the global rate low enough that password verification cannot consume all event-loop time, and tune the Argon2id settings on the production host rather than aiming for a one-second hash.

The defaults intentionally favor a responsive telnet game server. They are lighter than libsodium’s interactive preset, so the firewall or host should also rate-limit new TCP connections to the game port.