mux.world on StompyMUX Documentation

mux.world.access

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

mux.world.access is an immutable namespace of typed Access constants. Use these values for the optional access field in Lua command entries; raw strings are rejected.

Constant	Allowed invokers
`PUBLIC`	Everyone. This is the default when `access` is omitted.
`WIZARD`	Wizards and God.
`GOD`	God only.

Constants compare by access identity and stringify to the displayed uppercase name. Unknown lookups and attempts to modify a constant or the namespace raise mux.access.invalid.

mux.world.flags

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

mux.world.flags is an immutable namespace of typed Flag constants. Use these values with Flags methods; raw strings are rejected.

Constant	Constant	Constant	Constant
`ANSI`	`AUDIBLE`	`AUDITORIUM`	`BLIND`
`CONNECTED`	`DARK`	`FLOATING`	`GAGGED`
`GOING`	`HALTED`	`IN_CHARACTER`	`LIGHT`
`MONITOR`	`NO_COMMAND`	`SAFE`	`SUSPECT`
`TRANSPARENT`	`WIZARD`	`ZOMBIE`

Constants compare by flag identity and stringify to the displayed uppercase name. Unknown lookups and attempts to modify the namespace raise mux.flag.invalid. Command-only aliases from [aliases.flags] are not constants. String conversion raises the invariant-only mux.internal error if a registered native flag name exceeds the internal conversion buffer.

mux.world.lock_passes

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

Tests a native object lock without emitting lock messages or performing the associated action.

Function

Synopsis

mux.world.lock_passes({
 object = object,
 enactor = enactor,
 lock = mux.world.locks.TRAVERSE,
 cause = cause,
 subject = subject,
})

Arguments

number or Object object: The object whose lock is tested.
number or Object enactor: The object attempting the action.
Lock lock: A typed mux.world.locks constant identifying the lock to test.
number or Object cause (optional): The object that caused the action. Defaults to enactor.
number or Object subject (optional): The object acted upon within the lock context. Defaults to enactor.

Returns

boolean passes: Whether the selected lock passes.

Notes

The function is unavailable during @lua/check. It evaluates the same Lua lock callback as the corresponding native action, but always sets ctx.silent to true and discards any lock messages returned by the callback.

mux.world.locks

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

mux.world.locks is an immutable namespace of typed Lock constants for mux.world.lock_passes. Each constant corresponds directly to a supported key in an object module’s locks table. Raw strings are rejected.

Constant	Object-module key	Purpose
`MATCH`	`match`	Prefer an object that passes during key-aware matching.
`TRAVERSE`	`traverse`	Traverse an exit.
`TAKE`	`take`	Take an object.
`USE`	`use`	Use an object.
`DROP`	`drop`	Drop an object.
`GIVE`	`give`	Give an object.
`RECEIVE`	`receive`	Receive a given object.
`ENTER`	`enter`	Enter an object, room, BattleTech unit, bay, or hangar.
`LEAVE`	`leave`	Leave an object or room.
`TELEPORT`	`teleport`	Teleport into a destination.
`TELEPORT_OUT`	`teleport_out`	Teleport out of an origin.
`LINK`	`link`	Link an exit or object.
`SET_HOME`	`set_home`	Set an object’s home to a destination.
`SPEAK`	`speak`	Speak in a location.
`CHANNEL_JOIN`	`channel_join`	Join a channel.
`CHANNEL_TRANSMIT`	`channel_transmit`	Transmit on a channel.
`CHANNEL_RECEIVE`	`channel_receive`	Receive channel traffic.
`IDENTIFY_BUILDING`	`identify_building`	Identify a BattleTech building contact.

local passes = mux.world.lock_passes({
 object = exit,
 enactor = ctx.enactor,
 lock = mux.world.locks.TRAVERSE,
})

Constants compare by lock identity and stringify as their uppercase name. Unknown lookups and attempts to modify a constant or the namespace raise mux.arg.invalid.

mux.world.powers

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

mux.world.powers is an immutable namespace of typed Power constants. Use these values with Powers methods; raw strings are rejected.

Constant	Purpose
`IDLE`	Exempts a connected player from the inactivity timeout.

Constants compare by power identity and stringify to their uppercase name. Unknown lookups and attempts to modify the namespace raise mux.power.invalid. String conversion raises the invariant-only mux.internal error if a registered native power name exceeds the internal conversion buffer.

