Basic Concepts

These examples are created with the purpose of working on AstroMUD, they should work on any other muds with little modification though. This section will cover more topics later on.

Actions

Actions are also called Triggers is some clients. They act upon the data send from the mud. If you write a pattern for MonkeyTerm to match, you can have the client send some data back to the mud.

Ok, a few helpful starters. Anything you type in the command box (located under the pattern box) will be send to MonkeyTerm for processing. This means, you can call an alias, execute a script, send a speedwalk, etc. Also if you want MonkeyTerm to send some data you need to end your command with a newline. If you do not know what i'm talking about, try reading the Help Library first. The reason why MonkeyTerm needs the extra newline will be described in the following example. We're going to try something funny. Make sure you got the latest default.mos file from this site, located in your scripts folder and added to your scripts (F8).

Let's make an action that will flee from a battle once the monster is low on hitpoints. Obviously you will need to match the line in which you can see the mobs percentage (this won't be visible till you hit level 30 i think). So we need to match that line, and capture what percentage is left.

This pattern will match your status line with the mob percentage in it. It does not match the beginning of the line, nor the end. This can be a problem as people can send you a tell matching your pattern. This is something all clients have to deal with, and the solution is always the same; make the pattern specific enough so noone can trigger it by tells and gossip. The solution normally involves matching a whole line, or at least the beginning of the line. The pattern above is a Regular Expression and nothing prevents you from rewriting it to match the beginning of the line (actually it's pretty easy: add a leading ^ symbol). The reason why i didn't do it, is because the database tutorial substituted the status line so include some special chars and in this example i just want to show how it works for anybody. I'll write a section later about how to protect your actions against evil-minded-persons ;) but in this case, the worst that can happen is someone can make you flee.

First we match a sequence of numbers, then the string "Hp " then a series of numbers again, this goes on and on so let's skip to the last part, after the string "Lev " has been matched you see the pattern \[(\d+)%\] If you're not a (regular :)) Regular Expression user you might think it looks wierd, but check out the status line and you will recognize a pattern like [50%] - the [ and ] sign have a special meaning in Regular Expressions, so we need to escape them like this \[ and \] also we want to save the value after the [ sign and before the % sign, and we know that value will be one or more digits, so the pattern will be: \[(\d+)%\] - simple right? :) If not, check out the section about Regular Expressions in the Help Library. Ok, so now we got the percentage stored in $1, %1 and £1. You remember the difference? No? Hehe, well $1 is the string encoded version of your match, let's say the mob was at 99%, then the value of $1 will be "99". The value of %1 will be 99 and the value of £1 will also be 99. £1 will also be protected against script evokes and chained commands, so it's safer to use than %1. Keep this in mind, i'll explain the rest in the next paragraph.

Our goal is to flee if the mobs percentage goes below 50%, so the command should execute a "flee" if it is, otherwise it should execute nothing. The IIF function located in the default.mos can help us acheive this. It takes 3 parameters, the first is a boolean expression (something that evaluates to either true or false), the second is the result if the expression is true, the last parameter is the result if the expression is false. So our boolean expression is "is the mob percentage lower than 50%?" or in computer/mathematical language "£1 < 50". The reason why we do not use $1 here, is because $1 is string encoded, and we want the value not string-encoded since we have to compare it to a number, the reason why we do not use %1 is because the above pattern can be abused (as explained earlier) since it's not anchored (actually even anchored commands can be abused, by gods who can echo or sometimes by tricky players). Truth is, that the match is a sequence of numbers *only* (\d+) so it really doesn't matter if you use £1 or %1, this is just to illustrate how it works. We tell the IIF function to return "flee" followed by a newline if the expression is true, and to return an empty string if the expression is false. Obviously, the command will execute a flee if the mobs percentage is below 50% :)
There are other ways to execute commands than this way, but that will be explained later, when we're sure we won't change the syntax. All examples here should work in newer versions also, so we're avoiding creating examples that might change in the future.

Substitutes

Substitutes works a bit like Actions as they match some text send from the mud and take an action based on that. There are two major differences though. Substitutes match on the actual data send from the mud, including color codes and other weird ansi codes, actiones does not. Substitutes also gags(removed the matched pattern) removing it from the screen, actions leaves the pattern as it was.

So when do you want to use substitutes instead of actions? Well if you want to substitute something (oh boy that was easy right? :) You can substitute simple patterns like names, annoying fight-messages etc, but let's jump into it right away and try a useful example :)
Let's make a substitute for tells. We want to spice it up a bit, so you get it in a different color that the red one used now. We also want to change the look of tells, so they are more catchy :)
First, make sure you have the default.mos script added to your session (press F8), if not then add it. Ok, now let's try making a substitute(F7).

Pattern: What happened? You just made a Regular Expression match. Let's take it step by step. The first symbol "^" means that whatever pattern we are searching for starts on a new line. The "\a*" means that at the beginning of the line the pattern might contain a number of ansi codes (since tells are send in red color, there will be a ansi code for redcolor) and if you do not have colors on, we only said there MIGHT be some codes. Ok the next part "(\w+)" means any string of letters (of one or more letters), this will match a persons name since they consist of letters, without spaces and without numbers. This will be followed by the text " tells you, '" and then the pattern will save all the text it can before it runs into a ' and then the end of the line "$".
Got it? Good :)

The Command is pretty simple, even though it might look confusing. Let's take it from the beginning. The start "#=" means we will want the result of a script function. The function is called "highlight" and is defined in the default.mos you just made sure was added. That function takes two paramters, the last parameter is the string it will return and the first is the color it will return it with. So first we tell it to use color number 13 (bright purple) followed by the string "INCOMMING MESSAGE : (" followed by the value of the first match we did in the pattern "(\w+)", remember what that was? The name of the person sending you a tell. Followed by that is the string ") ->" then the second value matched in the Regular Expression "(.*)", the actual tell you got. Ok that's it - try it out :)
You can change the layout or even make several calls to hightlight to make the tell appear in more colors.

Any Comments? Just email us.