| Message
| These are the functions provided to Lua scripters by the lua_scripting module. There are all in the "mud" table. They are listed in alphabetic order.
Some of these have changed since the initial posting of this topic. In particular minvoke has been reworked somewhat.
Character userdata
In order to uniquely identify mobs in rooms, where multiple mobs might have the same vnum, various functions return or accept a "character userdatum". This is a Lua light userdata item, which stores the internal pointer of that player or mob. Because it is very possible for the character userdatum to become out of date, for example because players disconnect, and mobs are killed, it should only be used immediately after being returned from a function call. That is, userdata should not be stored for later use.
The current player has its userdatum stored as the variable "mud.self". This lets you check, when iterating through a room's contents, for example, if you have come across the current player. The userdatum "mud.self" will always be valid (unless you assign something else to it), as the current player is always present.
Added in version 2 of the Lua interface
char_or_mob
Where the argument "char_or_mob" is used the following algorithm is used to locate the target character:
- If omitted, the current character (player). eg.
if mud.fighting () then --- is the current character fighting?
- If the argument is a userdatum, it is checked to be a valid "character.metadata" userdatum, and the current room is searched for a player or mob matching that userdatum. If the player or mob is not found, and the second argument is true, then the entire MUD is searched for a player or mob matching that userdatum. These searches are done to confirm that the userdatum is still valid (that is, it is not out of date). If the second argument is a number, it is assumed to be a room vnum, and the userdatum is searched to be valid in that room only.
eg.
if mud.fighting (mud.self) then --- is the current character fighting?
- If the argument is a number, it is assumed to be a mob vnum, and the current room is searched for the first instance of a mob (NPC) with that vnum. If the mob is not found, and the second argument is true, then the entire MUD is searched for a mob of that vnum. If the second argument is a number, it is assumed to be a room vnum, and the mob is searched for in that room only.
eg.
if mud.fighting (23000) then --- is mob 23000 in this room, and fighting?
if mud.fighting (23000, true) then --- is mob 23000 in the MUD somewhere, and fighting?
if mud.fighting (23000, 13000) then --- is mob 23000 in room 13000, and fighting?
- If the argument is a string, it is assumed to be a player, and the current room is searched for the player of that name (case insensitive). If the player is not found, then the entire MUD is searched for that player. The word "self" can be used to refer to the current player.
eg.
if mud.fighting ("self") then --- is the current character fighting?
if mud.fighting ("Kedaeder") then --- is Kedaeder in the MUD somewhere, and fighting?
Many functions will simply return nothing (effectively, nil) if the mob or player cannot be found. A few (where noted) will raise an error.
- mud.area_info (area_name)
Returns table of information about the area with filename "area_name", or nil if that area does not exist.
- mud.area_list ()
Returns a table of all the areas in the game.
- mud.carryingvnum (vnum)
Returns true if the current character is carrying (not wearing) an item of that vnum.
- mud.char_exists (char_or_mob)
Returns true if the target player or mob exists.
- mud.char_name (char_or_mob)
Returns the name of the target player or mob.
- mud.character_info (char_or_mob)
Returns a table of information about the target player or mob, such as name, description, level, hit points, mana, and so on.
For player characters (that is, not mobs) also returns a "pc" subtable with further information in it.
- mud.class (char_or_mob)
Returns the class of the target player or mob.
- mud.destroy_item (vnum, count)
Destroys 'count' instances of the item 'vnum' in the current player's top-level inventory (that is, not in bags).
Returns the number destroyed.
- mud.equipped (char_or_mob)
Returns a table of all equipped items for the target player or mob. Equipped items are worn (not in inventory).
- mud.fighting (char_or_mob)
Returns true if the target player or mob is currently fighting.
- mud.force (char_or_mob, command)
Forces the target player or mob to perform 'command'. If the mob is specified in the form (vnum, true) then the command is the 3rd argument.
Raises an error if the target cannot be found.
eg.
mud.force ("self", "sigh") -- make ourselves sigh
mud.force (23000, "slap " .. mud.char_name ()) -- mob 23000 slaps us
- mud.gain_exp (n)
Adds 'n' experience to the current character.
- mud.gain_gold (n)
Adds 'n' gold to the current character.
- mud.immortal (char_or_mob)
Returns true if the target player or mob is an immortal).
- mud.interpret (command)
Makes the current character interpret command 'command'.
eg.
mud.interpret ("dance") -- make ourselves dance
- mud.inventory (char_or_mob)
Returns a table of all of the inventory items for the target player or mob.
The inventory is recursively processed, so that if the player has bags then the contents of the bags are also in a sub-table.
The six "value" fields are stored in a 1-relative array "value". (ie. value [1], value [2] and so on).
If the item has contents (eg. a bag) then its contents are in a table called "contents".
eg.
1:
"description"="A plate of armour from the Academy lies here"
"cost"=0
"wear_flags"=9
"item_type"=9
"value":
1=2
2=2
3=0
4=0
5=0
6=0
"level"=1
"wear_loc"=-1
"vnum"=10308
"short_descr"="a plate of armour"
"weight"=5
"room_vnum"=0
"name"="plate armour academy"
"magic_flags"=0
"timer"=0
"action_desc"=""
"serial"=1344
"count"=1
2:
"description"="A piece of wood, partly wrapped in cloth is here."
"cost"=20
"wear_flags"=65537
"item_type"=1
"value":
1=0
2=0
3=24
4=0
5=0
6=0
"level"=0
"wear_loc"=-1
"vnum"=10316
"short_descr"="a torch"
"weight"=1
"room_vnum"=0
"name"="torch"
"magic_flags"=0
"timer"=0
"action_desc"=""
"serial"=1345
"count"=1
- mud.level (char_or_mob)
Returns the level of the target player or mob.
- mud.make_trap (room, v0, v1, v2, v3)
A trap is added to the room, if it doesn't already exist, with values v0, v1, v2, v3.
- mud.minvoke (vnum, room, equipment, inventory)
Invokes an instance of the mob vnum, and places it in the nominated room.
The third argument is a table of items the mob is to wear, keyed by location, eg.
{ feet = 10301, wrist1 = 10300 }
Valid locations are:
"light", "finger1", "finger2", "neck1", "neck2", "body", "head", "legs",
"feet", "hands", "arms", "shield", "about", "waist", "wrist1", "wrist2",
"wield", "hold", "dual_wield", "ears", "eyes", "missile_wield", "back",
"face", "ankle1", "ankle2"
The fourth argument is a table of items the mob is to have in its inventory. eg.
Inventory items can be containers. Containers are indicated by a table rather than a number. The table is a list of the container contents, plus a field keyed by the key "bag" which is the vnum of the container. Containers may be nested. For example:
{ bag = 10325, 2109, 24803 } -- bag 10325 contains 2109 and 24803
{ bag = 25, 7211, { bag = 10325, 2109, 24803 } } -- bag vnum 25 contains 7211
-- also contains bag 10325 which itself contains 2109 and 24803
Raises an error if the mob, or any of the objects, cannot be found.
eg.
mud.minvoke (10323, 10350, { wrist1 = 10300, feet = 10301 }, { 10317, 21021 } )
-- put mob 10323 in room 10350, equipped with 10300 and 10301, and with
-- 10317 and 21021 in its inventory
mud.minvoke (10323, -- mob vnum
10350, -- room vnum
{ wrist1 = 10300, feet = 10301 }, -- equipped items
--- inventory ---
{ { bag = 25, 1510, 7211 }, -- bag vnum 25, contains 1510 and 7211
{ bag = 10325, 2109, 24803 }, -- bag vnum 10325,
-- contains 2109 and 24803
24844, -- A hot apple pie (not in a bag)
24860, -- A big red apple (not in a bag)
} -- end of equipment
)
Returns the userdata of the invoked mob.
- mud.mob_info (vnum)
Returns a table of information about the nominated mob.
- mud.mob_name (vnum)
Returns the short and long description of the nominated mob (two results).
- mud.mobinarea (vnum, room)
If a mob of the specified vnum is in the character's area, returns a count of how many of them there are. Otherwise it returns false.
- mud.mobinroom (vnum, room)
If a mob of the specified vnum is in the character's current room, returns a count of how many of them there are. Otherwise it returns false.
- mud.mobinworld (vnum)
If a mob of the specified vnum is in the world, returns a count of how many of them there are. Otherwise it returns false.
- mud.mobs_in_room (vnum)
Returns two tables (numerically keyed) of all of the mobs in the current room (if no vnum specified), or the room with the specified vnum. The first table is the vnums of the mobs, the second table is the userdata of the mobs.
eg.
t1, t2 = mud.mobs_in_room (23000)
-- t1 =
1=21037
2=10303
3=10300
-- t2 =
1=mud_character (userdatum)
2=mud_character (userdatum)
3=mud_character (userdatum)
- mud.msg_area (room_vnum, message, colour_type)
Sends "message" to every PC in the same area as the room with the specified vnum. The message is prepended by the nominated colour sequence (default: at.plain), and appended by a carriage-return/newline.
The argument colour_type must be a number in the range 0 to 110. This can be looked up in the 'at' table (eg. at.reset, at.green, at.gossip).
- mud.msg_char (name, message, colour_type)
Sends "message" to the character named "name" (not an NPC). The message is prepended by the nominated colour sequence (default: at.plain), and appended by a carriage-return/newline.
Intended to be called from area resets, it is more efficient to use send_to_char within character-related scripts (eg. task system).
The argument colour_type must be a number in the range 0 to 110. This can be looked up in the 'at' table (eg. at.reset, at.green, at.gossip).
- mud.msg_game (message, colour_type)
Sends "message" to every PC in the game. The message is prepended by the nominated colour sequence (default: at.plain), and appended by a carriage-return/newline.
The argument colour_type must be a number in the range 0 to 110. This can be looked up in the 'at' table (eg. at.reset, at.green, at.gossip).
- mud.msg_room (room_vnum, message, colour_type)
Sends "message" to every PC in the room with the specified vnum. The message is prepended by the nominated colour sequence (default: at.plain), and appended by a carriage-return/newline.
The argument colour_type must be a number in the range 0 to 110. This can be looked up in the 'at' table (eg. at.reset, at.green, at.gossip).
- mud.npc (char_or_mob)
Returns true if the target player or mob is an NPC (ie. a mob).
- mud.objinroom (item, room)
If an object of the specified vnum is in the character's current room, returns a count of how many of them there are. Otherwise it returns false.
- mud.obj_to_room (room_vnum, item)
Invokes an instance of object and places it into the room. The item can be specified as a table which will create a container (like minvoke).
eg.
mud.obj_to_room (10350, 21022) -- put a cherry pie in room 10350
mud.obj_to_room (10350, { bag = 25, 1510, 7211 }) -- put bag in room 10350
-- bag contains items 1510 and 7211
- mud.object_info (vnum)
Returns a table of information about the nominated object.
- mud.object_name (vnum)
Returns the short and long description of the nominated object (two results).
- mud.oinvoke (vnum, level)
Invokes an instance of the nominated object with level 'level' and places it in the player's inventory (if possible), otherwise on the ground in the current room.
Raises an error if the object does not exist, or the level is out of range. If the level is not specified a level 1 object is invoked.
- mud.players_in_game ()
Returns two tables (numerically keyed) of all of the players in the game. The first table is the names of the players, the second table is the userdata of the players.
- mud.players_in_room (vnum)
Returns two tables (numerically keyed) of all of the players in the current room (if no vnum specified), or the room with the specified vnum. The first table is the names of the players, the second table is the userdata of the players.
eg.
t1, t2 = mud.players_in_room (23000)
-- t1 =
1=Nick
2=David
3=Jennifer
-- t2 =
1=mud_character (userdatum)
2=mud_character (userdatum)
3=mud_character (userdatum)
- mud.position (char_or_mob)
Returns two results, representing the target player or mob's current position. The first one is a string representation, the second is the underlying number.
eg.
a, b = mud.position () --> standing, 12
- mud.possessvnum (vnum, inbags)
Returns a count of the number of items of 'vnum' that the current character has in their inventory. If 'inbags' is true, the function recurses to search bags (and bags inside bags and so on). Otherwise, it is a count of the items in their top-level inventory.
- mud.purgeobj (object_vnum, room_vnum, count)
Removes the one or more objects from the room. This is intended to be used in rooms without players in them, as there are no messages. The intention is that a reset program might clean up a room by removing objects that are no longer required, possibly replacing them by something else.
- mud.purgemob (char_or_mob)
Removes the target mob from the room. Can only be used on NPCs. This is intended to be used in rooms without players in them, as there are no messages. The intention is that a reset program might remove one mob and replace it with a different one, or clean up excess mobs that are no longer required.
- mud.race (char_or_mob)
Returns a string which is the target player or mob's race. (eg. "Dwarf")
- mud.randomize_exits (room, directions)
Exits for the room are randomized, up to a maximum of 'directions' directions.
- mud.room (char_or_mob)
Returns the vnum of the room which the target player or mob is in.
- mud.room_exits (vnum, except)
Returns a table of the exits from the nominated room.
The key of the table item is the direction, the value is the room vnum.
If the 'except' argument is present, exits which match that bit flag are excluded. (To exclude locked exits, 'except' would be 4).
eg.
"ne"=21200
"s"=21042
"nw"=21163
"e"=21036
"u"=21337
"w"=21039
"n"=21001
- mud.room_info (vnum)
Returns a table of information about the nominated room, or if the vnum is omitted, the current room.
Any exits are listed in a sub-table "exits". Exits are keyed by direction name (eg. n, s, nw).
Any contents of the room are listed in a sub-table "contents".
- mud.room_name (vnum)
Returns the name and description of the nominated room (two results), or if the vnum is omitted, the current room.
- mud.send_to_char (message)
Sends 'message' to the current player.
- mud.set_char_color (colour_number)
Sends the appropriate colour sequence to the character for the colour type.
Colour number must be a number in the range 0 to 110. This can be looked up in the 'at' table (eg. at.reset, at.green, at.gossip).
- mud.set_exit_state (room, exit, state_flags)
Sets the state of an exit in a room.
Exit must be a string (n, s, e, w, ne etc.).
State is a string. The exits is initially not closed, locked nor secret.
If the flags strings contains "C" the exit is then closed.
If the flags strings contains "L" the exit is then locked.
If the flags strings contains "S" the exit is then secret.
- mud.stop_fighting (char_or_mob)
Forces the target player or mob to stop fighting.
- mud.sysdata ()
Returns a table of information about the current MUD from the system file (sysdata). This includes things like the MUD name, and various flags and modifiers.
- mud.system_info ()
Returns a table of information about the current MUD which are the static "compiled-in" options. This includes things like the player directory, area directory, seconds per tick, maximum level, and so on.
- mud.transfer (char_or_mob, room)
Transfers the target player or mob to the nominated room.
- mud.wearing (loc)
Returns the vnum of the item that the player is wearing on the nominated location, or false if nothing.
Valid locations are:
"light", "finger1", "finger2", "neck1", "neck2", "body", "head", "legs",
"feet", "hands", "arms", "shield", "about", "waist", "wrist1", "wrist2",
"wield", "hold", "dual_wield", "ears", "eyes", "missile_wield", "back",
"face", "ankle1", "ankle2"
- mud.wearingvnum (vnum)
Returns true if the player is wearing an item of the specified vnum somewhere on their body, otherwise false.
The following functions are not in the C interface (and thus do not have "mud." in front of them). They are provided in the startup.lua file as helper functions.
- capitalize (s)
Capitalizes the supplied string.
eg.
capitalize ("nick") --> Nick
- convert_time (secs)
Converts the time in seconds to the nearest major interval, rounded. eg.
convert_time (5) --> 5s
convert_time (61) --> 1m
convert_time (3600) --> 1h
- convert_time_long (secs)
Converts the time in seconds to the nearest major interval, rounded, in "long" form. eg.
convert_time_long (5) --> 5 seconds
convert_time_long (61) --> 1 minute
convert_time_long (3600) --> 1 hour
- fix_description (s, a1, a2, a3, ...)
Takes string s and substitutes various things in it:
- $n --> character name
- $c --> character class
- $r --> character race
- $$ --> the '$' symbol
- $1 --> argument a1
- $2 --> argument a2
- ... and so on up to argument a9
eg.
fix_description ("Thanks $n, you are a good $c. I give you a $1.", "banana")
--> "Thanks Nick, you are a good elf. I give you a banana."
- fsend (format, a1, a2, a3, ...)
Formatted "send". Formats the message 'format' with a1, a2, etc., using string.format, and then sends it to the character using mud.send_to_char, appending a newline.
- heading (title, colour)
Displays a "heading" with "title" centered in a batch of 78 hyphens, and prefixed by the "colour" sequence (eg. &Y). If colour is omitted, "&Y" is used.
- hyphens ()
Displays a line of 79 hyphens to the player.
- round (n)
Returns 'n' rounded to the nearest whole number.
- send (s1, s2, s3, ...)
Sends its arguments to the player, concatenated together and terminated by carriage-return/newline.
- send_nocr (s1, s2, s3, ...)
Sends its arguments to the player, concatenated together with NO carriage-return/newline.
- task_xp (n)
Calls mud.gain_exp to award 'n' experience points to the player, and notifies them that it has done so.
- task_item (vnum, level)
Calls mud.oinvoke to create an item of 'vnum' and 'level' and notifies the player that it has done so.
- task_gold (n)
Calls mud.gain_gold to award 'n' gold to the player, and notifies them that it has done so.
- trim (s)
Returns the string 's', trimmed of leading and trailing spaces.
|
- Nick Gammon
www.gammon.com.au, www.mushclient.com | | Top |
|
![[Go to top]](/images/gototop.gif){kind=small}
top