local powers = mux.world.object(ctx.object):powers()
powers:add(mux.world.powers.IDLE)

mux.world.types

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

Provides immutable typed constants for native database object kinds.

Constants

Constant	Description
`mux.world.types.ROOM`	A room.
`mux.world.types.THING`	A thing.
`mux.world.types.EXIT`	An exit.
`mux.world.types.PLAYER`	A player.

Constants compare by native type identity within one Lua runtime. Their string forms are their canonical uppercase names. Unknown lookups and attempted mutation raise mux.arg.invalid.

Use these constants with create_object, list_objects, Object:type, and Object:contents rather than comparing or passing magic strings. PLAYER identifies existing players but is not accepted by create_object.

create_object

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

Creates a room, thing, or exit selected by a typed object-kind constant.

Function

mux.world.create_object({
 type = mux.world.types.THING,
 name = "Console",
 location = room,
 home = room,
 zone = equipment_zone,
})

Parameters

table options

An exact options table. Every object accepts these common fields:

Field	Type	Description
`type`	`ObjectType`	Required `ROOM`, `THING`, or `EXIT` constant from `mux.world.types`.
`name`	`string`	Required UTF-8 name. It may contain valid styled-text markup.
`zone`	number or `Object`	Optional live thing or room to assign as the object’s zone.

The remaining accepted fields depend on type:

destroy_object

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

Silently schedules a live object for destruction by the normal maintenance purge. The object remains accessible, with the same handle generation, until that purge runs.

Function

mux.world.destroy_object(object)
mux.world.destroy_object(object, { override = true })

The optional Boolean override field bypasses a target’s SAFE flag. It does not bypass protection for God, database object #0, configured start/default homes, or Wizard players. Rooms, things, exits, and non-Wizard players are supported. Repeated destruction requests are rejected.

list_objects

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

Returns database objects matching optional filters.

Function

Synopsis

mux.world.list_objects( options? )

Arguments

table or nil options: Optional filters. Omitting this argument, passing nil, or passing {} returns every valid, non-garbage database object.

Filter table keys and values

ObjectType[] options.types: Include only objects whose types appear in this array. Values must be typed constants from mux.world.types. An empty array matches nothing.
number or Object options.in_zone: Include only objects whose directly assigned zone is this object. The zone object itself is not implicitly included.

Returns

table objects: An array of matching Object handles in ascending dbref order.

Examples

local zone_things = mux.world.list_objects({
 types = { mux.world.types.THING },
 in_zone = zone,
})

Notes

Zone matching uses the object’s direct zone assignment and does not follow nested zone relationships. A zone being destroyed raises mux.object.unavailable. Objects scheduled for destruction may remain in the results until the native object purge runs; garbage dbrefs are excluded. This function scans the full database, so its cost grows with the database size. It is unavailable during @lua/check.

object

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

Creates a validated handle for a native database Object. Since this function raises errors, it’s best to wrap its invocation in a pcall() (see below).

Once you’ve retrieved an Object, its methods provide access to native metadata and handles for features such as State.

Function

Synopsis

mux.world.object( dbref )

Arguments

number or Object dbref: A live database reference or an existing object handle.

Returns

Object object: A handle for the referenced object.

Raises

Raises an error with code mux.object.invalid when passed an invalid dbref.

pemit

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

Privately emits a message to an object, matching the purpose and naming of the @pemit command. “Pemit” stands for “private emit.”

Function

Synopsis

mux.world.pemit( object, message )

Arguments

number or Object object: The recipient.
string message: Valid UTF-8 text without embedded NUL bytes.

Returns

Nothing.

Examples

mux.world.pemit(ctx.enactor, "The counter advances.")

Notes

The recipient must be a live object. Output styling is adapted to each recipient’s negotiated terminal color depth. This function is unavailable during @lua/check.

teleport_object

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

Teleports a thing or player to a destination using the native movement path. The operation updates both locations’ contents lists and emits the normal teleport and movement callbacks.

Function

mux.world.teleport_object({
 object = thing,
 destination = room,
})

The exact options table currently accepts these fields:

Field	Type	Description
`object`	dbref or `Object`	Required thing or player to teleport.
`destination`	dbref or `Object`	Required object capable of containing objects.

Unknown fields are rejected so additional options can be introduced later without expanding the function’s positional signature. The destination may not be the object itself or anything contained by it. Rooms and exits cannot be the moving object.