Difference between revisions of "Manual:Alias Engine"

From Mudlet
Jump to navigation Jump to search
(added category "Mudlet Manual")
(→‎Considerations: noting that named capture groups are unsupported, explaining how to use modifiers for alias regexes.)
 
(27 intermediate revisions by 8 users not shown)
Line 1: Line 1:
The aliases are the most basic way of automating the gameplay - you can use aliases to shorten the amount of typing you do. For example:
+
{{TOC right}}
 +
{{#description2:Manual on aliases, which react on user input, literally or with regex patterns, simply replacing text or starting more complex functions.}}
 +
=React on input - Mudlets Alias Engine=
 +
{{note}} A screencast is available on getting started with aliases - [http://www.youtube.com/view_play_list?p=15A249142399F3CB&playnext=1&playnext_from=PL watch it]!
  
- Brew’o'Matic 6000
+
Mudlet has a feature called "aliases" that allows you to set up certain phrases or commands that will automatically trigger certain actions or responses. These actions are defined using a specific type of language called "Perl regex expressions." Aliases only work on the input that the user types into the command line, while a separate feature called "triggers" works on the output that the game sends back. When you type a command and press enter, it is sent to the alias feature to see if it matches any of the phrases or commands that have been set up. If it does match, the alias will take over and either send a different command to the game or run a script (a set of instructions) that you have defined. This system is powerful because it gives you control over what happens when a certain phrase or command is entered. You can even change the user's input as it is being processed, allowing you to manipulate the command before it is sent to the game.
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:
 
  
: open the bag of tools
+
[[File:alias-diagram.png|600px]]
: 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
 
: and once you’re done, do the exact same thing nine more times… trice a day.
 
  
Alternatively, you just create an alias that would do this all with a single command - for example, quest.
+
The example in the diagram above shows 2 matching aliases, but only one of them sends commands to the game - and only if the player is healthy enough to attack the opponent. The other alias that matched the user input (enemy) choses a fitting opponent and sets the variable enemy accordingly, otherwise it issues a warning that attacking one of the available enemies would be too dangerous.
  
 +
For an alias to match the command text the same rules as explained above in the trigger section apply. However, to simplify matters there is only one alias type. As alias are not performance critical we could reduce the amount of trigger types to just Perl regex as this type can do it all and performance is no issue with alias as the amount of data is much less. Even if you type like a madman you’ll never get close to sending the same amount of text to the game than the amount of text the game sends back to you.
  
==1.8 Making a simple alias==
+
What does it mean that a regex is true or "matched"? A trigger or an alias fires - or executes its commands/script - when the text matches the pattern of the trigger or alias. In most cases this means that the text contains the trigger/alias pattern. If the regex pattern is <code>reen</code> then a text "The green house" will match because "reen" is contained in the text. More complex regex patterns can also hold information on where in the text a certain pattern must occur in order to match. <code>^tj</code> only matches when the letters "tj" occur at the beginning of the text. Consequently, a text like "go tj" would not match. Regex patterns can also capture data like numbers, sequences of letters, words etc. at certain positions in the text. This is very useful for game related scripting and this is why it is explained below.
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.
+
 
 +
Let’s get back to alias. We start with a simple example.
 +
 
 +
We want Mudlet to send "put weapon in bag" whenever we type "pwb". Consequently, the pattern is <code>pwb</code> and as the task is so simple it’s enough to enter "put weapon in bag" in the send field. Then we click on save to save the changes and activate the alias by clicking on the padlock icon. Then we leave the trigger editor and test our new alias. After typing "pwb" and pressing return Mudlet will send the command "put weapon in bag" to the game.
 +
 
 +
Let’s move on to a more complicated example that is needed very often.
 +
 
 +
We want our script to automatically put the weapon in the correct bag as we have many bags and many weapons. The pattern stays the same. ^pwb The ^ at the beginning of the line means that the command starts with pwd and no other letter in front of this. If we define our pattern more clearly, the pattern will match less often. Without the ^ the alias will match and the alias script will always be run whenever there is the sequence of letters "pwb" in your commands. This may not always be what you want. This is why it’s usually a good idea to make the pattern definition as exact as needed by being less general. The more general the pattern, the more often it will match.
 +
 
 +
Back to our task: The pattern is <code>^pwb</code>. Let’s assume that we have defined 2 variables in some other script. The variable "weapon" is the weapon we use and the variable "bag" is the name of the bag. NOTE: In Mudlet global variables can be accessed anywhere from within Mudlet scripts - no matter if they have been defined in a trigger script, in an alias script or in a key or button script. As soon as it’s been defined it somewhere it is usable. To make sure that a variable is local only, i. e. cannot be referenced from other scripts, you have to use the keyword local in front of your variable definition. Back to our alias: Pattern is: <code>^pwb</code>
 +
 
 +
Script is:
 +
<syntaxhighlight lang="lua">
 +
send(f"put {weapon} in {bag}")
 +
</syntaxhighlight>
 +
Depending on the values of our variables weapon and bag the command "pwb" will be substituted with an appropriate command. To set your weapon and bag variables we use 2 more aliases: Alias to set the weapon: <code>uw (\w)+</code>
 +
 
 +
Script:
 +
<syntaxhighlight lang="lua">
 +
weapon = matches[2]
 +
send( "wield " .. weapon )
 +
</syntaxhighlight>
 +
To set our bag variable: Pattern:<code>^set bag (.*)</code>
 +
<syntaxhighlight lang="lua">
 +
bag = matches[2]
 +
</syntaxhighlight>
 +
Now let’s go back to our initial problem. We want an alias to put our current weapon into our current bag. But what happens if we are in the middle of a fight and absolutely need to sip a healing potions because we are close to death and cannot take the risk that the bag may be too full to take the weapon? We want to upgrade out little alias to take into account that the bag may be full and chose an empty bag instead. To do this we set up a trigger that detects messages that indicate that the attempt to put the weapon in the bag failed. In this trigger we execute this little bag-is-full-detection-trigger Trigger Pattern: (type substring) <code>Your bag is full.</code>
 +
 
 +
Script:
 +
<syntaxhighlight lang="lua">
 +
bagIsFull = true;
 +
</syntaxhighlight>
 +
This detection trigger will set the variable <code>bagIsFull</code> to true as soon as it sees the message "Your bag is full.". Then you know that you have to use your spare bag to take the weapon.
 +
 
 +
Now we have the tools to write an improved version of our little alias script:
 +
<syntaxhighlight lang="lua">
 +
if bagIsFull then
 +
    send(f"put {weapon} in {spareBag}")
 +
else
 +
    send(f"put {weapon} in {bag}")
 +
end
 +
</syntaxhighlight>
 +
The next example is one of the most common aliases a tell alias: Pattern:<code>^tj (.*)</code>
 +
 
 +
Script:
 +
<syntaxhighlight lang="lua">
 +
send("tell Jane " .. matches[2])
 +
</syntaxhighlight>
 +
Sadly, Jane is your fiancée and the one thing she is a vegetarian and absolutely hates all words that relate to meat. Luckily, you know enough about aliases by now to make her believe that you’d never ever even think about meat. So you head to your global function script (any script item will do as long as you define your variables '''<span style="color:blue">outside of</span>''' your function definitions. See the scripts chapter below for more information. In your script "my global functions" you add a Lua table containing a list of all of all words that a vegetarian might hate. For example:
 +
<syntaxhighlight lang="lua">
 +
happyJaneTable = {"meat", "burger", "steak", "hamburger", "chickenburger"}
 +
</syntaxhighlight>
 +
Now you can upgrade your tell-jane script to automatically search our tell for all words that Jane might not like. In case such a word is found we substitute the entire tell with "How is the weather?".
 +
<syntaxhighlight lang="lua">
 +
for key, value in ipairs(happyJaneTable) do      -- looking at each element of the list
 +
    badWord = happyJaneTable[key]                -- check out the Lua table chapter below for more info
 +
    begin, end = string.find(command, badWord)    -- begin holds the start position of the word, end* the end-position
 +
    if begin ~= nil then                          -- we have found a bad word
 +
        send("tell Jane How is the weather?")
 +
        return
 +
    end
 +
end
 +
</syntaxhighlight>
 +
 
 +
== Alias Examples ==
 +
 
 +
Alias:
 +
<syntaxhighlight lang="lua">
 +
^cc( .+)?
 +
</syntaxhighlight>
 +
 
 +
Script:
 +
<syntaxhighlight lang="lua">
 +
local target = matches[2] or ""
 +
send("c cure critical" .. target)
 +
</syntaxhighlight>
 +
 
 +
= Default keybindings in the main window =
 +
{| {{table}} class="wikitable"
 +
| align="center" style="background:#f0f0f0;"|'''Keypress'''
 +
| align="center" style="background:#f0f0f0;"|'''Action'''
 +
|-
 +
| Left Arrow||Moves the cursor one character to the left.
 +
|-
 +
| Shift+Left Arrow||Moves and selects text one character to the left.
 +
|-
 +
| Right Arrow||Moves the cursor one character to the right.
 +
|-
 +
| Shift+Right Arrow||Moves and selects text one character to the right.
 +
|-
 +
| Home||Moves the cursor to the beginning of the line.
 +
|-
 +
| End||Moves the cursor to the end of the line.
 +
|-
 +
| Backspace||Deletes the character to the left of the cursor.
 +
|-
 +
| Ctrl+Backspace||Deletes the word to the left of the cursor.
 +
|-
 +
| Delete||Deletes the character to the right of the cursor.
 +
|-
 +
| Ctrl+Delete||Deletes the word to the right of the cursor.
 +
|-
 +
| Ctrl+A||Select all.
 +
|-
 +
| Ctrl+C||Copies the selected text to the clipboard.
 +
|-
 +
| Ctrl+Insert||Copies the selected text to the clipboard.
 +
|-
 +
| Ctrl+K||Deletes to the end of the line.
 +
|-
 +
| Ctrl+V||Pastes the clipboard text into line edit.
 +
|-
 +
| Shift+Insert||Pastes the clipboard text into line edit.
 +
|-
 +
| Ctrl+X||Deletes the selected text and copies it to the clipboard.
 +
|-
 +
| Shift+Delete||Deletes the selected text and copies it to the clipboard.
 +
|-
 +
| Ctrl+Z||Undoes the last operation.
 +
|-
 +
| Ctrl+Y||Redoes the last undone operation.
 +
|-
 +
| Ctrl+<Click>||Select the whole line.
 +
|-
 +
| Ctrl+Enter||Close split screen (scroll all the way to the bottom).
 +
|-
 +
| Ctrl+F||Search for text in the main output window.
 +
|}
 +
 
 +
= Considerations =
 +
 
 +
* Mudlet 4.17.2 currently ''does not'' support named capture groups for aliases.
 +
** You will need to use <code>matches[1]</code>,<code>matches[2]</code> etc. instead.
 +
 
 +
* You can use [https://perldoc.perl.org/perlre#Modifiers modifiers] for these regexes. Declare these at the start, in the form <code>(?modifiers)</code>
 +
** For example, to match the command <code>test</code>, ignoring case, you would need to declare the regex as being case-insensitive, like so: <code>(?i)^test$</code>
  
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 on what command that you are typing in the command line, your new alias will 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 alias 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. Alias as basically, a feature to save you a bit of typing - much like buttons which will be described in detail in section two of the manual. To learn more about more complex aliases have a look at section 2 of the manual.
 
  
 
[[Category:Mudlet Manual]]
 
[[Category:Mudlet Manual]]

Latest revision as of 16:00, 17 June 2024

React on input - Mudlets Alias Engine

Note Note: A screencast is available on getting started with aliases - watch it!

Mudlet has a feature called "aliases" that allows you to set up certain phrases or commands that will automatically trigger certain actions or responses. These actions are defined using a specific type of language called "Perl regex expressions." Aliases only work on the input that the user types into the command line, while a separate feature called "triggers" works on the output that the game sends back. When you type a command and press enter, it is sent to the alias feature to see if it matches any of the phrases or commands that have been set up. If it does match, the alias will take over and either send a different command to the game or run a script (a set of instructions) that you have defined. This system is powerful because it gives you control over what happens when a certain phrase or command is entered. You can even change the user's input as it is being processed, allowing you to manipulate the command before it is sent to the game.

Alias-diagram.png

The example in the diagram above shows 2 matching aliases, but only one of them sends commands to the game - and only if the player is healthy enough to attack the opponent. The other alias that matched the user input (enemy) choses a fitting opponent and sets the variable enemy accordingly, otherwise it issues a warning that attacking one of the available enemies would be too dangerous.

For an alias to match the command text the same rules as explained above in the trigger section apply. However, to simplify matters there is only one alias type. As alias are not performance critical we could reduce the amount of trigger types to just Perl regex as this type can do it all and performance is no issue with alias as the amount of data is much less. Even if you type like a madman you’ll never get close to sending the same amount of text to the game than the amount of text the game sends back to you.

What does it mean that a regex is true or "matched"? A trigger or an alias fires - or executes its commands/script - when the text matches the pattern of the trigger or alias. In most cases this means that the text contains the trigger/alias pattern. If the regex pattern is reen then a text "The green house" will match because "reen" is contained in the text. More complex regex patterns can also hold information on where in the text a certain pattern must occur in order to match. ^tj only matches when the letters "tj" occur at the beginning of the text. Consequently, a text like "go tj" would not match. Regex patterns can also capture data like numbers, sequences of letters, words etc. at certain positions in the text. This is very useful for game related scripting and this is why it is explained below.

Let’s get back to alias. We start with a simple example.

We want Mudlet to send "put weapon in bag" whenever we type "pwb". Consequently, the pattern is pwb and as the task is so simple it’s enough to enter "put weapon in bag" in the send field. Then we click on save to save the changes and activate the alias by clicking on the padlock icon. Then we leave the trigger editor and test our new alias. After typing "pwb" and pressing return Mudlet will send the command "put weapon in bag" to the game.

Let’s move on to a more complicated example that is needed very often.

We want our script to automatically put the weapon in the correct bag as we have many bags and many weapons. The pattern stays the same. ^pwb The ^ at the beginning of the line means that the command starts with pwd and no other letter in front of this. If we define our pattern more clearly, the pattern will match less often. Without the ^ the alias will match and the alias script will always be run whenever there is the sequence of letters "pwb" in your commands. This may not always be what you want. This is why it’s usually a good idea to make the pattern definition as exact as needed by being less general. The more general the pattern, the more often it will match.

Back to our task: The pattern is ^pwb. Let’s assume that we have defined 2 variables in some other script. The variable "weapon" is the weapon we use and the variable "bag" is the name of the bag. NOTE: In Mudlet global variables can be accessed anywhere from within Mudlet scripts - no matter if they have been defined in a trigger script, in an alias script or in a key or button script. As soon as it’s been defined it somewhere it is usable. To make sure that a variable is local only, i. e. cannot be referenced from other scripts, you have to use the keyword local in front of your variable definition. Back to our alias: Pattern is: ^pwb

Script is:

send(f"put {weapon} in {bag}")

Depending on the values of our variables weapon and bag the command "pwb" will be substituted with an appropriate command. To set your weapon and bag variables we use 2 more aliases: Alias to set the weapon: uw (\w)+

Script:

weapon = matches[2]
send( "wield " .. weapon )

To set our bag variable: Pattern:^set bag (.*)

bag = matches[2]

Now let’s go back to our initial problem. We want an alias to put our current weapon into our current bag. But what happens if we are in the middle of a fight and absolutely need to sip a healing potions because we are close to death and cannot take the risk that the bag may be too full to take the weapon? We want to upgrade out little alias to take into account that the bag may be full and chose an empty bag instead. To do this we set up a trigger that detects messages that indicate that the attempt to put the weapon in the bag failed. In this trigger we execute this little bag-is-full-detection-trigger Trigger Pattern: (type substring) Your bag is full.

Script:

bagIsFull = true;

This detection trigger will set the variable bagIsFull to true as soon as it sees the message "Your bag is full.". Then you know that you have to use your spare bag to take the weapon.

Now we have the tools to write an improved version of our little alias script:

if bagIsFull then
    send(f"put {weapon} in {spareBag}")
else
    send(f"put {weapon} in {bag}")
end

The next example is one of the most common aliases a tell alias: Pattern:^tj (.*)

Script:

send("tell Jane " .. matches[2])

Sadly, Jane is your fiancée and the one thing she is a vegetarian and absolutely hates all words that relate to meat. Luckily, you know enough about aliases by now to make her believe that you’d never ever even think about meat. So you head to your global function script (any script item will do as long as you define your variables outside of your function definitions. See the scripts chapter below for more information. In your script "my global functions" you add a Lua table containing a list of all of all words that a vegetarian might hate. For example:

happyJaneTable = {"meat", "burger", "steak", "hamburger", "chickenburger"}

Now you can upgrade your tell-jane script to automatically search our tell for all words that Jane might not like. In case such a word is found we substitute the entire tell with "How is the weather?".

for key, value in ipairs(happyJaneTable) do       -- looking at each element of the list
    badWord = happyJaneTable[key]                 -- check out the Lua table chapter below for more info
    begin, end = string.find(command, badWord)    -- begin holds the start position of the word, end* the end-position
    if begin ~= nil then                          -- we have found a bad word
        send("tell Jane How is the weather?")
        return
    end
end

Alias Examples

Alias:

^cc( .+)?

Script:

local target = matches[2] or ""
send("c cure critical" .. target)

Default keybindings in the main window

Keypress Action
Left Arrow Moves the cursor one character to the left.
Shift+Left Arrow Moves and selects text one character to the left.
Right Arrow Moves the cursor one character to the right.
Shift+Right Arrow Moves and selects text one character to the right.
Home Moves the cursor to the beginning of the line.
End Moves the cursor to the end of the line.
Backspace Deletes the character to the left of the cursor.
Ctrl+Backspace Deletes the word to the left of the cursor.
Delete Deletes the character to the right of the cursor.
Ctrl+Delete Deletes the word to the right of the cursor.
Ctrl+A Select all.
Ctrl+C Copies the selected text to the clipboard.
Ctrl+Insert Copies the selected text to the clipboard.
Ctrl+K Deletes to the end of the line.
Ctrl+V Pastes the clipboard text into line edit.
Shift+Insert Pastes the clipboard text into line edit.
Ctrl+X Deletes the selected text and copies it to the clipboard.
Shift+Delete Deletes the selected text and copies it to the clipboard.
Ctrl+Z Undoes the last operation.
Ctrl+Y Redoes the last undone operation.
Ctrl+<Click> Select the whole line.
Ctrl+Enter Close split screen (scroll all the way to the bottom).
Ctrl+F Search for text in the main output window.

Considerations

  • Mudlet 4.17.2 currently does not support named capture groups for aliases.
    • You will need to use matches[1],matches[2] etc. instead.
  • You can use modifiers for these regexes. Declare these at the start, in the form (?modifiers)
    • For example, to match the command test, ignoring case, you would need to declare the regex as being case-insensitive, like so: (?i)^test$