Manual:Scripting

Scripting with Mudlet

Lua tables can basically be considered multidimensional arrays and dictionaries at the same time. If we have the table matches, matches[2] is the first element, matches[n+1] the n-th element.

 a = "Tom"
 matches[2] = "Betty"
 b = matches[2]
 c = a .. b and e will equal "TomBetty"

To output a table you can use a convenience function - display(mytable), which is built into Mudlet.

Lua interface functions - triggers, timers etc.

How to get data from regex capture groups? Regular expression capture groups (e.g. "(\d+)" ) are passed on to Lua scripts as a Lua table matches. To make use of this information inside Lua scripts, you need to specify the number of the capture group within the regex.

Example: You have (\d+) weapons and they are (?:(\b\w+\W+)+)

This regex contains 3 capture groups, but only the 2 green colored ones contain data as the red capture group is a non-capturing group. Consequently, your Lua script gets passed only 2 instead of 3 capture groups and matches[4] is undefined.

In your Lua script you may write following program in order to print the number and status of your weapons on the screen:

You have (\d+) weapons and they are (?:(\b\w+\W+)+)

 number_of_weapons = matches[2]
 status_of_weapons = matches[3]
 notice = number_of_weapons .. status_of_weapons
 echo( notice )
 send( "put weapons in backpack" )

 -- the following 2 lines color the first capture
 -- group red and the second group blue
 -- see below for details

 selectCaptureGroup( 2 )
 setFgColor( 255,0,0 )

 selectCaptureGroup( 3 )
 setFgColor( 0,0,255 )

The best way is to use selectCaptureGroup( number ) to select the proper capture group and then perform your actions on it e.g. replace(), highlight etc. Note: Both selectCaptureGroup() and matches[n] start with group 1 (which is the whole match. The defined capture groups start with 2).

How to select all occurrences of "Tom" and highlight them?

You add a function like this to a script containing you main function definitions. Note that script items differ from all other "scripts" in triggers, timers, actions etc. because they require you to put your code in proper functions that can be called by your other trigger-scripts, timer-scripts etc. via normal function calls. Trigger-scripts, timer-scripts etc. cannot contain any function definitions because they are automatically generated functions themselves because this makes usage a lot easier.

To come back to our question how to select all occurrences of "Tom" and highlight them:

  function setBgColorAll( word, r, g, b )
    i = 0
    word_count = 1
    while i > -1 do
        i = selectString(word, word_count)
        if i == -1 then
             return
        end
        word_count = word_count +1
        setBgColor( r, g, b )
    end
  end

Then you simply define a substring matching trigger on the word "Tom" and in the trigger script you call above function:

setBgColorAll("Tom", 255,50,50)

Since Mudlet 4.11+ it is possible to use name capture groups. You can verify if feature availability by checking mudlet.supports.namedPatterns flag. Let's say you have multiple patterns that you want to handle with one code.

^My name is (?<name>\w+)\. My class is (?<class>\w+)\.

^I am (?<class\w+)\ and my name is (?<name>\w+)\.

Notice that class and name come in different order, therefore in first case we will have name under matches[2] and in second case under matches[3]. With named capture groups in both cases we will have name available under matches.name and class under matches.class.

Code example to handle named matches above:

  echo("Name: " .. matches.name .. "\n")
  echo("Class: " .. matches.class .. "\n")

Sending commands or printing information messages

To print information messages on the session screen you can use the echo( message ) function, or insertText( text ). Currently, it only takes one string as argument.

To send a command to the MUD, you can use the send( command ) function. In Alias scripts the command that is being sent to the MUD is contained in the variable command that you can change in the context of Alias scripts. Alias take regular expressions, as well. As a result, you can use following regex and script to talk like Yoda: Perl regex:

say (\w+).*(\w*).*(.*)

script:

send( "say " .. matches[4] .." " .. matches[2] .." ".. matches[3] )

Note: The variable "command" contains what was entered in the command line or issued via the expandAlias( ) function. If you use expandAlias( command ) inside an alias script the command would be doubled. You have to use send( ) inside an alias script to prevent recursion. This will send the data directly and bypass the alias expansion.

Changing and formatting text from the MUD

When sending commands to the MUD - from now on referred to as output stream - alias scripts find the command that was issued by the user stored in the variable "command".

By manipulating the value, the command can easily be changed before it is being sent to the MUD.

However, things get much more complicated with the data received from the MUD, from now on referred to as input stream. Before triggers can be run on the MUD data, Mudlet has to strip all format codes from the text and store it in data structures associated with the text. Consequently, the text that is being passed on to the trigger processing unit is a small subset of the data received from the MUD. If you want to edit, replace, delete or reformat text from within your trigger scripts you have to keep this in mind if you don’t want to lose all text format information such as colors etc.

As the text is linked with data structures containing the format of the text, the cursor position inside the line is important if data is being changed. You select a word or a sequence of characters from the line and then issue commands to do actions on the selected data.

Replacing the word "Tom" with "Betty" in the line: Jim, Tom and Lucy are learning a new spell. This could be done with following script:

selectString("Tom",1)
replace("Betty")

Things get more complicated if there are two or more occurrences of "Tom" in the line e.g. Jim and Tom like magic. Jim, Tom and Lucy are learning a new spell.

The above example code would select the first occurrence of "Tom" in this line and ignore the second. If you want to work on the the second occurrence of "Tom" you have to specify the occurrence number in the call to select().

selectString( "Tom", 2 )
replace( "Betty" )

This code would change the second "Tom" and leave the first "Tom" alone. The function call

replaceAll( "Betty" )

will replace all occurrences of "Tom" with "Betty" in the line if "Tom" has been selected before. replaceAll() is a convenience function defined in LuaGlobal.lua.

Colorization example: You want to change to color of the words "ugly monster" to red on a white background.

You add a new trigger and define the regex: ugly monster In the script you write:

selectString("ugly monster", 1 )
setFgColor(255,0,0)
setBgColor(255,255,255)
resetFormat()

Another means to select text is to select a range of characters by specifying cursor positions. If we have following line: Jim and Tom like magic. Jim, Tom and Lucy are learning a new spell.

selectSection( 28, 3 )

This example would select the second Tom. The first argument to selectSection is the cursor position within the line and the second argument is the length of the selection.

selectCaptureGroup( number )

