Object on StompyMUX Documentation

affiliation

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

Returns an object’s assigned affiliation.

local affiliation = object:affiliation()

The receiver is the live database object to inspect.

Returns

Object|nil affiliation: A handle for the assigned object, or nil when the object has no affiliation or its affiliate is being destroyed.

Affiliations are persistent object references only. They do not affect command matching, events, permissions, or other server behavior.

Errors and availability

Raises mux.object.invalid for an invalid receiver or an invalid affiliation stored on the object. This method is unavailable during @lua/check and raises mux.unavailable.checking there.

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

Returns objects directly contained by or attached to this object.

Function

Synopsis

object:contents( options? )

Arguments

table or nil options: Optional filters.

Filter table keys and values

With no argument, nil, or {} as the options table, the method returns all ordinary contents and attached exits.

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.visible_to: Include only objects visible to the provided viewer under native look rules.

Returns

table contents: An array of matching Object handles. Ordinary contents precede attached exits, with native database order preserved within each group.

Examples

local visible_exits = room:contents({
 types = { mux.world.types.EXIT },
 visible_to = ctx.enactor,
})

Notes

The receiver must be capable of holding contents or exits. This method is unavailable during @lua/check.

dbref

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

Returns this object’s native database reference.

Function

Synopsis

object:dbref( )

Arguments

None.

Returns

number dbref: The object’s native database reference.

Notes

The returned number identifies the object but cannot be used to change its identity. A stale Object raises mux.object.invalid.

description

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

Returns this object’s styled description, or nil when unset.

Function

object:description( )

Returns

string or nil description: The stored styled-text markup, or nil.

destination

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

Returns an exit’s destination.

Method

local destination = exit:destination()

The receiver must be an exit. The method returns an Object handle for a concrete destination, or nil when the exit is unlinked or its destination is being destroyed. An invalid stored destination raises mux.object.invalid.

This method also raises mux.object.invalid when called on a room, thing, or player, and mux.unavailable.checking during @lua/check.

Example

local destination = exit:destination()
if destination then
 mux.log("lua", "Exit leads to " .. tostring(destination))
end

flags

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

Creates a typed flag collection for this object.

Synopsis

local flags = object:flags()

Returns a Flags handle. The object must be live, and the method is unavailable during @lua/check.

home

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

Returns a thing or player’s assigned home.

Method

local home = object:home()

The receiver must be a thing or player. The method returns an Object handle for its home, or nil when no home is assigned or the home is being destroyed.

It raises mux.object.invalid for other receiver types or an invalid stored home, and mux.unavailable.checking during @lua/check.

Example

local home = object:home()
if home then
 mux.log("lua", tostring(object) .. " is homed to " .. tostring(home))
end

internal_description

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

Returns this object’s styled internal description, or nil when unset.

Function

object:internal_description( )

Returns

string or nil description: The stored styled-text markup, or nil.

location

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

Returns a thing or player’s current location.

Method

local location = object:location()

The receiver must be a thing or player. The method returns an Object handle for its location, or nil when it has no location or the location is being destroyed. Use Object:destination for an exit; room droptos are not exposed by this method.

It raises mux.object.invalid for other receiver types or an invalid stored location, and mux.unavailable.checking during @lua/check.

Example

local location = object:location()
if location then
 mux.log("lua", tostring(object) .. " is in " .. tostring(location))
end

lua_parent

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

Returns an object’s directly assigned Lua parent path.

local parent = object:lua_parent()

The receiver is the live database object to inspect.

Returns

string|nil parent: The path relative to game/lua/object_logic, or nil when the object has no Lua parent. The returned path does not include the object_logic/ prefix.

This reports only the object’s direct assignment. Object-logic modules are not inherited through zones, locations, or other objects.

Errors and availability

Raises mux.object.invalid for an invalid receiver. This method is unavailable during @lua/check and raises mux.unavailable.checking there.

name

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

Returns this object’s current stored name.

Function

Synopsis

object:name( )

Arguments

None.

Returns

string name: The object’s current name, including any stored styled-text markup.

Examples

local object = mux.world.object(ctx.object)
mux.world.pemit(ctx.enactor, object:name())

powers

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

Creates a typed power collection for this object.

Synopsis

local powers = object:powers()

Returns a Powers handle. The object must be live, and the method is unavailable during @lua/check.

set_affiliation

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

Assigns an object’s affiliation or clears its affiliation assignment.

object:set_affiliation(affiliation)
object:set_affiliation(nil)

Parameters

number|Object|nil affiliation: Any live room, thing, exit, or player to assign. Pass nil to clear the current assignment. An object may be affiliated with itself.

The receiver is the live database object to update. The affiliation argument is required even when clearing an assignment. These are trusted world mutations: the method does not perform player-control checks. Affiliations are persistent object references only and do not affect command matching, events, permissions, or other server behavior.

set_description

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

Sets or clears this object’s styled description.

Function

object:set_description(description)
object:set_description(nil)

Arguments

string or nil description: Valid styled-text markup. nil or an empty string clears the description.

Errors

mux.unavailable.checking during @lua/check.
mux.arg.invalid for invalid text or markup.
mux.object.invalid if the handle is stale.
mux.object.unavailable if the object is being destroyed.

