Scripting on StompyMUX Documentation

Overview

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

LuaJIT modules live under game/lua in three separate roots:

lua/
 object_logic/ # @lua/parent modules and their private helpers
 global_logic/ # globally matched command and scheduled modules
 packages/ # shared require-only helpers

Object and global logic

Attach a module to an object with the wizard-only @lua/parent <object>=<path>.lua; the path is relative to object_logic, and omitting it clears the attachment. Each object uses only its own direct attachment. See Object scripting for the full module contract, the native event catalog, and how load errors are handled.

Object scripting

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

Object Lua modules live under game/lua/object_logic. Attach one to an object with the wizard-only command:

@lua/parent <object>=<path>.lua

The path is relative to object_logic; for example, @lua/parent #123=hello.lua selects game/lua/object_logic/hello.lua. Paths must be relative .lua files and cannot escape into global_logic or packages. Omit the path to clear an attachment.

The [mux] settings default_thing_lua_parent, default_room_lua_parent, default_exit_lua_parent, and default_player_lua_parent assign direct Lua parents to newly created objects of each type. Paths use the same object_logic-relative format as @lua/parent. Changing a default does not update existing objects. Clones preserve the source object’s Lua parent (or its lack of one) rather than receiving the type default.

Object Flags

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

Object flags are independent boolean properties on database objects. Native code stores each flag in a has_<name>_flag field and in a matching SQLite column. There is no packed flag word and no reserved legacy bits.

Flags are displayed after the object type as compact letters. A script or administrator should use the full flag name when issuing a command because ANSI and XCODE both use X:

@set <object>=<flag>
@set <object>=!<flag>

The mux Lua package does not currently expose direct flag getter or setter functions. Lua logic can invoke an appropriate native command with mux.command; queued commands run as God after the current callback finishes.

Object Powers

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

Object powers are independent boolean privileges stored on database objects. They are separate from object flags: flags describe object state and presentation, while powers grant an exception to normal server behavior. Native code stores each power in a has_<name>_power field and in a matching SQLite column.

IDLE is the complete set of powers currently registered by the MUX server. Historical MUX and BattleTech power names are not accepted.

Power summary

Power	Stored field and column	Native purpose
`IDLE`	`has_idle_power`	Exempts a connected player from the inactivity timeout.

IDLE

The IDLE power prevents the maintenance timer from disconnecting a connected player when the descriptor’s inactivity timeout expires. It is meaningful only on a player with an active connection; setting it on another object type has no native effect.

Commands

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

Lua command modules return a commands array. Each entry has a native Lua pattern, a handler function, and an optional access level:

return {
 commands = {
 {
 pattern = "^say%s+(.+)$",
 access = "wizard",
 handler = function(ctx, message)
 mux.notify(ctx.enactor, "You said: " .. message)
 return true
 end,
 },
 },
}

Omit access, or set it to "public", to allow everyone. Set it to "wizard" to allow Wizards and God, or "god" to allow only God. Values are case-sensitive. Invalid values cause module validation and reload to fail.

Global logic

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

Global Lua logic modules live under game/lua/global_logic. Every .lua file in that tree is discovered recursively during startup and @lua/reload. Files are loaded in lexical relative-path order, so use domain-oriented paths such as player/help.lua, world/travel.lua, and wizard/maintenance.lua. Use numeric prefixes only when deliberate cross-domain priority is necessary. Use @lua/check to validate every Lua module before reloading.

Each global module returns a table containing commands:

return {
 commands = {
 {
 pattern = "^global%-hello$",
 handler = function(ctx)
 mux.notify(ctx.enactor, "Hello, world, from a global Lua command!")
 return true
 end,
 },
 },
}

Global handlers run after local and zone Lua command matching declines the command. Master-room exits and other non-command behavior are unchanged. Matching stops at the first global handler that returns true; false or nil allows the next handler to try.

Interactive flows

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

Softcode has no interactive-input primitive; Lua does, through mux.flow_start and a module’s flows table. A flow drives a connected player’s own descriptor through a menu, a confirmation, or a multi-step form, one line of input at a time, without the player prefixing every line with a command.

return {
 commands = {
 {
 pattern = "^delete%-character$",
 handler = function(ctx)
 mux.flow_start(ctx.descriptor, "confirm_delete.lua", "confirm")
 return true
 end,
 },
 },
 flows = {
 confirm = function(ctx)
 if ctx.input == nil then
 return { action = "repeat", prompt = "Delete this? (y/n) " }
 end
 if ctx.input:match("^[Yy]") then
 return { action = "done", message = "Deleted." }
 end
 return { action = "cancel", message = "Cancelled." }
 end,
 },
}

Starting a flow

mux.flow_start(descriptor, module, first_step) attaches a flow to the given descriptor and immediately shows its first prompt. descriptor is ctx.descriptor from the command or event that is starting the flow - flows are always driven from a live connection, never from a queued or scheduled context, so ctx.descriptor is only present when one exists (see Commands). module is resolved the same way require resolves a name: relative to the calling module’s own root, without repeating the root name. Raises a Lua error if the descriptor doesn’t exist, already has a flow running, or the module has no such flow step.

Validating and Reloading

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

You can validate and reload your game’s Lua files from within the game without a full restart.

Validating Lua

To check your Lua scripts for validity, run the following from in-game with a Wizard character:

@lua/check

@lua/check recursively verifies every .lua file below game/lua/object_logic, game/lua/global_logic, and game/lua/packages. It checks module syntax, top-level imports, and the module return contract, including cron schedules. Global logic modules must export a nonempty commands or schedules table. It also checks every configured Luaparent path. Missing or unreadable paths are reported once per path with the number of objects that use that value, so a single deleted file does not produce one error for every affected object.