Manual:Introduction

Automation and MUD Rules

Effectively speaking, it is possible to create an AI (Artificial Intelligence) that does everything you can do in a MUD. Even more so, the program will be able outperform you in almost every routine operation. The difficulty of creating such a program depends on the task it has to perform: gathering loot being very easy, walking through a dungeon and leveling you character being moderately easy and socially interacting with other real people being outrageously difficult (see A.L.I.C.E.). At the end of the day, you’re teaching your client to process information and act the way you consider best suited. Because scripting is so powerful, it can give you a competitive advantage that some people consider unfair or even cheating. As of the moment of this writing (2 November 2008), this sort of automation can be best observed in commercial massively-multiplayer online role-playing games (MMORPG), known as gold-farming or power-leveling. The basic idea is creating a system that will raise your character to the maximum level and gather in-game currency in the process, both of which can be effectively exchanged for real-world currency. The spread of the above aspects can have much more far reaching consequences than just being unfair, such as inflation, loss of balance in terms of game-mechanics or, ultimately, a complete crash of in-game economy. For more information see the paper "Simple Economics of Real-Money Trading in Online Games" by Jun-Sok Huhh of the Seoul National University. For these and various other reasons the administrators and owners of the corresponding virtual worlds can forbid the usage of automation tools. A failure to comply can result in suspension or deletion of the user’s character or account for future denial of service. By including scripting support in Mudlet, we effectively give you the ability to create and utilize AI toolkits, however, we do not endorse or promote the usage of these systems if it’s prohibited in your MUD. Keep in mind that by cheating you can lessen the quality of gameplay for both your fellow players and yourself.

Mudlet's Automation Features

Mudlet offers a vast array of standard features to automate or otherwise improve your gaming experience. These include, but are not limited to:

Aliases

User-defined text input, which is converted into a different, usually longer input before being sent to the MUD.

e.g. <lua>gg</lua> sends the full command to the MUD <lua>get gold from ground;put gold in bag</lua>

Keybindings

also known as hotkeys, allow executing certain user-defined commands by simultaneously pressing a specific combination of keys

e.g. <lua>CTRL+H</lua> might send "say Hello Miyuki!" to the MUD or play La Marseillaise

Triggers

execute user-defined commands upon receiving specific out from the MUD,

e.g. MUD sends: "You see Elyssa standing here." and Mudlet automatically sends "poke Elyssa" to the MUD.

Timers

delay the execution of a command or execute it after a specified period of time.

e.g. throw gauntlet to Eric-wait 3 seconds-exclaim Let us end this here!

Variables

allow the user to store text or numbers for easier use inside scripts.

Events

allow the user to make triggers for specific events like when Mudlet has connected to the MUD, or even user-defined events to use in complex system making.

Variables

Variables are containers for data. In Lua, they can store numbers or words. You can use variables to store important information like how much gold do you have, or have them remember things for you.

The syntax for making a variable remember a number is the following: <lua>variable = 1234</lua>

Or to make it remember some text: <lua>my_name = "Bob"</lua>

You can also do basic maths easily, for example:

To concatenate strings together, you can use the .. expression: <lua>my_full_name = "Bob" .. " the Builder"</lua>

Don't forget to use a space when you're contatenating two variables together: <lua> firstname = "Apple" lastname = "Red"

-- bad: will produce "AppleRed" full_name = firstname .. lastname

-- good: will produce "Apple Red" full_name = firstname .. " " .. lastname </lua>

Sending Commands to the MUD

To send a command to the MUD, you can use the send() function. Data inside the quotes is sent to the MUD.

For example, the following code sends the command to eat bread: <lua>send("eat bread")</lua>

If you’d like to include variables in the send command, you need to prefix and suffix them with two dots outside the quotes, like this: <lua>send("My name is " .. full_name .. ". What's yours?")</lua>

Echoing Text

To echo (show text to yourself) you can use the echo() or the insertText() function. For example, the following code will display "Time to eat dinner!" on your screen: <lua>echo("Time to eat dinner!")</lua>

If you’d like to include variables in your echo, you concatenate the value of your variable to the text: <lua> my_gold = 5 echo("I have " .. my_gold .. " pieces of gold!") </lua>

If you'd like to include a new line in your text, insert \n for it:

<lua> echo("this echo\nis on\nthree lines!")

-- comes out at: this echo is on three lines! </lua>

Aliases

Aliases are the most basic way of automating the gameplay - you can use aliases to shorten the amount of typing you do.

Example - Brew’o'Matic 6000

You’re walking around the epic dungeon of the Unholy Firedragon of Westersand, gathering roots in order to brew a potion and thus restore the growth of hair on Farmer Benedict’s bald head. Once you see a root, you need to:

<lua> open the bag of tools

get the sickle of damnation from the bag of tools

cut the root of hair-growth

clean the sickle of damnation of deadly root acid

