Manual:Lua Functions

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:

The name of the color to set the background to.

Example

<lua> --This would change the 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", [[

You are under attack!

]] );

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>

String Functions

string.cut

string.cut(s, maxLen)

Cut string to specified maximum length.

Parameters:

    s:
    maxLen:

Usage:

    Following call will return 'abc'.
    string.cut("abcde", 3)

You can easily pad string to certain length. Example bellow will print 'abcde ' e.g. pad/cut string to 10 characters.

     local s = "abcde"
     s = string.cut(s .. "          ", 10)   -- append 10 spaces
     echo("'" .. s .. "'")

string.enclose

string.enclose(s, maxlevel)

Enclose string by long brackets.

Parameters:

    s:
    maxlevel:

string.ends

string.ends(String, Suffix)

Test if string is ending with specified suffix.

Parameters:

    String:
    Suffix:

See also:

    string.starts()

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.

    local match = string.findPattern("Troll is here!", "Troll")
    if match then
    echo("I did find: " .. match)
    end

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.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.starts

string.starts(String, Prefix) Test if string is starting with specified prefix. Parameters:

    String:
    Prefix:

See also:

    string.ends()

string.trim

string.trim (s) Trim string (remove all white spaces around string).

Parameters:

    s:

Usage: Example will print 'Troll is here!'.

     local str = string.trim("  Troll is here!  ")
     echo("'" .. str .. "'")

string:split

string:split(delimiter) Splits a string into a table by the given delimiter.

Parameters:

   delimiter:

Usage: Split string by ", " delimiter.

    names = "Alice, Bob, Peter"
    name_table = names:split(", ")
    display(name_table)

Previous code will print out:

   table {
   1: 'Alice'
   2: 'Bob'
   3: 'Peter'
   }

Return value:

   array with split strings

string:title

string:title() Capitalize first character in a string.

Usage: Variable testname is now Anna.

     testname = string.title("anna")

Example will set test to "Bob".

     test = "bob"
     test = string.title(test)

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:

mudlet = mudlet or {}; mudlet.mapper_script = true

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:

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'
}
]]

If no rooms are found, then an empty table is returned.

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.

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

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.

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 :(".

getRoomExits

getRoomExits (roomID) Returns the currently known non-special exits for a room in an key-index form: exit = exitroomid, ie:

table {
  'northwest': 80
  'east': 78
}

addRoom

addRoom(roomID)

Creates a new room with the given ID, returns true if the room was successfully created.

lockRoom

lockRoom (roomID, lock = true/false)

Locks a given room id from future speed walks (-> never enter that room).

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.

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.

setRoomWeight(1532, 1) -- avoid using this room if possible, but don't completely ignore it

To completely avoid a room, make use of lockRoom().

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.

-- 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

getAreaRooms

getAreaRooms(area id)

Returns a key-value table with all rooms IDs for a given area ID.

-- 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

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.

-- 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

roomExists

roomExists(roomID)

Returns a boolean true/false depending if the room with that ID exists (is created) or not.

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.

-- 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

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.

-- 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

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.

-- 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)

You can make them relative as well:

-- 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)

getRoomCoordinates

x,y,z = getRoomCoordinates(room ID)

Returns the room coordinates of the given room ID.

local x,y,z = getRoomCoordinates(roomID)
echo("Room Coordinates for "..roomID..":")
echo("\n     X:"..x)
echo("\n     Y:"..y)
echo("\n     Z:"..z)

Miscellaneous Functions

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: