Difference between revisions of "Manual:Lua Functions"
Line 1,172: | Line 1,172: | ||
<lua> | <lua> | ||
echo(string.format("room id #455 is in %s.", getRoomAreaName(getRoomArea(455)))) | echo(string.format("room id #455 is in %s.", getRoomAreaName(getRoomArea(455)))) | ||
+ | </lua> | ||
+ | |||
+ | ==deleteArea== | ||
+ | deleteArea(areaID) | ||
+ | |||
+ | Deletes the given area, permanently. This will also delete all rooms in it! | ||
+ | |||
+ | <lua> | ||
+ | deleteArea(23) | ||
</lua> | </lua> | ||
Revision as of 02:20, 28 June 2011
Function Categories
UI Functions: These functions are used to construct custom user GUIs. They deal mainly with miniconsole/label/gauge creation and manipulation. <lua>
createMiniConsole() createLabel() createGauge()
</lua>
Table Functions: These functions are used to manipulate tables. Through them you can add to tables, remove values, check if a value is present in the table, check the size of a table, and more.
String Functions
Scripting Object Functions
Mapper Functions
Miscellaneous Functions
UI Functions
- These functions are used to create, resize, print to, or otherwise manipulate UI elements such as Labels, MiniConsoles, Gauges, et al
appendBuffer
- appendBuffer(name)
- Pastes the previously copied rich text (including text formats like color etc.) into user window name.
- See also: paste
- Parameters
- name:
- The name of the user window to paste into. Passed as a string.
- Examples
<lua> --selects and copies an entire line to user window named "Chat" selectCurrentLine() copy() appendBuffer("Chat") </lua>
bg
- bg(colorName)
- Changes the background color of the text. Useful for highlighting text.
- See Also: fg, setBgColor
- Parameters
- colorName:
- Example
<lua> --This would change the background color of the text on the current line to magenta selectCurrentLine() bg("magenta") </lua>
calcFontSize
- calcFontSize(fontSize)
- Used to calculate the number of pixels wide and high a character would be on a mini console at fontSize.
- Returns two numbers, width/height
- See Also: setMiniConsoleFontSize, getMainWindowSize
- Parameters
- fontSize:
- The font size you are wanting to calculate pixel sizes for. Passed as an integer number.
- Example
<lua> --this snippet will calculate how wide and tall a miniconsole designed to hold 4 lines of text 20 characters wide --would need to be at 9 point font, and then changes miniconsole Chat to be that size local width,height = calcFontSize(9) width = width * 20 height = height * 4 resizeWindow("Chat", width, height) </lua>
clearUserWindow
- clearUserWindow(name)
- Clears the window or miniconsole with the name given as argument.
- Parameters
- name:
- The name of the user window to clear. Passed as a string.
Examples <lua> --This would clear a label, user window, or miniconsole with the name "Chat" clearUserWindow("Chat") </lua>
clearWindow
- clearWindow(name)
- Clears the window or miniconsole with the name given as argument.
- See also: clearUserWindow
- Parameters
- name:
- The name of the user window to clear. Passed as a string.
Examples <lua> --This would clear a label, user window, or miniconsole with the name "Chat" clearWindow("Chat") </lua>
createBuffer
- createBuffer(name)
- Creates a named buffer for formatted text, much like a miniconsole, but the buffer cannot be shown on the screen. Intended for temporary use in the formatting of text.
- Parameters
- name:
- The name of the buffer to create.
Examples <lua> --This creates a named buffer called "scratchpad" createBuffer("scratchpad") </lua>
createConsole
- createConsole(consoleName, fontSize, charsPerLine, numberOfLines, Xpos, Ypos)
- Makes a new miniconsole. The background will be black, and the text color white.
- Parameters
- consoleName:
- The name of your new miniconsole. Passed as a string.
- fontSize:
- The font size to use for the miniconsole. Passed as an integer number.
- charsPerLine:
- How many characters wide to make the miniconsole. Passed as an integer number.
- numberOfLines:
- How many lines high to make the miniconsole. Passed as an integer number.
- Xpos:
- X position of miniconsole. Measured in pixels, with 0 being the very left. Passed as an integer number.
- Ypos:
- Y position of miniconsole. Measured in pixels, with 0 being the very top. Passed as an integer number.
Examples <lua> -- this will create a console with the name of "myConsoleWindow", font size 8, 80 characters wide, -- 20 lines high, at coordinates 300x,400y createConsole("myConsoleWindow", 8, 80, 20, 200, 400) </lua>
createGauge
- createGauge(name, width, Xpos, Ypos, gaugeText, r, g, b)
- createGauge(name, width, Xpos, Ypos, gaugeText, colorName)
- Creates a gauge that you can use to express completion with. For example, you can use this as your healthbar or xpbar.
- See also: moveGauge, setGauge, setGaugeText
- Parameters
- name:
- The name of the gauge. Must be unique, you can not have two or more gauges with the same name. Passed as a string.
- width:
- The width of the gauge, in pixels. Passed as an integer number.
- height:
- The height of the gauge, in pixels. Passed as an integer number.
- Xpos:
- X position of gauge. Measured in pixels, with 0 being the very left. Passed as an integer number.
- Ypos:
- Y position of gauge. Measured in pixels, with 0 being the very top. Passed as an integer number.
- gaugeText:
- Text to display on the gauge. Passed as a string, unless you do not wish to have any text, in which case you pass nil
- r:
- The red component of the gauge color. Passed as an integer number from 0 to 255
- g:
- The green component of the gauge color. Passed as an integer number from 0 to 255
- b:
- The blue component of the gauge color. Passed as an integer number from 0 to 255
- colorName:
- the name of color for the gauge. Passed as a string.
Examples <lua> -- This would make a gauge at that's 300px width, 20px in height, located at Xpos and Ypos and is green. -- The second example is using the same names you'd use for something like fg() or bg(). createGauge("healthBar", 300, 20, 30, 300, nil, 0, 255, 0) createGauge("healthBar", 300, 20, 30, 300, nil, "green")
-- If you wish to have some text on your label, you'll change the nil part and make it look like this:
createGauge("healthBar", 300, 20, 30, 300, "Now with some text", 0, 255, 0)
-- or
createGauge("healthBar", 300, 20, 30, 300, "Now with some text", "green")
</lua>
createLabel
- createLabel(name, Xpos, Ypos, width, height, fillBackground)
- Creates a highly manipulable overlay which can take some css and html code for text formatting. Labels are clickable, and as such can be used as a sort of button. Labels are meant for small variable or prompt displays, messages, images, and the like. You should not use them for larger text displays or things which will be updated rapidly and in high volume, as they are much slower than miniconsoles.
- Returns true or false.
- See also: hideWindow, showWindow, resizeWindow, setLabelClickCallback, setTextFormat, setTextFormat, setMiniConsoleFontSize, setBackgroundColor, getMainWindowSize, calcFontSize
- Parameters
- name:
- The name of the label. Must be unique, you can not have two or more labels with the same name. Passed as a string.
- Xpos:
- X position of the label. Measured in pixels, with 0 being the very left. Passed as an integer number.
- Ypos:
- Y position of the label. Measured in pixels, with 0 being the very top. Passed as an integer number.
- width:
- The width of the label, in pixels. Passed as an integer number.
- height:
- The height of the label, in pixels. Passed as an integer number.
- fillBackground:
- Whether or not to display the background. Passed as either 1 or 0. 1 will display the background color, 0 will not.
Examples <lua> --This example creates a transparent overlay message box to show a big warning message "You are under attack!" in the middle --of the screen. Because the background color has a transparency level of 150 (0-255, with 0 being completely transparent --and 255 non-transparent) the background text can still be read through. The message box will disappear after 2.3 seconds. local width, height = getMainWindowSize(); createLabel("messageBox",(width/2)-300,(height/2)-100,250,150,1); resizeWindow("messageBox",500,70); moveWindow("messageBox", (width/2)-300,(height/2)-100 ); setBackgroundColor("messageBox", 150,100,100,200);
echo("messageBox", [[
]] );
showWindow("messageBox"); tempTimer(2.3, hideWindow("messageBox") ) -- close the warning message box after 2.3 seconds </lua>
createMiniConsole
- createMiniConsole(name, posX, posY, width, height)
- Opens a miniconsole window inside the main window of Mudlet. This is the ideal fast colored text display for everything that requires a bit more text, such as status screens, chat windows, etc.
- Returns true or false.
- See also: createLabel, hideWindow, showWindow, resizeWindow, setTextFormat, moveWindow, setMiniConsoleFontSize, handleWindowResizeEvent, setBorderTop, setWindowWrap, getMainWindowSize, calcFontSize
- Parameters
- name:
- The name of the miniconsole. Must be unique, you can not have two or more miniconsoles with the same name. Passed as a string.
- Xpos:
- X position of the miniconsole. Measured in pixels, with 0 being the very left. Passed as an integer number.
- Ypos:
- Y position of the miniconsole. Measured in pixels, with 0 being the very top. Passed as an integer number.
- width:
- The width of the miniconsole, in pixels. Passed as an integer number.
- height:
- The height of the miniconsole, in pixels. Passed as an integer number.
Examples <lua> --This script would create a mini text console called "sys" and write with yellow foreground color and blue background color --"Hello World".
-- set up the small system message window in the top right corner
-- determine the size of your screen
WindowWidth = 0;
WindowHeight = 0;
WindowWidth, WindowHeight = getMainWindowSize();
createMiniConsole("sys",WindowWidth-650,0,650,300) setBackgroundColor("sys",85,55,0,255) setMiniConsoleFontSize("sys", 8) -- wrap lines in window "sys" at 40 characters per line setWindowWrap("sys", 40) -- set default font colors and font style for window "sys" setTextFormat("sys",0,35,255,50,50,50,0,0,0)
echo("sys","Hello world!") </lua>
deleteLine
- deleteLine()
- Deletes the current line under the user cursor. This is a high speed gagging tool and is very good at this task, but is only meant to be use when a line should be omitted entirely in the output. If you echo() to that line it will not be shown, and lines deleted with deleteLine() are simply no longer rendered. For replacing text, replace() is the proper option.
- See Also: replace, wrapLine
- No Parameters
- Example
<lua> --This example creates a temporary line trigger to test if the next line is a prompt, and if so gags it entirely. --This can be useful for keeping a pile of prompts from forming if you're gagging chat channels in the main window --Note: isPrompt() only works on servers which send a GA signal with their prompt. tempLineTrigger(1, 1, if isPrompt() then deleteLine() end) </lua>
deselect
- deselect(name)
- This is used to clear the current selection (to no longer have anything selected). Should be used after changing the formatting of text, to keep from accidentally changing the text again later with another formatting call.
- Parameters
- name:
- The name of the buffer/miniConsole to stop having anything selected in. This is an optional argument, if name is not provided the main window will have its selection cleared. Passed as a string.
- Example
<lua> --This will change the background on an entire line in the main window to red, and then properly clear the selection to keep further --changes from effecting this line as well. selectCurrentLine() bg("red") deselect() </lua>
fg
- fg(colorName)
- If used on a selection, sets the foreground color to colorName - otherwise, it will set the color of the next text-inserting calls (echo(), insertText, echoLink(), and others)
- See Also: bg, setBgColor
- Parameters
- colorName:
- Examples
<lua> --This would change the color of the text on the current line to green selectCurrentLine() fg("green") resetFormat()
--This will echo red, green, blue in their respective colors fg("red") echo("red ") fg("green") echo("green ") fg("blue") echo("blue ") resetFormat() </lua>
getMainWindowSize
- getMainWindowSize()
- Returns two numbers, the width and height in pixels.
- No Parameters
- Example
<lua> --this will get the size of your main mudlet window and save them --into the variables mainHeight and mainWidth mainWidth, mainHeight = getMainWindowSize() </lua>
resetFormat
- resetFormat()
- Resets the colour/bold/italics formatting. Always use this function when done adjusting formatting, so make sure what you've set doesn't 'bleed' onto other triggers/aliases.
- Example
<lua> -- select and set the 'Tommy' to red in the line selectString("Tommy", 1) fg("red")
-- now reset the formatting, so our echo isn't red resetFormat() echo(" Hi Tommy!")
-- another example: just highlighting some words for _, word in ipairs{"he", "she", "her", "their"} do
if selectString(word, 1) ~= -1 then bg("blue") end
end resetFormat() </lua>
setAppStyleSheet
- setAppStyleSheet(stylesheet)
- Allows you to set the Qt stylesheet for Mudlet itself, customizing how it looks on your platform. See the stylesheet syntax on how to use it, along with the stylesheet reference to see what CSS elements can be used on which Qt widgets. You may also might want to take a peek at stylesheet examples.
- Example
This is not a perfect example. It will change the settings windows, and triggers/aliases/scripts/etc window to silver, but certain section positions will be moved. Test this out on a blank profile to see how it changes. <lua> setAppStyleSheet([[ QGroupBox {
background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #E0E0E0, stop: 1 #FFFFFF); border: 2px solid gray; border-radius: 5px; margin-top: 1ex; /* leave space at the top for the title */ }
QGroupBox::title { subcontrol-origin: margin; subcontrol-position: top center; /* position at the top center */ padding: 0 3px; background-color: qlineargradient(x1: 0, y1: 0, x2: 0, y2: 1, stop: 0 #FFOECE, stop: 1 #FFFFFF); }]]);
</lua>
Added in Mudlet 2.0-rc5
Table Functions
table.complement
table.concat
table.contains
table.foreachi
table.foreach
table.getn
table.intersection
table.insert
table.index_of
table.is_empty
table.load
table.maxn
table.n_union
table.n_complement
table.n_intersection
table.pickle
table.remove
table.save
table.sort
table.size
table.setn
table.unpickle
table.update
table.union
String Functions
string.byte
string.char
string.cut
- string.cut(string, maxLen)
- Cuts string to the specified maximum length.
- Returns the modified string.
- Parameters
- string:
- The text you wish to cut. Passed as a string.
- maxLen
- The maximum length you wish the string to be. Passed as an integer number.
- Example
<lua> --The following call will return 'abc' and store it in myString mystring = string.cut("abcde", 3) --You can easily pad string to certain length. Example below will print 'abcde ' e.g. pad/cut string to 10 characters. local s = "abcde" s = string.cut(s .. " ", 10) -- append 10 spaces echo("'" .. s .. "'") </lua>
string.dump
string.enclose
- string.enclose(String)
- Wraps a string with [[ ]]
- Returns the altered string.
- Parameters
- String: The string to enclose. Passed as a string.
- Example
<lua> --This will echo 'Oh noes!' to the main window echo("'" .. string.enclose("Oh noes!") .. "'") </lua>
string.ends
- string.ends(String, Suffix)
- Test if string is ending with specified suffix.
- Returns true or false.
- See also: string.starts
- Parameters
- String:
- The string to test. Passed as a string.
- Suffix:
- The suffix to test for. Passed as a string.
- Example
<lua> --This will test if the incoming line ends with "in bed" and if not will add it to the end. if not string.ends(line, "in bed") then
echo("in bed\n")
end </lua>
string.find
string.findPattern
string.findPattern(text, pattern) Return first matching substring or nil.
Parameters
text: pattern:
Usage: Following example will print: "I did find: Troll" string. <lua>
local match = string.findPattern("Troll is here!", "Troll") if match then echo("I did find: " .. match) end
</lua> This example will find substring regardless of case.
local match = string.findPattern("Troll is here!", string.genNocasePattern("troll")) if match then echo("I did find: " .. match) end
Return value:
nil or first matching substring
See also:
string.genNocasePattern()
string.format
string.genNocasePattern
string.genNocasePattern(s)
Generate case insensitive search pattern from string.
Parameters
s:
Usage: Following example will generate and print "123[aA][bB][cC]" string.
echo(string.genNocasePattern("123abc"))
Return value:
case insensitive pattern string
string.gfind
string.gmatch
string.gsub
string.len
string.lower
string.match
string.rep
string.reverse
string.split
- string.split(String, delimiter)
- myString:split(delimiter)
- Splits a string into a table by the given delimiter. Can be called against a string (or variable holding a string) using the second form above.
- Returns a table containing the split sections of the string.
- Parameters
- String:
- The string to split. Parameter is not needed if using second form of the syntax above. Passed as a string.
- delimiter:
- The delimiter to use when splitting the string. Passed as a string.
- Example
<lua> -- This will split the string by ", " delimiter and print the resulting table to the main window. names = "Alice, Bob, Peter" name_table = string.split(names, ", ") display(name_table)
--The alternate method names = "Alice, Bob, Peter" name_table = names:split(", ") display(name_table) </lua>
Either method above will print out:
table { 1: 'Alice' 2: 'Bob' 3: 'Peter' }
string.starts
- string.starts(String, Prefix)
- Test if string is starting with specified prefix.
- Returns true or false
- See also: string.ends
- Parameters
- String:
- The string to test. Passed as a string.
- Prefix:
- The prefix to test for. Passed as a string.
- Example
<lua> --The following will see if the line begins with "You" and if so will print a statement at the end of the line if string.starts(line, "You") then
echo("====oh you====\n")
end </lua>
string.sub
string.title
- string.title(String)
- string:title()
- Capitalizes the first character in a string.
- Returns the altered string.
- Parameters
- String
- The string to modify. Not needed if you use the second form of the syntax above.
- Example
<lua> --Variable testname is now Anna. testname = string.title("anna") --Example will set test to "Bob". test = "bob" test = test:title() </lua>
string.trim
- string.trim(String)
- Trims String, removing all 'extra' white space at the beginning and end of the text.
- Returns the altered string.
- Parameters
- String:
- The string to trim. Passed as a string.
- Example
<lua> --This will print 'Troll is here!', without the extra spaces. local str = string.trim(" Troll is here! ") echo("'" .. str .. "'") </lua>
string.upper
Mudlet Object Functions
tempTimer
- tempTimer(time, code to do)
Creates a temporary single shot timer and returns the timer ID for subsequent enableTimer(), disableTimer() and killTimer() calls. You can use 2.3 seconds or 0.45 etc. After it has fired, the timer will be deactivated and killed.
- Parameters
- time: the time in seconds for which to set the timer for
- code to do: the code to do when the timer is up - wrap it in [[ ]], or provide a Lua function
- Examples
<lua> -- wait half a second and then run the command tempTimer( 0.5, send("kill monster") )
-- or an another example - two ways to 'embed' variable in a code for later: local name = matches[2] tempTimer(2, send("hello, ..name..!")) -- or: tempTimer(2, function()
send("hello, "..name)
end) </lua>
- Note
[[ ]] can be used to quote strings in Lua. The difference to the usual `" " quote syntax is that `[[ ]] also accepts the character ". Consequently, you don’t have to escape the " character in the above script. The other advantage is that it can be used as a multiline quote, so your script can span several lines. Also note that the Lua code that you provide as an argument is compiled from a string value when the timer fires. This means that if you want to pass any parameters by value e.g. you want to make a function call that uses the value of your variable myGold as a parameter you have to do things like this:
<lua> tempTimer( 3.8, echo("at the time of the tempTimer call I had .. myGold .. gold.") ) tempTimer also accepts functions (and thus closures) - which can be an easier way to embed variables and make the code for timers look less messy:
local variable = matches[2] tempTimer(3, function () send("hello, " .. variable) end) </lua>
Mapper Functions
These are functions that are to be used with the Mudlet Mapper. The mapper is designed to be MUD-generic - it only provides the display and pathway calculations, to be used in Lua scripts that are tailored to the MUD you're playing. For a collection of pre-made scripts and general mapper talk, visit the http://forums.mudlet.org/viewforum.php?f=13[mapper section] of the forums.
To register a script as a mapping one with Mudlet (so Mudlet knows the profile has one and won't bother the user when they open the map), please do this in your script:
<lua> mudlet = mudlet or {}; mudlet.mapper_script = true </lua>
addRoom
addRoom(roomID)
Creates a new room with the given ID, returns true if the room was successfully created.
- See also: createRoomID
<lua> local newroomid = createRoomID() addRoom(newroomid) </lua>
createRoomID
usableId = createRoomID()
Returns the lowest possible room ID you can use for creating a new room. If there are gaps in room IDs your map uses it, this function will go through the gaps first before creating higher IDs.
- See also: addRoom
centerview
centerview (room number)
Centers the map view onto the given room ID. The map must be open to see this take effect. This function can also be used to see the map of an area if you know the number of a room there and the area and room are mapped.
createMapper
createMapper(x, y, width, height)
Creates a miniconsole window for mapper to render in, the with the given dimensions. You can only create one at a time at the moment.
<lua> createMapper(0,0,300,300) -- creates a 300x300 mapper top-right of Mudlet setBorderLeft(305) -- adds a border so text doesn't underlap the mapper display </lua>
getAreaRooms
getAreaRooms(area id)
Returns an indexed table with all rooms IDs for a given area ID (room IDs are values), or nil if no such area exists.
Note that on Mudlet versions prior to the 2.0 final release, this function would raise an error.
<lua> -- using the sample findAreaID() function defined in the getAreaTable() example, -- we'll define a function that echo's us a nice list of all rooms in an area with their ID function echoRoomList(areaname)
local id, msg = findAreaID(areaname) if id then local roomlist, endresult = getAreaRooms(id), {} -- obtain a room list for each of the room IDs we got for _, id in ipairs(roomlist) do endresult[id] = getRoomName(id) end -- now display something half-decent looking cecho(string.format( "List of all rooms in %s (%d):\n", msg, table.size(endresult)))
for roomid, roomname in pairs(endresult) do cecho(string.format( "%6s: %s\n", roomid, roomname)) end elseif not id and msg then echo("ID not found; " .. msg) else echo("No areas matched the query.") end
end </lua>
getAreaTable
getAreaTable()
Returns a key(area name)-value(area id) table with all known areas and their IDs. There is an area with the name of and an ID of 0 included in it, you should ignore that.
<lua> -- example function that returns the area ID for a given area
function findAreaID(areaname)
local list = getAreaTable()
-- iterate over the list of areas, matching them with substring match. -- if we get match a single area, then return it's ID, otherwise return -- 'false' and a message that there are than one are matches local returnid, fullareaname for area, id in pairs(list) do if area:find(areaname, 1, true) then if returnid then return false, "more than one area matches" end returnid = id; fullareaname = area end end return returnid, fullareaname
end
-- sample use: local id, msg = findAreaID("blahblah") if id then
echo("Found a matching ID: " .. id")
elseif not id and msg then
echo("ID not found; " .. msg)
else
echo("No areas matched the query.")
end </lua>
getPath
getPath(roomID from, roomID to)
Returns a boolean true/false if a path between two room IDs is possible. If it is, the global `speedWalkPath` table is set to all of the directions that have to be taken to get there, and the global `speedWalkDir` table is set to all of the roomIDs you'll encounter on the way.
<lua> -- check if we can go to a room - if yes, go to it if getPath(34,155) then
gotoRoom(155)
else
echo("\nCan't go there!")
end </lua>
getRoomCoordinates
x,y,z = getRoomCoordinates(room ID)
Returns the room coordinates of the given room ID.
<lua> local x,y,z = getRoomCoordinates(roomID) echo("Room Coordinates for "..roomID..":") echo("\n X:"..x) echo("\n Y:"..y) echo("\n Z:"..z) </lua>
getRoomExits
getRoomExits (roomID) Returns the currently known non-special exits for a room in an key-index form: exit = exitroomid, ie:
<lua> table {
'northwest': 80 'east': 78
} </lua>
gotoRoom
gotoRoom (roomID) Speedwalks you to the given room from your current room if it is able and knows the way. You must turn the map on for this to work, else it will return "(mapper): Don't know how to get there from here :(".
lockRoom
lockRoom (roomID, lock = true/false)
Locks a given room id from future speed walks (-> never enter that room).
<lua> lockRoom(1, true) -- locks a room if from being walked through when speedwalking. lockRoom(1, false) -- unlocks the room, adding it back to possible rooms that can be walked through. </lua>
roomLocked
locked = roomLocked(roomID)
Returns true or false whenever a given room is locked.
<lua> echo(string.format("Is room #4545 locked? %s.", roomLocked(4545) and "Yep" or "Nope")) </lua>
roomExists
roomExists(roomID)
Returns a boolean true/false depending if the room with that ID exists (is created) or not.
setCustomEnvColor
setCustomEnvColor(environmentID, r,g,b)
Creates, or overrides an already created custom color definition for a given environment ID. Note that this will not work on the default environment colors - those are adjustable by the user in the preferences. You can however create your own environment and use a custom color definition for it.
<lua> setRoomEnv(571, 200) -- change the room's environment ID to something arbitrary, like 200 setCustomEnvColor(200, unpack(color_table.blue)) -- set the color of environmentID 200 to blue </lua>
getCustomEnvColorTable
envcolors = getCustomEnvColorTable()
Returns a table with customized environments, where the key is the environment ID and the value is a indexed table of rgb values.
<lua> {
envid1 = {r,g,b}, envid2 = {r,g,b}
} </lua>
setRoomEnv
setRoomEnv(roomID, newEnvID)
Sets the given room to a new environment ID. You don't have to use any functions to create it - can just set it right away.
<lua> setRoomEnv(551, 34) -- set room with the ID of 551 to the environment ID 34 </lua>
getRoomEnv
envID = getRoomEnv(roomID)
Returns the environment ID of a room. The mapper does not store environment names, so you'd need to keep track of which ID is what name yourself.
<lua> funtion checkID(id)
echo(strinf.format("The env ID of room #%d is %d.\n", id, getRoomEnv(id)))
end </lua>
searchRoom
searchRoom (room name)
Searches for rooms that match (by case-insensitive, substring match) the given room name. It returns a key-value table in form of roomid = roomname, like so:
<lua> display(searchRoom("master"))
--[[ would result in: table {
17463: 'in the branches of the Master Ravenwood' 3652: 'master bedroom' 10361: 'Hall of Cultural Masterpieces' 6324: 'Exhibit of the Techniques of the Master Artisans' 5340: 'office of the Guildmaster' 19067: 'the master's gallery' 21546: 'the Grand Master's Chambers' 6592: 'hall before the Master Chambers' 4395: 'customs Office and Harbourmaster's' 18978: 'the master's salon' 1622: 'before the office of the harbourmaster' 18869: 'Master's gallery and reception suite' 14456: 'north of the Master Gear' 14624: 'beastmaster's hangout' 9078: 'chambers of the Master of the Bloodhunt' 6593: 'Master Quettle's Chambers' 10210: 'the chambers of Master Blasterson' 14465: 'south of the Master Gear' 5341: 'the chamber of the Guildmaster' 7712: 'central hall in the beastmaster apartments' 2004: 'office of the guildmaster' 14457: 'the Master Gear' 1337: 'before the Master Ravenwood Tree'
} ]]</lua>
If no rooms are found, then an empty table is returned.
setExit
setExit(from roomID, to roomID, direction)
Creates a one-way exit from one room to another using a standard direction - which can be either one of n, ne, nw, e, w, s, se, sw, u, d, in, out.
Returns false if the exit creation didn't work.
<lua> -- alias pattern: ^exit (\d+) (\w+)$
if setExit(mmp.currentroom, tonumber(matches[2]),matches[3]) then echo("\nExit set to room:"..matches[2]..", Direction:"..string.upper(matches[3])) centerview(mmp.currentroom) else mmp.echo("Failed to set the exit.") end </lua>
This function can also delete exits from a room if you use it like so: setExit(from roomID, -1, direction)
Which will delete an outgoing exit in the specified direction from a room.
<lua> -- locate the room on the other end, so we can unlink it from there as well if necessary local otherroom if getRoomExits(getRoomExits(mmp.currentroom)[dir])[mmp.ranytolong(dir)] then
otherroom = getRoomExits(mmp.currentroom)[dir]
end
if setExit(mmp.currentroom, -1, dir) then
if otherroom then if setExit(otherroom, -1, mmp.ranytolong(dir)) then mmp.echo(string.format("Deleted the %s exit from %s (%d).", dir, getRoomName(mmp.currentroom), mmp.currentroom)) else mmp.echo("Couldn't delete the incoming exit.") end else mmp.echo(string.format("Deleted the one-way %s exit from %s (%d).", dir, getRoomName(mmp.currentroom), mmp.currentroom)) end
else
mmp.echo("Couldn't delete the outgoing exit.")
end </lua>
setGridMode
setGridMode(area, true/false)
Enables grid/wilderness view mode for an area - this will cause the rooms to lose their visible exit connections, like you'd see on compressed ASCII maps, both in 2D and 3D view mode.
<lua> setGridMode(55,true) -- set area with ID 55 to be in grid mode </lua>
setRoomCoordinates
setRoomCoordinates(roomID, x, y, z)
Sets the given room ID to be at the following coordinates visually on the map, where z is the up/down level.
0,0,0 is the center of the map.
<lua> -- alias pattern: ^set rc (-?\d+) (-?\d+) (-?\d+)$ local x,y,z = getRoomCoordinates(previousRoomID) local dir = matches[2]
if dir == "n" then y = y+1 elseif dir == "ne" then y = y+1 x = x+1 elseif dir == "e" then x = x+1 elseif dir == "se" then y = y-1 x = x+1 elseif dir == "s" then y = y-1 elseif dir == "sw" then y = y-1 x = x-1 elseif dir == "w" then x = x-1 elseif dir == "nw" then y = y+1 x = x-1 elseif dir == "u" or dir == "up" then z = z+1 elseif dir == "down" then z = z-1 end setRoomCoordinates(roomID,x,y,z) centerview(roomID) </lua>
You can make them relative as well:
<lua> -- alias pattern: ^src (\w+)$
local x,y,z = getRoomCoordinates(previousRoomID) local dir = matches[2]
if dir == "n" then y = y+1 elseif dir == "ne" then y = y+1 x = x+1 elseif dir == "e" then x = x+1 elseif dir == "se" then y = y-1 x = x+1 elseif dir == "s" then y = y-1 elseif dir == "sw" then y = y-1 x = x-1 elseif dir == "w" then x = x-1 elseif dir == "nw" then y = y+1 x = x-1 elseif dir == "u" or dir == "up" then z = z+1 elseif dir == "down" then z = z-1 end setRoomCoordinates(roomID,x,y,z) centerview(roomID) </lua>
setRoomWeight
setRoomWeight(roomID, weight)
Sets a weight to the given roomID. By default, all rooms have a weight of 0 - the higher the weight is, the more likely the room is to be avoided for pathfinding. For example, if travelling across water rooms takes more time than land ones - then you'd want to assign a weight to all water rooms, so they'd be avoided if there are possible land pathways.
<lua> setRoomWeight(1532, 3) -- avoid using this room if possible, but don't completely ignore it </lua>
To completely avoid a room, make use of lockRoom().
addSpecialExit
addSpecialExit(roomIDFrom, roomIDTo, command)
Creates a one-way from one room to another, that will use the given command for going through them.
<lua> -- sample alias pattern: ^spe (\d+) (.*?)$ -- mmp.currentroom is your current room ID in this example addSpecialExit(mmp.currentroom,tonumber(matches[2]), matches[3]) echo("\n SPECIAL EXIT ADDED TO ROOMID:"..matches[2]..", Command:"..matches[3]) centerview(mmp.currentroom) </lua>
getSpecialExits
exits = getSpecialExits(roomID)
Returns a roomid - command table of all special exits in the room. If there are no special exits in the room, the table returned will be empty.
<lua> getSpecialExits(1337)
-- results in: --[[ table {
12106: 'faiglom nexus'
} ]] </lua>
getSpecialExitsSwap
exits = getSpecialExitsSwap(roomID)
Very similar to getSpecialExits, but returns the rooms in the command - roomid style.
clearSpecialExits
clearSpecialExits(roomID)
Removes all special exits from a room.
<lua> clearSpecialExits(1337)
if #getSpecialExits(1337) == 0 then -- clearSpecialExits will neve fail on a valid room ID, this is an example
echo("All special exits successfully cleared from 1337.\n")
end </lua>
getRoomWeight
room weight = getRoomWeight(roomID)
Returns the weight of a room. By default, all new rooms have a weight of 1.
<lua> display("Original weight of room 541: "..getRoomWeight(541) setRoomWeight(541, 3) display("New weight of room 541: "..getRoomWeight(541) </lua>
getRoomArea
areaID = getRoomArea(roomID)
Returns the area ID of a given room ID. To get the area name, you can check the area ID against the data given by getAreaTable() function, or use the getRoomAreaName function.
Note that if the room ID does not exist, this function will raise an error
<lua> display("Area ID of room #100 is: "..getRoomArea(100))
display("Area name for room #100 is: "..getRoomAreaName(getRoomArea(100))) </lua>
setRoomArea
setRoomArea(roomID, newAreaID)
Assigns the given room to a new area.
setAreaName
setAreaName(areaID, newName)
Renames an existing area to the new name.
<lua> setAreaName(2, "My city") </lua>
setRoomName
setRoomName(roomID, newName)
Renames an existing room to a new name.
<lua> setRoomName(534, "That evil room I shouldn't visit again.") lockRoom(534, true) -- and lock it just to be safe </lua>
getRoomName
roomName = getRoomName(roomID)
Returns the room name for a given room id.
<lua> echo(string.format("The name of the room id #455 is %s.", getRoomname(455)) </lua>
getRoomAreaName
areaname = getRoomAreaName(areaID)
Returns the area name for a given area id.
<lua> echo(string.format("room id #455 is in %s.", getRoomAreaName(getRoomArea(455)))) </lua>
deleteArea
deleteArea(areaID)
Deletes the given area, permanently. This will also delete all rooms in it!
<lua> deleteArea(23) </lua>
highlightRoom
highlightRoom(roomID, r, g, b )
Highlights a room with the given color, which will override it's environment color.
Available since Mudlet 2.0 final release
<lua> -- color some room red highlightRoom(5, 255, 0 0)
-- or use a name from showColors(), gold in this case highlightRoom(351, unpack(color_table.gold)) </lua>
unHighlightRoom
unHighlightRoom(roomID)
Unhighlights a room if it was previously highlighted and restores the rooms original environment color.
Available since Mudlet 2.0 final release
<lua> unHighlightRoom(4534) </lua>
setRoomUserData
setRoomUserData(roomID, key (as a string), value (as a string))
Stores information about a room under a given key. Similar to Lua's key-value tables, except only strings may be used here. One advantage of using userdata is that it's stored within the map file itself - so sharing the map with someone else will pass on the user data. You can have as many keys as you'd like.
Returns true if successfully set.
<lua> -- can use it to store room descriptions... setRoomUserData(341, "description", "This is a plain-looking room.")
-- or whenever it's outdoors or not... setRoomUserData(341, "ourdoors", "true")
-- how how many times we visited that room local visited = getRoomUserData(341, "visitcount") visited = (tonumber(visited) or 0) + 1 setRoomUserData(341, "visitcount", tostring(visited))
-- can even store tables in it, using the built-in yajl.to_string function setRoomUserData(341, "some table", yajl.to_string({name = "bub", age = 23})) display("The denizens name is: "..yajl.to_value(getRoomUserData(341, "some table")).name) </lua>
getRoomUserData
data = getRoomUserData(roomID, key (as a string))
Returns the user data stored at a given room with a given key, or "" if none is stored. Use setRoomUserData for setting the user data.
<lua> display(getRoomUserData(341, "visitcount")) </lua>
clearRoomUserData
clearRoomUserData(roomID)
Clears all user data from a given room.
<lua> clearRoomUserData(341) </lua>
addAreaName
areaID = addAreaName(areaName)
Adds a new area name and returns the new area ID for the new name. If the name already exists, -1 is returned.
<lua> local newID = addAreaName("My house")
if newID == -1 then echo("That area name is already taken :(\n") else echo("Created new area with the ID of "..newid..".\n") end </lua>
getRoomsByPosition
getRoomsByPosition(areaID, x,y,z)
Returns an indexed table of all rooms at the given coordinates in the given area, or an empty one if there are none. This function can be useful for checking if a room exists at certain coordinates, or whenever you have rooms overlapping.
<lua> -- sample script to determine a room nearby, given a relative direction from the current room local otherroom if matches[2] == "" then
local w = matches[3] local ox, oy, oz, x,y,z = getRoomCoordinates(mmp.currentroom) local has = table.contains if has({"west", "left", "w", "l"}, w) then x = (x or ox) - 1; y = (y or oy); z = (z or oz) elseif has({"east", "right", "e", "r"}, w) then x = (x or ox) + 1; y = (y or oy); z = (z or oz) elseif has({"north", "top", "n", "t"}, w) then x = (x or ox); y = (y or oy) + 1; z = (z or oz) elseif has({"south", "bottom", "s", "b"}, w) then x = (x or ox); y = (y or oy) - 1; z = (z or oz) elseif has({"northwest", "topleft", "nw", "tl"}, w) then x = (x or ox) - 1; y = (y or oy) + 1; z = (z or oz) elseif has({"northeast", "topright", "ne", "tr"}, w) then x = (x or ox) + 1; y = (y or oy) + 1; z = (z or oz) elseif has({"southeast", "bottomright", "se", "br"}, w) then x = (x or ox) + 1; y = (y or oy) - 1; z = (z or oz) elseif has({"southwest", "bottomleft", "sw", "bl"}, w) then x = (x or ox) - 1; y = (y or oy) - 1; z = (z or oz) elseif has({"up", "u"}, w) then x = (x or ox); y = (y or oy); z = (z or oz) + 1 elseif has({"down", "d"}, w) then x = (x or ox); y = (y or oy); z = (z or oz) - 1 end
local carea = getRoomArea(mmp.currentroom) if not carea then mmp.echo("Don't know what area are we in.") return end
otherroom = select(2, next(getRoomsByPosition(carea,x,y,z)))
if not otherroom then mmp.echo("There isn't a room to the "..w.." that I see - try with an exact room id.") return else mmp.echo("The room "..w.." of us has an ID of "..otherroom) end
</lua>
Miscellaneous Functions
spawn
- t = spawn(read function, process to spawn)
- Spawns a process and opens a communicatable link with it - read function is the function you'd like to use for reading output from the process, and t is a table containing functions specific to this connection - send(data), true/false = isRunning(), and close().
<lua> -- simple example on a program that quits right away, but prints whatever it gets using the 'display' function local f = spawn(display, "ls") display(f.isRunning()) f.close() </lua>
downloadFile
- downloadFile(saveto, url)
- Downloads the resource at the given url into the saveto location on disk. This does not pause the script until the file is downloaded - instead, it lets it continue right away and downloads in the background. When a download is finished, the sysDownloadDone event is raised (with the saveto location as the argument), or when a download fails, the sysDownloadError event is raised with the reason for failure. You may call downloadFile multiple times and have multiple downloads going on at once - but they aren’t guaranteed to be downloaded in the same order that you started them in.
- Requires Mudlet 2.0+
- Example
<lua> -- this example will check the Imperian homepage to see how many players are on right now
-- in an alias, download the Imperian homepage for stats processing downloadFile(getMudletHomeDir().."/page.html", "http://www.imperian.com/")
-- then create a new script with the name of downloaded_file, add the event handler
-- for sysDownloadDone, and use this to parse the webpage and display the amount
function downloaded_file(_, filename)
-- is the file that downloaded ours? if not filename:match("page", 1, true) then return end
-- parse our ownloaded file for the player count io.input(filename) local s = io.read("*all") local pc = s:match([[<a href='players.php%?search=who'>(%d+)</a>]]) display("Imperian has "..tostring(pc).." players on right now.") io.open():close() os.remove(filename)
end </lua>
sendIrc
- sendIrc(channel, message)
- Sends a message to an IRC channel or person. You must have the IRC window open, and if speaking to a channel, be joined in that channel. IRC currently only works on the freenode network and password-protected channels aren't supported.
- Parameters
- channel:
- The channel to send the message to. Can be #<channelname> to send to a channel, or <person name> to send to a person. Passed as a string.
- message:
- The message to send. Passed as a string.
- Example
<lua> --This would send "hello from Mudlet!" to the channel #mudlet on freenode.net sendIrc("#mudlet", "hello from Mudlet!") --This would send "identify password" in a private message to Nickserv on freenode.net sendIrc("Nickserv", "identify password") </lua>
showColors
- showColors(columns)
- shows the named colors currently available in Mudlet's color table.
- See Also: bg, fg, cecho
- Parameters
- columns:
- Number of columns to print the color table in. Passed as an integer number.
- Example
<lua> showColors(4) </lua> The output for this is: