User:Kebap/Manual:Lua Functions

Here you can find a long list of all possible Lua functions and programming interfaces (API) that Mudlet offers. Due to the integrated Lua, you can also use all regular Lua functions. In the following page, we will explain the usage, expected behaviour and examples for the functions added in Mudlet.

Function Categories

Basic Essential Functions: These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.

Date/Time Functions: A collection of functions for handling Date & Time.

File System Functions: A collection of functions for interacting with the file system.

Basic Essentials

These functions are generic functions used in normal scripting. These deal with mainly everyday things, like sending stuff and echoing to the screen.

send

send(command, showOnScreen)

This sends "command" directly to the network layer, skipping the alias matching. The optional second argument of type boolean (print) determines if the outgoing command is to be echoed on the screen.

See also: sendAll()

Note: If you want your command to be checked as if it's an alias, use expandAlias() instead - send() will ignore them.

send( "Hello Jane" ) --echos the command on the screen
send( "Hello Jane", true ) --echos the command on the screen
send( "Hello Jane", false ) --does not echo the command on the screen

-- use a variable in the send:
send("kick "..target)

echo

echo([miniconsoleName or labelName], text)

This function appends text at the end of the current line.

Parameters

• miniconsoleName: (optional) the miniconsole to echo to, or:
• labelName: (optional) the label to echo to.
• text: text you'd like to see printed. You can use \n in an echo to insert a new line. If you're echoing this to a label, you can also use styling to colour, center, increase/decrease size of text and various other formatting options as listed here.

See also: moveCursor(), insertText(), cecho(), decho(), hecho()

Example

-- a miniconsole example

-- first, determine the size of your screen
local windowWidth, windowHeight = getMainWindowSize()

-- create the miniconsole
createMiniConsole("sys", windowWidth-650,0,650,300)
setBackgroundColor("sys",255,69,0,255)
setMiniConsoleFontSize("sys", 8)
-- wrap lines in window "sys" at 40 characters per line - somewhere halfway, as an example
setWindowWrap("sys", 40)

echo("sys","Hello world!\n")
cecho("sys", "<:OrangeRed>This is random spam with the same background\n")
cecho("sys", "<blue:OrangeRed>and this is with a blue foreground. ")
cecho("sys", "<bisque:BlueViolet>Lastly, this is with both a foreground and a background.\n")

-- a label example

-- 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 opaque) the background text can still be read through.
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", 255, 204, 0, 200)
echo("messageBox", [[<p style="font-size:35px"><b><center><font color="red">You are under attack!</font></center></b></p>]])

display

display(content)

This is much like echo, in that is will show text at your screen, not send anything to anywhere. However, it also works with other objects than just text, like a number, table or function. This function is useful to easily take a look at the values of a lua table, for example. If a value is a string, it'll be in quotes, and if it's a number, it won't be quoted.

Note: Do not use this to display information to end-users. It may be hard to read. It is mainly useful for developing/debugging.

myTable = {} -- create an empty lua table
myTable.foo = "Hello there" -- add a text
myTable.bar = 23 -- add a number
myTable.ubar = function () echo("OK") end -- add more stuff
display( myTable ) -- take a look inside the table

debugc

debugc(content)

Again this will not send anything to anywhere. It will however print not to the main window, but only to the errors view. You need to open that window to see the message.

See also: Errors View

Note: Do not use this to display information to end-users. It will be hard to find. It is mainly useful for developing/debugging.

debugc(" Trigger successful!")
-- Text will be shown in errors view, not to main window.

Date & Time Functions

A collection of functions for handling Date & Time.

datetime:parse

datetime:parse(source, format, as_epoch)

Parses the specified source string, according to the format if given, to return a representation of the date/time. If as_epoch is provided and true, the return value will be a Unix epoch — the number of seconds since 1970. This is a useful format for exchanging date/times with other systems. If as_epoch is false, then a Lua time table will be returned. Details of the time tables are provided in the Lua Manual.

Supported Format Codes

%b = Abbreviated Month Name
%B = Full Month Name
%d = Day of Month
%H = Hour (24-hour format)
%I = Hour (12-hour format, requires %p as well)
%p = AM or PM
%m = 2-digit month (01-12)
%M = 2-digit minutes (00-59)
%S = 2-digit seconds (00-59)
%y = 2-digit year (00-99), will automatically prepend 20 so 10 becomes 2010 and not 1910.
%Y = 4-digit year.

getEpoch

getEpoch()

This function returns the seconds since Unix epoch with milliseconds.

Example

getEpoch() -- will show e.g. 1523555867.191

getTime

getTime(returntype, format)

returntype takes a boolean value (in Lua anything but false or nil will translate to true). If false, the function will return a table in the following format:

{ 'min': #, 'year': #, 'month': #, 'day': #, 'sec': #, 'hour': #, 'msec': # }

If true, it will return the date and time as a string using a format passed to the format arg or the default of "yyyy.MM.dd hh:mm:ss.zzz" if none is supplied:

2012.02.18 00:52:52.489

Format expressions:

h               the hour without a leading zero (0 to 23 or 1 to 12 if AM/PM display)
hh              the hour with a leading zero (00 to 23 or 01 to 12 if AM/PM display)
H               the hour without a leading zero (0 to 23, even with AM/PM display)
HH              the hour with a leading zero (00 to 23, even with AM/PM display)
m               the minute without a leading zero (0 to 59)
mm              the minute with a leading zero (00 to 59)
s               the second without a leading zero (0 to 59)
ss              the second with a leading zero (00 to 59)
z               the milliseconds without leading zeroes (0 to 999)
zzz             the milliseconds with leading zeroes (000 to 999)
AP or A         use AM/PM display. AP will be replaced by either "AM" or "PM".
ap or a         use am/pm display. ap will be replaced by either "am" or "pm".

d               the day as number without a leading zero (1 to 31)
dd              the day as number with a leading zero (01 to 31)
ddd             the abbreviated localized day name (e.g. 'Mon' to 'Sun'). Uses QDate::shortDayName().
dddd            the long localized day name (e.g. 'Monday' to 'Qt::Sunday'). Uses QDate::longDayName().
M               the month as number without a leading zero (1-12)
MM              the month as number with a leading zero (01-12)
MMM             the abbreviated localized month name (e.g. 'Jan' to 'Dec'). Uses QDate::shortMonthName().
MMMM            the long localized month name (e.g. 'January' to 'December'). Uses QDate::longMonthName().
yy              the year as two digit number (00-99)
yyyy            the year as four digit number

All other input characters will be ignored. Any sequence of characters that are enclosed in single quotes will be treated as text and not be used as an expression. Two consecutive single quotes ('') are replaced by a single single quote in the output.

Example

-- Get time as a table
getTime()

-- Get time with default string
getTime(true)

-- Get time without date and milliseconds
getTime(true, "hh:mm:ss")

getTimestamp

getTimestamp( optional console_name, lineNumber )

Returns the timestamp string as it’s seen when you enable the timestamps view (blue i button bottom right).

Note: Available in Mudlet 1.1.0-pre1.

Example

--Echo the timestamp of the current line in a trigger:
echo(getTimestamp(getLineCount()))

shms

shms( seconds, bool )

Converts seconds into hours, minutes and seconds, displaying the result as a table. An optional second argument can be passed to return the result as an echo.

Note: Available in Mudlet 3.0.

Example

--Determine the total number of seconds and display:
shms(65535, true)