This function selects the captureGroup number if you use Perl regular expressions containing capture groups. The first capture group starts with index 1.

Deleting Text - Gagging

deleteLine()

This function deletes the current line - or any line where the cursor is currently placed. You can use repeated calls to this function to effectively erase the entire text buffer. If you want to delete or gag certain words only, you can select the text that you want to delete and then replace it with an empty string e.g:

If you get this line form the MUD: "Mary and Tom walk to the diner."

selectString( "Tom", 1 )
replace( "" )

Then the output will be changed to: "Mary and walk to the diner."

Cursor Movement and Cursor Placement

Mudlet allows you to insert text arbitrarily within the buffer - in the previous line, in the previous ten lines, or even the first line that you've ever saw. These are the tools to help you with the job:

moveCursor( windowName, x, y ) This will move the user cursor of window windowName to the absolute (x/y) coordinates in the text.

moveCursor( "main", 20, 3950 ) will move the cursor on the 20th character from the left on line number 3950. To determine the current cursor position you can use getLineNumber() and getColumnNumber() as well as getLastLineNumber() to get the number of the last line in the text buffer. moveCursorEnd("main") will move the cursor of the main display to end of the buffer. This is always a new line of size 1 containing the character \n.

number_of_last_line_in_text = getLineCount() returns the number of the last line of the text in the console buffer. This number will change as soon as a new \n is printed either by the user or when a new line arrives from the MUD. All lines from the MUD are terminated with \n which is called line feed or the new line character. This control character ends the current line and move the cursor to the beginning of the next line, thus creating a new, empty line below the line that contains the \n.

line_number_of_the_current_cursor_position = getLineNumber()

column_number_of_the_current_cursor_position = getColumnNumber()

luaTable_containing_textlines = getLines( absolute_line_number_from, absolute_line_number_to ) this will return a Lua table containing all lines between the absolute positions from and to.

Note: This function uses absolute line numbers, not relative ones like in moveCursor().

moveCursor() returns true or false depending on whether the move was possible and done.

Inserting text in the middle of the line

Here's an example where we'll append the text (one) right after the word exit in the line of You see a single exit leading west.

The pattern we used was an exact match for You see a single exit leading west. and the code is:

if moveCursor(string.find(line, "exit")+#("exit")-1, getLineNumber()) then
  insertText("(one)")
end

What happened here:

• we triggered on the desired line using our pattern above
• we used moveCursor() to place the cursor in the desired position within the line. moveCursor() takes both the line number and the position within the line to place our virtual cursor on, so
  • we used string.find() to find the position of the word "exit" within the line
  • but string.find() returns us the position of the first character of the word we want, while we want to have the text be right after it - so we find out how long our word is with #("exit"), add that to the number returned by string.find() which gets us the first character + the length of the word - which isn't quite at the end of the word, but the word plus the space (because of string.find() and the first character) - so we substract 1 to move our cursor right at the end of the word
  • we then use getLineNumber() to get the current line number, so our cursor is placed on the current line, at our desired position
• lastly we finally insert the text with insertText(), which puts the text exactly where our virtual cursor is

Done! You can also use cinsertText() for coloured inserts, and other functions mentioned above and in the API manual to help you do what you'd like.

User defined dockable windows

You may want to use dock windows to display information you gathered in your scripts, or you may want to use them as chat windows etc. Check out Geyser.UserWindow on how to add them!

Dynamic Triggers

triggerID = tempTrigger( substring pattern, code ) creates a fast substring matching trigger

triggerID = tempRegexTrigger( regex, code ) creates a regular expression matching trigger

triggerID = tempBeginOfLineTrigger( begin of line pattern, code ) creates a fast begin of line substring trigger

Scripting howtos

How to convert a string to value?

Say you'd like to capture a number from a trigger, but the capture always ends up being a "string" (or, just text on which you can't do any maths on) even if it's a number. To convert it to a number, you'd want to use the tonumber() function:

myage = tonumber(matches[2])

How to highlight my current target?

You can put the following script into your targetting alias:

if id then killTrigger(id) end
id = tempTrigger(target, function() selectString(target, 1) fg("gold") deselect() resetFormat() end)

Where target is your target variable. Note that you have to use the full name, capitalized. If you’d like the script to auto-capitalize for you, you can use this version:

target = target:title()
if id then killTrigger(id) end
id = tempTrigger(target, function() selectString(target, 1) fg("gold") deselect() resetFormat() end)

Note: Ensure you're on Mudlet 3.5.0+ so you can put function() in a tempTrigger().

How to format an echo to a miniConsole?

One of the ways you can create multi-line displays in a miniConsole with variable information is with string.format and the use of [[ ]] brackets for text, which allow for multiple line in text:

local WindowWidth, WindowHeight = getMainWindowSize();
createMiniConsole("sys",WindowWidth-650,0,650,300)

local name, age, sex = "Bob", 34, "male"

cecho("sys", string.format([[

  /---------\
      %s
   %dyrs
   sex - %s 
  \---------/
]], name, age, sex))

How to play a sound when I receive communication while afk?

For this to work, place the line you'd like to trigger on in the first pattern box and select the appropriate pattern type. Then add return not hasFocus() with the Lua function as the second pattern, enable the AND trigger, and set the line delta to zero. Then just enable play sound, choose your sound and you're set!

How can I make a key that toggles between commands?

To make a key that toggles between two actions, for example - sleep/wake, you can use this as the script:

if not sleeping then
  send("sleep")
  sleeping = true
else
  send("wake")
  sleeping = false
end

How can I make a trigger with a next-line condition?

Here's how you can set it up - replace line1 and line2 with appropriate lines.

Here's the Mudlet XML you can download for this!

How to target self or something else?

Using regex and an 'or' statement allows us to consolidate multiple aliases, or an if statement, into a single more simple alias. When a regex is found it will use it, but if you don't specify one then the alternative will be used. The use of 'or' can be used with any function in Mudlet. In this example, one can type "buff" to buff themself, or "buff ally" to buff their ally instead.

^buff(?: (\w+))?$

send("cast buff on "..(matches[2] or "myself"))

How to delete everything between two lines?

When deleteLine() is called, every following line shifts back in numerical position. Thus if we know where we're starting and how many lines to expect, we can use a for loop to gag everything between line a and b by leaving the cursor in one spot. In the below example, line_a_number is the number of the line you want to start at, and line_b_number is the ending line. To gag x number of lines instead, use line_a_number + x in place of line_b_number.

for i = line_a_number, line_b_number, 1
do
   moveCursor(0, line_a_number)
   selectCurrentLine()
   deleteLine()
end

How to capture foreground line color information?

Here's an example that loops through each character in a line of text and prints the character and its foreground color to a miniconsole if the color has changed from the previous character:

Trigger: ^ (regex)

Code:

miniconsoleContainer =
  miniconsoleContainer or Adjustable.Container:new({name = "miniconsoleContainer"})
myMiniconsole =
  Geyser.MiniConsole:new(
    {
      name = "myMiniconsole",
      x = 0,
      y = 0,
      autoWrap = true,
      color = "black",
      scrollBar = false,
      fontSize = 8,
      width = "100%",
      height = "100%",
    },
    miniconsoleContainer
  )

local index = 0
local line = getCurrentLine()
local linesize = #line
local currentlinenumber = getLineNumber()
local r, g, b = 0, 0, 0
local cr, cg, cb -- last seen colors
while index < linesize do
  index = index + 1
  moveCursor("main", index, currentlinenumber)
  selectString(line:sub(index), 1)
  r, g, b = getFgColor()
  if cr ~= r or cg ~= g or cb ~= b then
    cr, cg, cb = r, g, b
    myMiniconsole:echo(string.format("rgb(%d,%d,%d)%s", r, g, b, line:sub(index, index)))
  else
    myMiniconsole:echo(string.format("%s", line:sub(index, index)))
  end
  line:sub(index, index)
end
myMiniconsole:echo("\n")

How to enter a carriage return / enter command?

Say you'd like to gag the following line, and just continue ...

[ Press Enter to continue ]

Trigger: [ Press Enter to continue ]  (set to exact match)
Code: deleteLine()
      send("\n")

How to repeat commands with #?

Install the following alias, and with it #5 mycommand will get repeated five times.

How to move the command line over?

To move the command line over to the right, create a new script and add the following to it:

setCmdLineStyleSheet("main", [[
  QPlainTextEdit {
    padding-left: 100px; /* change 100 to your number */
    background-color: black; /* change it to your background color */
  }
]])

How to add a background for Mudlets buttons?

You can give Mudlets buttons a background to have them blend in with your UI by doing this:

-- replace the /home/vadi/Pictures/tile.png location below with the one of your picture!
-- you can download the sample tile.png from https://opengameart.org/content/bevouliin-free-game-background-for-game-developers
local backgroundpath = [[/home/vadi/Pictures/tile.png]]
-- Windows:
-- local backgroundpath = [[C:/Users/Vadim/Downloads/Free game background/transparent PNG/tile.png]]

setAppStyleSheet([[
QToolBar {
  border-image: url(]]..backgroundpath..[[);

}

QToolBar QToolButton:!hover {
  color: white;
}
QToolBar QToolButton:hover {
  color: black;
}
]])

Result:

Advanced scripting tips

Do stuff after all triggers/aliases/scripts are run

This little snippet will have your commands be executed right after, depending on the context you run it in, all triggers, aliases or scripts are completed:

tempTimer(0, [[mycode]])

How to delete the previous and current lines

This little snippet comes from Iocun:

moveCursor(0,getLineCount()-1)
deleteLine()
moveCursor(0,getLineCount())
deleteLine()

db: Mudlet's database frontend

The DB package is meant to provide easier access to a database, so you don’t have to know SQL or use the luasql module to set and get at your data. However, it does require that the luasql module be compiled and included in Mudlet to function.

Creating a Database

Before you can store anything in a database, you need to create one. You may have as many independent databases as you wish, with each having as many unique tables-- what we will call sheets in this package, so as to avoid confusion with Lua tables - think spreadsheets.

To create a database, you use the db:create() function, passing it the name of your database and a Lua table containing its schema configuration. A schema is a mold for your database - it defines what goes where. Using the spreadsheet example, this would mean that you’d define what goes into each column. A simple example:

db:create("people", {friends={"name", "city", "notes"}, enemies={"name", "city", "notes"}})

This will create a database which contains two sheets: one named friends, the other named enemies. Each has three columns, name, city and notes-- and the datatype of each are strings, though the types are very flexible and can be changed basically whenever you would like. It’ll be stored in a file named Database_people.db in your Mudlet config directory on the hard drive should you want to share it.

It’s okay to run this function repeatedly, or to place it at the top-level of a script so that it gets run each time the script is saved: the DB package will not wipe out or clear the existing data in this case.

Note: You may not create a column or field name which begins with an underscore. This is strictly reserved to the db package for special use.

Note: Adding new columns to an existing database did not work in Mudlet 2.1 - see db:create() on how to deal with this.

Adding Data

To add data to your database, you must first obtain a reference (variable) for it. You do that with the db:get_database function, such as:

  local mydb = db:get_database("people")

The database object contains certain convenience functions (discussed later, but all are preceded with an underscore), but also a reference to every sheet that currently exists within the database. You then use the db:add() function to add data to the specified sheet.

  db:add(mydb.friends, {name="Ixokai", city="Magnagora"})

If you would like to add multiple rows at once to the same table, you can do that by just passing in multiple tables:

  db:add(mydb.friends,
    {name="Ixokai", city="Magnagora"},
    {name="Vadi", city="New Celest"},
    {name="Heiko", city="Hallifax", notes="The Boss"}
  )

Notice that by default, all columns of every table are considered optional-- if you don’t include it in the add, then it will be set to its default value (which is nil by default)

For those familiar with databases: with the DB package, you don’t have to worry about committing or rolling back any changes, it will commit after each action automatically. If you would like more control than this, see Transactions below.

You also cannot control what is the primary key of any sheets managed with DB, nor do you have to create one. Each row will get a unique integer ID that automatically increments, and this field can be accessed as "_row_id".

Querying

Putting data in isn’t any fun if you can’t get it out. If you want every row from the sheet, you can do:

  db:fetch(mydb.friends)

But rarely is that actually useful; usually you want to get only select data. For example, you only want to get people from the city of Magnagora. To do that you need to specify what criteria the system should use to determine what to return to you. It looks like this:

  db:fetch(mydb.friends, db:eq(mydb.friends.city, "Magnagora"))