put the sickle of damnation in the bag of tools

close the bag of tools

open the magical bag of storing

take the root

put the root into the magical bag of storing

close the magical of storing </lua>

And once you’re done, do the exact same thing nine more times… thrice a day!

Alternatively, you just create an alias that would do this all with a single command - for example, "quest".

Making a Simple Alias

To get started, go click on the Aliases button in Mudlet, and then on the Add one. This will make a blank alias for you, which we’ll now fill in.

The Alias name field is optional - it’s mainly used for the alias listing that you see on the left as an easy way to distinguish all of the aliases. You can just name our alias "test" for now. The Pattern field is where you put your regex pattern to describe the command you'll enter to make your new alias spring into action. Let’s say we want our new alias to send the command "say hello" whenever we type "sh". The regex pattern would be ^sh$. Then we put say hello into the Substitution field. After you have saved and activated your new alias "test", whenever you type "sh" Mudlet will not send "sh", but "say hello" instead. We call this substitution process alias expansion.

Mudlet uses Perl regular expression aliases. Regexes are a special way of matching patterns of words. For the beginners it is enough to think of them as a general way to specify the words itself and their placement within the line. For basic aliases it is enough to know that the character ^ symbolizes the beginning of the line and the character $ symbolizes the end of the line. If you want to make an alias "tw" that sends the command "take weapon", you don’t have to care about placement or pattern matching in general. All you need to do is fill ^tw$ in the field called "Regex" and type take weapon in the field called "substitution". Then you need to save the new alias by clicking on the "Save" icon in the top middle. The symbol for unsaved items disappears and makes way for a little blue checkbox. If this box is checked the alias is active. If the blue box is empty, the alias is deactivated and will not work unless you press the "activate" toggle padlock icon. Now you are ready to go. Type "tw" in the command line and press the enter key. Mudlet will send "take weapon" to the MUD. Aliases are basically a feature to save you a bit of typing (much like buttons which will be described in detail in a later section of the manual). More advance alias usage will be described later in the manual.

Triggers

Triggers are an automation feature offered in all MUD clients. They help you respond quicker a particular situation and generally make things more convenient for you since you need to do less manual work as your triggers will do the hard work for you often times. This helps you concentrate more on the important aspects of the game and lessen stress. The way a trigger works is simple: You define some text that you want to trigger some action. This is called the trigger pattern. When the trigger "sees" this text in the MUD output, it’ll run the commands you’ve told it to. Example: Whenever you see a bunny, you want to attack it (meanie!). You type "bunny" in the data field titled "add to list" and then either press the enter key or click on the little + icon next to the input line to add this word to the list of texts this trigger fires on. Now you type "kill bunny" in the field called "send plain text". Then click on the save icon to save the trigger and activate your new trigger (= blue checkbox icon in front of the trigger name in the trigger tree on the right side is checked). When the trigger is active each time the word "bunny" will appear in the MUD output, your trigger will issue the command "kill bunny" automatically as long as it is active. When you want to stop hunting bunnies, you can simply select the bunny trigger and then click on the padlock icon to deactivate the trigger. The trigger will stop firing until you re-enable it again via the padlock icon. If you lock a group of triggers or an entire trigger branch, all triggers in this branch will be locked until you remove the lock again. The locking starts from the root of the tree down to the end. As soon as a lock is met the trigger engine will skip the locked branch. Locking and unlocking branches is one of the most common actions you have to take care of when playing. You turn on your defensive triggers when engaging into a battle and you turn them off afterwards, or you turn on your harvesting triggers only when you are going to harvest.

Beginners should use Mudlet's automated highlight triggers in the beginning to highlight the text that has been triggered on to get the hang of the different trigger and pattern types. Click on the "highlight trigger" option and pick a foreground and a background color that you like to highlight your trigger with. When the trigger matches it automatically highlights its pattern. This is the most used form of triggers in mudding as it is a quick way of highlighting words that are important to you at the moment. You don’t have to know anything about scripting, regular expressions etc. to use highlight triggers. Just type in the word you like to be highlighted, select appropriate colors, save the new trigger and activate it.

Matching one unknown

You can also set up a trigger to gather the scimitars, gold or whatever the skeletons could carry around with them. Since we do not know what the loot is, we will need to set up a trigger to match the line and take whatever was dropped. Examples:

The skeleton drops ring. The skeleton drops gold. The skeleton drops scimitar.

The skeleton drops_ is the generic segment of the line, the loot itself varies. Thus, we need to tell the client to take_ whatever the skeleton dropped. We do this by setting up a so-called regular expression:

Perl Style Regular Expression: <lua>^The skeleton drops (.*)\.$</lua>

Script: <lua>send("take " .. matches[2])</lua>