set_destination

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

Sets an attached exit’s destination or clears its destination without changing the exit’s source.

Method

exit:set_destination(destination)
exit:set_destination(nil)

The receiver must be a live exit. Calling this method on any other object type raises mux.object.invalid. A non-nil destination may be a dbref or Object handle for a live object capable of containing objects. Pass nil explicitly to clear the destination; an omitted destination is rejected.

This is a trusted world mutation and does not perform the permission or lock checks used by @link. Setting or clearing only changes the exit’s destination. The exit remains attached to its existing source.

set_home

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

Sets a thing or player’s home.

Method

object:set_home(new_home)

The receiver must be a live thing or player. new_home is a dbref or Object handle for a live room, thing, or player capable of containing objects. The receiver cannot be its own home.

This trusted world mutation validates the same object relationships used when assigning a home with @link, but it does not perform ownership or SET_HOME lock checks. The method returns no values.

set_internal_description

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

Sets or clears this object’s styled internal description.

Function

object:set_internal_description(description)
object:set_internal_description(nil)

Arguments

string or nil description: Valid styled-text markup. nil or an empty string clears the description.

Errors

mux.unavailable.checking during @lua/check.
mux.arg.invalid for invalid text or markup.
mux.object.invalid if the handle is stale.
mux.object.unavailable if the object is being destroyed.

set_lua_parent

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

Assigns an object’s direct Lua parent or clears the assignment.

object:set_lua_parent("events/enter_notice.lua")
object:set_lua_parent(nil)

Parameters

string|nil parent: An existing .lua file relative to game/lua/object_logic, or nil to clear the current assignment. Do not include an object_logic/, global_logic/, or packages/ prefix.

The receiver is the live database object to update. The parent argument is required even when clearing an assignment. The path is resolved with the same validation as @lua/parent: it must remain inside the object-logic root and the file must exist. This trusted world mutation does not perform the command’s player-control checks.

set_name

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

Changes this object’s name using the native object-name rules. Player names must also be available, allowed by the bad-name list, and valid player names.

Function

Synopsis

object:set_name( name )

Arguments

string name: The new UTF-8 name. It may contain valid styled-text markup.

Returns

No values.

Examples

local object = mux.world.object(ctx.object)
object:set_name("New Name")

Errors

mux.unavailable.checking during @lua/check.
mux.arg.invalid if the name is missing, malformed, invalid for the object type, forbidden, or already used by another player.
mux.object.invalid if the Object handle is stale.
mux.object.unavailable if the object is being destroyed.

set_zone

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

Assigns an object’s zone or clears its zone assignment.

object:set_zone(zone)
object:set_zone(nil)

Parameters

number|Object|nil zone: A live thing or room to assign as the zone. Pass nil to clear the current assignment. When the zone is a room, the object being updated must also be a room.

The receiver is the live database object to update. The zone argument is required even when clearing an assignment. These are trusted world mutations: unlike @chzone, the method does not perform player-control checks.

state

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

Creates a persistent-state handle for one namespace on this object.

Function

Synopsis

object:state( namespace )

Arguments

string namespace: A valid, exact, case-sensitive state namespace.

Returns

State state: A handle for the namespace.

Examples

local state = mux.world.object(ctx.object):state("counter")
local count = state:get("count", 0) + 1
state:set("count", count)

Notes

The namespace must begin with an ASCII letter and may contain letters, digits, _, -, ., and /. This method is unavailable during @lua/check.

type

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

Returns this object’s native object type.

Function

Synopsis

object:type( )

Arguments

None.

Returns

ObjectType or nil type: The corresponding typed constant from mux.world.types, or nil for an unrecognized native type.

Examples

if object:type() == mux.world.types.PLAYER then
 mux.world.pemit(object, "You are a player.")
end

Notes

The returned value cannot be used to change the object’s type. A stale Object raises mux.object.invalid.

zone

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

Returns an object’s assigned zone.

local zone = object:zone()

The receiver is the live database object to inspect.

Returns

Object|nil zone: A handle for the assigned zone, or nil when the object has no zone or its zone is being destroyed.

Errors and availability

Raises mux.object.invalid for an invalid receiver or an invalid zone stored on the object. This method is unavailable during @lua/check and raises mux.unavailable.checking there.

Object on StompyMUX Documentation

affiliation

Returns

Errors and availability

contents

Function

Synopsis

Arguments

Filter table keys and values

Returns

Examples

Notes

dbref

Function

Synopsis

Arguments

Returns

Notes

See Also

description

Function

Returns

See Also

destination

Method

Example

flags

Synopsis

See Also

home

Method

Example

internal_description

Function

Returns

See Also

location

Method

Example

lua_parent

Returns

Errors and availability

name

Function

Synopsis

Arguments

Returns

Examples

See Also

powers

Synopsis

See Also

set_affiliation

Parameters

set_description

Function

Arguments

Errors

See Also

set_destination

Method

set_home

Method

set_internal_description

Function

Arguments

Errors

See Also

set_lua_parent

Parameters

set_name

Function

Synopsis

Arguments

Returns

Examples

Errors

See Also

set_zone

Parameters