So the basic command is - db:fetch(_sheet_, _what to filter by_)

The following filter operations are defined:

  db:eq(field, value[, case_insensitive]) -- Defaults to case insensitive, pass true as the last arg to
              reverse this behavior.
  db:not_eq(field, value[, case_insensitive) -- Not Equal To
  db:lt(field, value) -- Less Than
  db:lte(field, value) -- Less Than or  Equal to.
  db:gt(field, value) -- Greater Than
  db:gte(field, value) -- Greater Than or Equal To
  db:is_nil(field) -- If the column is nil
  db:is_not_nil(field) -- If the column is not nil
  db:like(field, pattern) -- A simple matching pattern. An underscore matches any single character,
          and a percent(%) matches zero or more characters. Case insensitive.
  db:not_like(field, pattern) -- As above, except it'll give you everything but what you ask for.
  db:between(field, lower_bound, upper_bound) -- Tests if the field is between the given bounds (numbers only).
  db:not_between(field, lower_bound, upper_bound) -- As above, only... not.
  db:in_(field, table) -- Tests if the field is in the values of the table. NOTE the trailing underscore!
  db:not_in(field, table) -- Tests if the field is NOT in the values of the table *

The db:in_ operator takes a little more explanation. Given a table, it tests if any of the values in the table are in the sheet. For example:

  db:in_(mydb.friends.city, {"Magnagora", "New Celest"})

It tests if city == "Magnagora" OR city == "New Celest", but with a more concise syntax for longer lists of items.

There are also two logical operators:

  db:AND(operation1, ..., operationN)
  db:OR(operation1, operation2)

You may pass multiple operations to db:fetch in a table array, and they will be joined together with an AND by default. For example:

  db:fetch(mydb.friends,
    {db:eq(mydb.friends.city, "Magnagora"), db:like(mydb.friends.name, "X%")}
  )

This will return every record in the sheet which is in the city of Magnagora, and has a name that starts with an X. Again note that in LIKE patterns, a percent is zero or more characters — this is the same effect as "X.*" in pcre patterns. Similarly, an underscore matches any single characters and so is the same as a dot in pcre.

Passing multiple expressions in an array to db:fetch is just a convenience, as its exactly the same as:

  db:fetch(mydb.friends, db:AND(db:eq(mydb.friends.city, "Magnagora"), db:like(mydb.friends.name, "I%")))

The db:OR operation only takes two arguments, and will check to see if either of the two is true. You can nest these logical operators as deeply as you need to.

You can also just pass in a string directly to db:fetch, but you have to be very careful as this will be passed straight to the SQL layer. If you don’t know any SQL then you want to avoid this… for example, in SQL there’s a very big difference between double and single quotes. If you don’t know that, then stick to the db functions. But an example is:

  db:fetch(mydb.friends, "city == 'Magnagora'")

Now, the return value of db:fetch() is always a table array that contains a table dictionary representing the full contents of all matching rows in the sheet. These are standard Lua tables, and you can perform all normal Lua operations on them. For example, to find out how many total items are contained in your results, you can simply do #results. If a request from the friends sheet were to return one row that you stored in the results variable, it would look like this if passed into the display() function:

  table {
  1: table {
    'name': 'Bob',
    'city': 'Magnagora',
    'notes': 'Trademaster of Tailoring'
  }
}

And if you were to echo(#results), it would show 1.

The order of the returned rows from db:fetch is generally the same as the order in which you entered them into the database, but no actual guarantees are made to this. If you care about the order then you can pass one or two optional parameters after the query to db:fetch() to control this.

The first table is an array of fields that indicate the column names to sort by; the second is a flag to switch from the default ascending(smallest to largest) sort, to a descending(largest to smallest) sort. For example:

  db:fetch(mydb.friends, db:eq(mydb.friends.city, "Magnagora"), {mydb.friends.city})

This will return all your friends in Magnagora, sorted by their name, from smallest to largest. To reverse this, you would simply do:

  db:fetch(mydb.friends, db:eq(mydb.friends.city, "Magnagora"), {mydb.friends.city}, true)

Including more then one field in the array will indicate that in the case that two rows have the same value, the second field should be used to sort them.

If you would like to return ALL rows from a sheet, but still sort them, you can do that by passing nil into the query portion. For example:

  db:fetch(mydb.friends, nil, {mydb.friends.city, mydb.friends.name})

This will return every friend you have, sorted first by city and then their name.

Indexes and Types

The sheets we’ve defined thus far are very simple, but you can take more control over the process if you need to. For example, you may assign default values and types to columns, and the DB package will attempt to coerce them as appropriate. To do that, you change your db:create() call as:

db:create("people", {
  friends={"name", "city", "notes"},
  enemies={
    name="",
    city="",
    notes="",
    enemied="",
    kills=0
  }
})

This is almost the same as the original definition, but we’ve defined that our first four fields are strings with a default value of blank, and the new kills field which is an integer that starts off at 0. The only way to set a datatype is to set a default value at this time.

Please note, beneath the DB package is SQLite, and SQLite is very data-type neutral. It doesn’t really care very much if you break those rules and put an integer in a string field or vice-versa, but the DB package will — to a limited degree — attempt to convert as appropriate, especially for the operations that work on numbers.

You may also create both standard and unique indexes. A unique index enforces that a certain criteria can only happen once in the sheet. Now, before you go and make indexes, pause and consider. There is no right or wrong answer when it comes to what to index: it depends on what kind of queries you do regularly. If in doubt, don’t make an index. Indexes will speed up reading data from the sheet, but they will slow down writing data.

To add an index, pass either the _index or _unique keys in the table definition. An example:

db:create("people", {
  friends={"name", "city", "notes"},
  enemies={
    name="",
    city="",
    notes="",
    enemied="",
    kills=0,
    _index = { "city" },
    _unique = { "name" }
  }
})

Now, bear in mind: _index = { "name", "city"} creates two indexes in this sheet. One on the city field, one on the name field. But, _index = { {"name", "city"} } creates one index: on the combination of the two. Compound indexes help speed up queries which frequently scan two fields together, but don’t help if you scan one or the other.

The admonition against making indexes willy-nilly holds double for compound indexes: do it only if you really need to!

Uniqueness

As was specified, the _unique key can be used to create a unique index. This will make it so a table can only have one record which fulfills that index. If you use an index such as _unique = { "name" } then names must be unique in the sheet. You can specify more than one key to be unique; in that case they will be checked in an OR condition.

Now, if you use db:add() to insert a record which would violate the unique constraint, a hard error will be thrown which will stop your script. Sometimes that level of protection is too much, and in that case you can specify how the db layer handles violations.

There are three possible ways in which the layer can handle such violations; the default is to FAIL and error out.

You can also specify that the db layer should IGNORE any commands that would cause the unique constraint to be violated, or the new data should REPLACE the existing row.

For example:

db:add(mydb.enemies, {name="Bob", city="Sacramento"})
db:add(mydb.enemies, {name="Bob", city="San Francisco"})

With the name field being declared to be unique, these two commands can’t succeed normally. The first db:add() will create a record with the name of Bob, and the second would cause the uniqueness of the name field to be violated. With the default behavior (FAIL), the second db:add() call will raise an error and halt the script.

If you want the IGNORE behavior, the second command will not cause any errors and it will simply fail silently. Bob’s city will still be Sacramento.

With the REPLACE behavior, the second command will cause its data to completely overwrite and replace the first record. Bob’s city will now be San Francisco.

A word of caution with REPLACE, given:

db:add(mydb.enemies, {name="Bob", city="Sacramento", notes="This is something."})
db:add(mydb.enemies, {name="Bob", city="San Francisco"})

With the REPLACE behavior, the second record will overwrite the first-- but the second record does not have the notes field set. So Bob will now not have any notes. It doesn’t -just- replace existing fields with new ones, it replaces the entire record.

To specify which behavior the db layer should use, add a _violations key to the table definition:

db:create("people", {
  friends={"name", "city", "notes"},
  enemies={
    name="",
    city="",
    notes="",
    enemied="",
    kills=0,
    _index = { "city" },
    _unique = { "name" },
    _violations = "IGNORE"
  }
})

Note that the _violations behavior is sheet-specific.

Timestamps

In addition to strings and floats, the db module also has basic support for timestamps. In the database itself this is recorded as an integer (seconds since 1970) called an epoch, but you can easily convert them to strings for display, or even time tables to use with Lua’s built-in time support.

The most common use for the Timestamp type is where you want the database to automatically record the current time whenever you insert a new row into a sheet. The following example illustrates that:

local mydb = db:create("combat_log",
  {
    kills = {
      name = "",
      area = "",
      killed = db:Timestamp("CURRENT_TIMESTAMP"),
      _index = { {"name", "killed"} }
    }
  }
)

-- observe that we don't provide the killed field here - DB automatically fills it in for us.
db:add(mydb.kills, {name="Drow", area="Undervault"})

results = db:fetch(mydb.kills)
display(results)

The result of that final display would show you this on a newly created sheet:

table {
  1: table {
    '_row_id': 1
    'area': 'Undervault'
    'name': 'Drow'
    'killed': table {
      '_timestamp': 1264317670
    }
  }
}

As you can see from this output, the killed fields contains a timestamp-- and that timestamp is stored as an epoch value in the GMT timezone. For your convenience, the db.Timestamp type offers three functions to get the value of the timestamp in easy formats. They are as_string, as_number and as_table, and are called on the timestamp value itself.

The as_number function returns the epoch number, and the as_table function returns a time table. The as_string function returns a string representation of the timestamp, with a default format of "%m-%d-%Y %H:%M:%S". You can override this format to anything you would like. Details of what you can do with epoch values, time tables, and what format codes you can use are specified in the Lua manual at: http://www.lua.org/pil/22.1.html for the Lua date/time functions.

A quick example of the usage of these functions is:

results = db:fetch(mydb.kills)
for _, row in ipairs(results) do
  echo("You killed " .. row.name .. " at: " .. (row.killed and row.killed:as_string() or "no time") .."\n")
end

Deleting

The db:delete function is used to delete rows from the sheet. It takes two arguments, the first being the sheet you are deleting and the second a query string built using the same functions used to build db:fetch() queries.

For example, to delete all your enemies in the city of Magnagora, you would do:

db:delete(mydb.enemies, db:eq(mydb.enemies.city, "Magnagora"))

Be careful in writing these! You may inadvertantly wipe out huge chunks of your sheets if you don’t have the query parameters set just to what you need them to be. Its advised that you first run a db:fetch() with those parameters to test out the results they return.

As a convenience, you may also pass in a result table that was previously retrieved via db:fetch and it will delete only that record from the table. For example, the following will get all of the enemies in Magnagora, and then delete the first one:

results = db:fetch(mydb.enemies, db:eq(mydb.enemies.city, "Magnagora"))
db:delete(mydb.enemies, db:eq(mydb.enemies._row_id, results[1]._row_id))

That is equivalent to:

db:delete(mydb.enemies, results[1])

You can even pass a number directly to db:delete if you know what _row_id you want to purge.

A final note of caution: if you want to delete all the records in a sheet, you can do so by only passing in the table reference. To try to protect you from doing this inadvertently, you must also pass true as the query after:

db:delete(mydb.enemies, true)

Updating

If you make a change to a table that you have received via db:fetch(), you can save those changes back to the database by doing:

db:update(mydb.enemies, results[1])

A more powerful (and somewhat dangerous, be careful!) function to make changes to the database is db:set, which is capable of making sweeping changes to a column in every row of a sheet. Beware, if you have previously obtained a table from db:fetch, that table will NOT represent this change.

The db:set() function takes two arguments: the field to change, the value to set it to, and the db:fetch() like query to indicate which rows should be affected. If you pass true as the last argument, ALL rows will be changed.

To clear out the notes of all of our friends in Magnagora, we could do:

db:set(mydb.friends.notes, "", db:eq(mydb.friends.notes, "Magnagora"))

Be careful in writing these!

Transactions

As was specified earlier, by default the db module commits everything immediately whenever you make a change. For power-users, if you would like to control transactions yourself, the following functions are provided on your database instance:

local mydb = db:get_database("my_database")
mydb:_begin()
mydb:_commit()
mydb:_rollback()
mydb:_end()

Once you issue a mydb._begin() command, autocommit mode will be turned off and stay off until you do a mydb._end(). Thus, if you want to always use transactions explicitly, just put a mydb._begin() right after your db:create() and that database will always be in manual commit mode.

Viewing and editing the database contents

A good tool to view and edit the database contents in raw form is SQlite Sorcerer (free and available for Linux, Windows, Mac).

Debugging raw queries

If you'd like to see the queries that db: is running for you, you can enable debug mode with db.debug_sql = true.

Discord Messages

Can you send messages from Mudlet to Discord? Totally. Here is an example:

function sendToDiscord(data)
  local url = "https://discord.com/api/webhooks/1204151397977821184/Cu8ZQQo9R11AyIt3DxpOEeB8MtVMA6_AEfXoZaYxqEAOu_6hwhtA2cRLIw-VIs7py7p8"
  local headers = {["Content-Type"] = "application/json"}
  local json = yajl.to_string(data)
  postHTTP(json, url, headers)
end

local data = {
  content = "Hello, Discord!",
  embeds = {
    {
      title = "This is an embed",
      url = "https://example.com",
      image = {
        url = "https://example.com/image.jpg"
      }
    }
  }
}

sendToDiscord(data)

Sure enough, after starting this script, you can see a message in Discord:

What you just need to do is create a webhook in a channel. Go to channel settings, then create this:

Here you can find more documentation on which fields Discord allows: https://discord.com/developers/docs/resources/webhook#execute-webhook

All this is one way though. Mudlet won't listen to messages from Discord. For that you'd probably have to make a Discord bot first.

Discord Rich Presence

Discord Rich Presence in Mudlet allows you, the player, to show off the game you're playing and you, the game author, to get your game shown off! Advertise your game for free alongside AAA titles in server player lists :)

To respect the players privacy, this option is disabled by default - enable it by ticking the Discord option for the profile:

Once enabled, a Discord-capable game will show information in your Discord!

To fine-tune the information you'd like to see displayed, go to Settings, Chat tab:

Implementing

As a game author, you have two ways of adding Discord support to your game: via GMCP (easy) or via Lua.

Adding support via GMCP means that your players don't have to install any Lua scripts which is a nicer experience. To do so, implement the Discord over GMCP specification and get in touch to let us know your game implements GMCP.

GMCP

Here's a quick cheatsheet to implement the GMCP spec:

1. Create a discord application
2. Upload game logo for "rich presence invite image"
3. Upload same game logo in "Rich Presence Assets" with the name of server-icon
4. Upon receiving "External.Discord.Hello" from the game client, reply with "External.Discord.Info" with applicationid (see screenshot) and "External.Discord.Status"
5. Send "External.Discord.Status" whenever you need to send data to the client, and fill it with the values have changed since the last status. Discord has some ideas for filling it in.
6. Done. Mudlet will enable the Discord checkbox upon receiving the applicationid from the game at least once.

Lua

An alternative way to add Discord support as a game author is via Lua - all of Discords functionality can be manipulated from it. Create a discord application and set it with setDiscordApplicationID(), then set the set the rest of the options as necessary:

Credit: Discord

If you're a game player and your game doesn't support Discord, you can still use the functionality to set the detail, status, party and time information as desired.

Available in Mudlet3.14+

MUD Client Media Protocol

Client.Media

Want to add accessibility and excitement into your game? How about implementing sound and music via GMCP?

The Client.Media family of GMCP packages provide a way for games to send sound and music events. GMCP media events are sent in one direction: from game server to to game client.

Client.Media in Mudlet

Media files may be downloaded manually or automatically if certain conditions are met.

Available in Mudlet4.4+

Mudlet accepts case-insensitive GMCP for the Client.Media namespace (for example, these are all acceptable: "Client.Media.Play", "client.media.play", "cLiEnT.MeDiA.Play").

Enabling Media

When a new profile opens, Mudlet adds to the Core.Supports.Set GMCP package "Client.Media 1" to signal to servers that it supports processing media files via GMCP:

Core.Supports.Set ["Client.Media 1", ...]

To process Client.Media GMCP data in Mudlet, these boxes in the Settings window of Mudlet must be checked:

1. The "Enable GMCP" box in the Miscellaneous section.
2. The "Allow server to download and play media" box in the Game protocols section.

These boxes are checked by default upon the start of a new profile in Mudlet.

Storing Media

Mudlet plays files cached in the "media" folder within a game's profile. To get files into the "media" folder you could perform either of these options:

1. Copy media files or extract them from an archive (zip)
2. Automatically download them from external resources such as your game's web server on the Internet.

To enable the second option (Internet), use the "url" parameter made available in the "Client.Media.Default", "Client.Media.Load" and "Client.Media.Play" GMCP packages described below.

Loading Media

Send a Client.Media.Default GMCP event to setup the default URL directory to load sound or music files from external resources. This would typically be done once upon player login.

Required	Key	Value	Purpose
Yes	"url"	<url>	Resource location where the media file may be downloaded.

For example, to setup the default URL directory for your game:

Client.Media.Default {
  "url": "https://www.example.com/sounds/"
}

If downloading from external resources, it is recommended to use Client.Media.Default, set this default URL directory once, and let Mudlet download all of your media files automatically from this one resource location. Otherwise, explicitly set the "url" parameter on all of your Client.Media.Load GMCP and Client.Media.Play GMCP events to ensure that files are downloaded from the intended location(s).

Send Client.Media.Load GMCP events to load sound or music files. This could be done when the player logs into your game or at the beginning of a zone that will need the media.

Required	Key	Value	Purpose
Yes	"name"	<file name>	Name of the media file. May contain directory information (i.e. weather/lightning.wav).
Maybe	"url"	<url>	Resource location where the media file may be downloaded. Only required if a url was not set above with Client.Media.Default.

For example, download the sound of a sword swooshing within the "media" folder:

Client.Media.Load {
  "name": "sword1.wav",
  "url": "https://www.example.com/sounds/"
}

Playing Media

Send Client.Media.Play GMCP events to play sound or music files.

Required	Key	Value	Default	Purpose
Yes	"name"	<file name>		Name of the media file. May contain directory information (i.e. weather/lightning.wav). Wildcards * and ? may be used within the name to randomize media files selection.
Maybe	"url"	<url>		Resource location where the media file may be downloaded. Only required if the file is to be downloaded remotely and a url was not set above with Client.Media.Default or Client.Media.Load.
No	"type"	"sound" or "music"	"sound"	Identifies the type of media.
No	"tag"	<tag>		Helps categorize media.
No	"volume"	1 to 100	50	Relative to the volume set on the player's client.
No	"fadein"	<msec>		Volume increases, or fades in, ranged across a linear pattern from one to the volume set with the "volume" key. Start position: Start of media. End position: Start of media plus the number of milliseconds (msec) specified. 1000 milliseconds = 1 second.
No	"fadeout"	<msec>		Volume decreases, or fades out, ranged across a linear pattern from the volume set with the "volume" key to one. Start position: End of the media minus the number of milliseconds (msec) specified. End position: End of the media. 1000 milliseconds = 1 second.
No	"start"	<msec>	0	Begin play at the specified position in milliseconds. 1000 milliseconds = 1 second.
No	"loops"	-1, or >= 1	1	Number of iterations that the media plays. A value of -1 allows the sound or music to loop indefinitely.
No	"priority"	1 to 100		Halts the play of current or future played media files with a lower priority while this media plays.
No	"continue"	true or false	true	Only valid for media files with a "type" of "music". Continues playing matching new music files when true. Restarts matching new music files when false.
No	"key"	<key>		Uniquely identifies media files with a "key" that is bound to their "name" or "url". Halts the play of current media files with the same "key" that have a different "name" or "url" while this media plays.

name

For example, to simply play the sound of a cow mooing already stored in the "media" folder:

Client.Media.Play {
  "name": "cow.wav"
}

Or some lightning stored in a "weather" sub-folder under the "media" folder.

Client.Media.Play {
  "name": "weather/lightning.wav"
}

The "name" parameter may be used for stopping media with the Client.Media.Stop GMCP event.

url

If you maintain your sound files on the Internet and don't set a default URL with Client.Media.Default, or preload them with Client.Media.Load, include the "url" parameter:

Client.Media.Play {
  "name": "cow.wav",
  "url": "https://www.example.com/sounds/"
}

type: sound

Media files default to a "type" of "sound" when the "type" parameter is not specified, such as in the example above. It is good practice to specify the "type" parameter to best keep media organized within your implementation:

Client.Media.Play {
  "name": "cow.wav",
  "type": "sound"
}

The "type" parameter may be used for stopping matching media with the Client.Media.Stop GMCP event.

tag

To play the sound of a sword swooshing and categorized as "combat":

Client.Media.Play {
  "name": "sword1.wav",
  "type": "sound",
  "tag": "combat"
}

The "tag" parameter may be used for stopping matching media with the Client.Media.Stop GMCP event.

type: music

Add background music to your environment through use of the "music" value set upon the "type" parameter:

Client.Media.Play {
  "name": "river.wav",
  "type": "music",
  "tag": "environment"
}

The "type" parameter may be used for stopping matching media with the Client.Media.Stop GMCP event.

volume: 1 to 100

As the character draws nearer to or farther from the environmental feature, consider adjusting the "volume" parameter. Example values, followed by syntax examples:

• Maximum: 100 (recommended to use rarely)
• High: 75
• Default: 50
• Low: 25
• Minimum: 1 (recommended to use rarely)

Client.Media.Play {
  "name": "river.wav",
  "type": "music",
  "tag": "environment",
  "volume": 75
}

Although using the integer type is recommended, Mudlet parses "volume" values of type string ("75") into integers (75) as needed.

fadein

Increase volume from the start of the media [start position, volume one] to the number in milliseconds specified with the "fadein" parameter [position start + milliseconds, volume specified with the "volume" parameter]. Example values, followed by syntax examples:

• 1000 milliseconds (1 second)
• 60000 milliseconds (1 minute)
• 0 milliseconds (no fade in)

Client.Media.Play {
  "name": "monty_python.mp3",
  "type": "music",
  "volume": 100,
  "fadein": 1000
}

        +---------------------------+-----------------------+
        | Fade in 1000 milliseconds |         Normal        |
        +---------------------------+-----------------------+
Volume 1|........::::::::::iiiiiiiii%%%%%%%%%%%%%%%%%%%%%%%%|Volume 100
        +---------------------------+-----------------------+

Although using the integer type is recommended, Mudlet parses "fadein" values of type string ("1000") into integers (1000) as needed.

fadeout

Decrease volume from a position in milliseconds subtracted from the duration of the media [position duration - milliseconds, volume specified with the "volume" parameter] to the end of the media [position duration, volume one]. Example values, followed by syntax examples:

• 1000 milliseconds (1 second)
• 60000 milliseconds (1 minute)
• 0 milliseconds (no fade out)

Client.Media.Play {
  "name": "the_matrix.mp3",
  "type": "music",
  "volume": 50,
  "fadeout": 333
}

         +-----------------------+---------------------------+
         |        Normal         | Fade out 333 milliseconds |
         +-----------------------+---------------------------+
Volume 50|%%%%%%%%%%%%%%%%%%%%%%%%iiiiiiiii::::::::::........|Volume 1
         +-----------------------+---------------------------+

Although using the integer type is recommended, Mudlet parses "fadeout" values of type string ("333") into integers (333) as needed.

start

Start playing a media track at the number of milliseconds specified. Example values, followed by syntax examples:

• 1000 milliseconds (1 second)
• 60000 milliseconds (1 minute)
• 0 milliseconds (start from beginning)

Client.Media.Play {
  "name": "mudlet_beatboxing.mp3",
  "type": "music",
  "volume": 75,
  "start": 1000
}

Although using the integer type is recommended, Mudlet parses "start" values of type string ("100") into integers (100) as needed.

loops: -1, 1 or more

The "loops" parameter controls how many times the sound repeats and defaults to 1 if not specified. A value of -1 will loop the file indefinitely.

Client.Media.Play {
  "name": "clock/hour_bell.wav",
  "type": "sound",
  "loops": 3
}

Client.Media.Play {
  "name": "underdark.mp3",
  "type": "music",
  "tag": "environment",
  "loops": -1
}

Although using the integer type is recommended, Mudlet parses "loops" values of type string ("-1") into integers (-1) as needed.

priority: 1 to 100

The "priority" parameter sets precedence for Client.Media.Play GMCP events that include a "priority" setting. The values for the "priority" parameter range between 1 and 100. Given that two Client.Media.Play GMCP events have the same priority, the media already playing will continue playing. In Mudlet, media without priority set is not included comparisons based on priority.

A common place to find priority implemented is with combat. In the following example, imagine a combat scenario where some sounds of sword thrusts were interrupted by a successful blocking maneuver.

Client.Media.Play {
  "name": "sword1.wav",
  "type": "sound",
  "tag": "combat",
  "loops": 3,
  "priority": 60
}

Client.Media.Play {
  "name": "block1.wav",
  "type": "sound",
  "tag": "combat",
  "priority": 70
}

Although using the integer type is recommended, Mudlet parses "priority" values of type string ("25") into integers (25) as needed.

The "priority" parameter may be used for stopping matching media with the Client.Media.Stop GMCP event.

continue: true or false (for music)

Typically sent with the "type" of "music" is the parameter "continue", which presents the following values:

• true: continues music that is already playing if it is requested again through a new Client.Media.Play GMCP event
• false: restarts music that is already playing if it is requested again through a new Client.Media.Play GMCP event

Client.Media.Play {
  "name": "city.mp3",
  "type": "music",
  "tag": "environment",
  "continue": true
}

If the "continue" parameter is not specified, behavior will default to true for music.

Although using the boolean type is recommended, Mudlet parses "continue" values of type string ("true" and "false") into boolean (true and false) as needed, as not all game drivers support a boolean type.

key

The "key" parameter enables media categorization, similar to the "tag" parameter, however it adds a feature of uniqueness that halts media currently playing with the same key, replacing it with the media that arrived from a new Client.Media.Play GMCP event. This update will only occur if the "name" or "url" associated with the currently playing media does not match the new media, while the key is identical.

In the example below, consider that a player moves from a sewer area to a village. The "key" parameter is used to stop the previously playing sewer.mp3 and start playing village.mp3 within the second Client.Media.Play GMCP event.

Client.Media.Play {
  "name": "sewer.mp3",
  "type": "music",
  "tag": "environment",
  "loops": -1,
  "continue": true,
  "key": "area-music"
}

Client.Media.Play {
  "name": "village.mp3",
  "type": "music",
  "tag": "environment",
  "loops": -1,
  "continue": true,
  "key": "area-music"
}

The "key" parameter may be used for stopping matching media with the Client.Media.Stop GMCP event.

Note: Where music is bound to change, continue or stop as a player enters a new room, consider allowing for a slight pause of 1 heart beat or tick to send the Client.Media.Play or Client.Media.Stop GMCP events. This practice reduces the number of Client.Media.Play GMCP events sent when the player travels through several rooms quickly.

randomization

Wildcards * (asterisk) and ? (question mark) may be used within the name to randomize media file(s) selection.

Given that media files underdark.wav, underdark.mp3 and underdark_dark_elven_moshpit.mp3 were all present in the media/environment directory under the current game profile, the following Client.Media.Play GMCP event would randomly choose one of those files to play using the * wildcard.

Client.Media.Play {
  "name": "underdark*",
  "type": "music",
  "tag": "environment",
  "loops": -1,
  "continue": false
}

If media files sword1.wav, sword2.wav and sword3.wav were all present in the media/combat directory under the current game profile, the following Client.Media.Play GMCP event would randomly choose one of those files to play per each loop using the ? wildcard.

Client.Media.Play {
  "name": "combat/sword?.wav",
  "type": "sound",
  "tag": "combat",
  "loops": 3
}

Stopping Media

Send Client.Media.Stop GMCP events to stop sound or music media.

Required	Key	Value	Purpose
No	"name"	<file name>	Stops playing media by name matching the value specified.
No	"type"	"sound" or "music"	Stops playing media by type matching the value specified.
No	"tag"	<tag>	Stops playing media by tag matching the value specified.
No	"priority"	1 to 100	Stops playing media with priority less than or equal to the value.
No	"key"	<key>	Stops playing media by key matching the value specified.

all

Send the Client.Media.Stop GMCP event with no parameters to stop all playing media within a given game profile.

Client.Media.Stop {}

parameters

Send any combination of the name, type, tag, priority or sound parameters and valid corresponding values to stop playing media that matches all combinations of the parameters.

Stop the rain.

Client.Media.Stop {
  "name": "rain.wav"
}

Stop all media using the "type" of "sound".

Client.Media.Stop {
  "type": "sound"
}

Stop all media categorized with the "tag" of "combat" and that has a "priority" less than or equal to 50.

Client.Media.Stop {
  "tag": "combat",
  "priority": 50
}

Stop all media categorized with the "key" of "area-music".

Client.Media.Stop {
  "key": "area-music"
}

GUI Scripting in Mudlet

Mudlet has extremely powerful GUI capabilities built into it, and with the inclusion of the Geyser and Vyzors layout managers in Mudlet's Lua API it is quicker and easier to get a basic UI created.

Geyser

Geyser is an object oriented framework for creating, updating and organizing GUI elements within Mudlet - it allows you to make your UI easier on Mudlet, and makes it easier for the UI to be compatible with different screen sizes.

Geyser's manual is quite extensive - follow here to read up on it.

UI template

Akaya has created a UI template based on Geyser that can serve as a quick start for customizing the Mudlet interface to your character:

To get started with it, see the forum thread about Geyser UI Template.

Simple Window Manager

Simple Window Manager is a light-weight script designed to provide the GUI object placement and sizing functionality seen in Geyser and Vyzor without any of the extras. Any GUI object, once created normally, can be added to the SWM along with a corner to base its positioning info off of, the distance from that corner, and the size of the object in any combination of pixels and percentages of the screen. SWM does all the behind the scenes work to keep all objects it has been given to manage in their correct places and sizes as the screen changes size. All other interactions with GUI objects are handled using standard functions built into Mudlet.

Simple Window Managers manual, and download, can be found here.

Useful Resources

There are several useful resources you can refer to when creating your GUI.

Wiki Resources

• Geyser Tutorial:

Excellent for getting an initial feel of how to use the Geyser layout manager.

• GUI API:

The GUI section of the Lua API manual

External Resources

• Geyser subforum:

The Geyser Layout Manager subforum on Mudlet's forums.

• GUI Screenshots:

A pinned thread on Mudlet's forums for showing what your GUI looks like. Useful for ideas and to see what is possible.

• Godwars II Mudlet UI:

A forum thread which follows the evolution of the UI provided by God Wars II

Resetting your UI

While scripting your UI, you can reset it completely and have your scripts be loaded from scratch with the resetProfile() function - in the input line, type lua resetProfile().