The expression (.*) matches any characters that the client receives between The skeleton drops_ (NB: notice the blank at the end) and the full-stop. matches[2] simply transfers the first matched text fitting the search criteria into the output (matches[1] contains the entire matched text, matches[2] contains the first capture group. More on this in section two of the manual).

Matching multiple unknowns

Now, let’s try making a trigger that would gather the loot from anybody:

Perl Style Regular Expression: ^(.*) drops (.*)\.$

Script: <lua>send("take " .. matches[3])</lua>

In this case, any time somebody, or something, drops something else, or someone else, the client will pick it up. Note that we used matches[3] instead of matches[2] this time, in order to pick up the second match. If we used matches[2], we’d end up picking up the skeleton’s corpse.

Matching known variants

If you’re playing a MUD in English, you’ll notice that these triggers probably won’t work due to English syntax. Compare:

 The skeleton drops apple.
 The skeleton drops an apple.

Chances are that you’ll see the later a little more often. If we used our old RegEx, the output would look something like this.

 INPUT: The skeleton drops an apple.
 OUTPUT: take an apple

Most MUDs can’t handle determiners, such as articles (i.e. a, an, the) or quantifiers (e.g. five, some, each), in user-input. To match this line we could either create multiple triggers matching every possible article or a regular expression filtering out these words:

Perl Style Regular Expression: (.*) drops (a|an|the|some|a couple of|a few|) (.*)\.$

Script: <lua>send("take " .. matches[4])</lua>

Once again, note that we’re using the third match (matches[4]) this time.

Note: Certain other languages, with a morphology richer than that of English, might require a somewhat different approach. If you’re stuck, and your MUD-administrators don’t prohibit the use of triggers, try asking on the corresponding world’s forums.

For more information, see the chapter Regular Expressions.

Basic Regex Characters

Retrieving wildcards from triggers

Wildcards from triggers are stored in the matches[] table. The first wildcard goes into matches[2], second into matches[3], and so on, for however many wildcards do you have in your trigger.

For example, you’d like to say out loud how much gold did you pick up from a slain monster. The message that you get when you pick up the gold is the following:

You pick up 16 gold.

A trigger that matches this pattern could be the following:

Perl Style Regular Expression: ^You pick up (\d+) gold\.$

And in your code, the variables matches[2] will contain the amount of gold you picked up (in this case, 16). So now to say out loud how much gold did you loot, you can do the following:

Script: <lua>echo("I got " .. matches[2] .. " gold!")</lua> More advanced example Here’s an example by Heiko, which makes you talk like Yoda:

Perl Style Regular Expression: ^say (\w+) *(\w*) .*?(.*) Script: <lua>send( "say "..matches[4].." "..matches[2].." "..matches[3] )</lua>

What it does here is save the first word, the second word and then the rest of the text into wildcards. It then says rest of the text first, then the first word and then the second word.

Highlighting Words

To highlight something in the MUD output, make a trigger and use the "highlight trigger" option to highlight the matched trigger pattern.

Optionally, you can also make use of the bg() and fg() functions in scripting to highlight.

Keybindings

Keybindings, or hotkeys, are in many respects very similar to aliases, however, instead of typing in what you want to be done, you simply hit a key (or combination of keys) and let the Mudlet do the work.

Example - You don’t drink tea, you sip it! You’re participating in an in-game tea sipping contest. The winner is the first person to sip an Earl Grey, should the quiz-master make a vague reference to a series of tubes, or a Ceylon Mint, if he begins talking about the specific theory of relativity. In order to give us a competitive advantage, we will define two keybindings:

HOTKEY: F1 command on button down: sip earl gray

HOTKEY: F2 command on button down: sip ceylon mint Now you just have to listen, or rather read, carefully and hit either F1 or F2 to claim that prize.

Another practical use for keybindings would be creating a so-called "targeting system", which is especially useful for grinding down armies of pumpkin-men in MUDs without auto-attack. See the Variables chapter for further details.

Instructions on how to make a keybinding can be found here: Keybindings

Timers

Timers, as the name suggests, can be used to execute a specific command at a certain time, after a certain time or once every so often.

Example - Don’t miss the training!

Your character can train in his attributes once every three hours. You could either try tracking this manually or add a trigger starting timer after each training. Once the three hours have passed, your character will conveniently say to himself that it is time to do a couple of push-ups.

To create a Timer, enter the interval you'd like it to go off at - the format of the boxes is hour, minutes, seconds, milliseconds. For a 3-hour timer, put 3 into the first box.

Then either put in the exact command in the Command box, or the script you'd like it to do in the big script box. Make sure you enable the timer, and then you're set!

Offset timers

Mudlet's timers also feature an offset feature: an offset timer is a timer that goes off x seconds after it's parent went off. To create one, just drag one timer into another - and it'll be going off after the main one. For example - if the parent timer is on a 5 second interval, and you make the offset timer be on a 1 second interval, the child will be going off 1 second after the parent does.

See also: Mudlet Technical Manual