Basic

• Introduction.
• Differences from other clients.
• Basic stuff, how to get you started.
• Funky Monkey Tree.
• Aliases.
• Actions.
• Keybinding.
• Substitutes.
• Commands and parameter syntax.
• Using GLOB's
• Advanced stuff, how to get the most of your scripts.
• Using Regular Expressions
• Object structure, how to access MonkeyTerm's modules.
• How to understand and edit the savefile
• What you can and can not, and what to expect in the future.
• Things to know.
• Upcomming features.
• Further questions?

Introduction

Differences from other clients

If you tried Zmud or Tintin, you should recognize some thing from there. The platform is MS Windows, and we've got aliases, actions (triggers in Zmud), substitues and variables just like Zmud and Tintin, but much of what you see is just to make you feel more comfortable - what lies beneath Monkey Term is a lot more different from any of those clients. We got three kinds of scripting languages, two are used for pattern matching (Regular Expressions and GLOB's) and if you're familiar with Regular Expressions this will be a feast. If you're not, you might want to use GLOB's or check out the section explaining Regular Expressions (clients like tinyfuge also use regular expression, making it an excellent choice for unix/linux platforms, if you want more control of your patterns). The last one is Visual Basic scripting and can be used anywhere in your aliases, actions or where you find them usefull. The real strength lies with the Visual Basic scripting ofcourse, with it you can access many of the build-in objects like our media object or even the session object which holds informations about the session you are in. You will learn more about this in later chapters. When entering alises or actions you can do it through the forms provided when you press F5 or F6, but you can also type the on the command line, more of this later.

Basic stuff, how to get you started.

Ok, what you need is some basic info that will let you know how to start mudding at your favorite place. If this is the first time you start Monkey Term you will have to open a new session, go to File and then New (This could also have been done by pressing Ctrl+N or pressing on the white paper icon on the line below). Enter an appropriate name for this Session, if you want to connect to AstroMUD as 'Trojan' you could enter Trojan on AstroMUD under host you would enter astro.mud.com and under port enter 2447. Now click on Connect. If you have already connected you should get a form with a list of recent connections, you may click on any of them to choose it or you can close this form to open a file or create a new as described above. Enter the your name, password to enter the game. This would be a good time to save your session. Go to File and Save (Ctrl+s or clicking on the disk icon below would do the same). Enter a name you would like to save your session as and press Save. You should make sure the option Save on exit under File is checked. This way you won't have to save every time you make a change.

The Funky Monkey Tree (FMT)

The FMT is organizes your actions, aliases, events, keybindings, substitutes and variables in a convenient way. It is here you can create and manage your aliases and more. You can group your aliases by naming them appropriately. For example the alias "enemy/tar" is grouped into the alias- group "enemy".

Creating a new item in the tree is easy. Right click on the tree and selecting "New item".

Aliases

At this point you might want to try and make an Alias. Let's create an alias that will create a bread and eat it. Bring up the FMT, right click on Aliases in the tree and select "Add item" to add a new alias.

Whenever you type eb the client will send the two commands cast 'create food' and eat bread to the mud. Let's look at another example. Let's say you are wearing a pair of saddle bags around your waist and you want to make an alises that removes your saddle bags gets an item from it and puts it back on. Under Alias type:

Learn more about the parameter syntax in later chapters.

Actions

With actions you'll be able to make Monkey Term respond to certain output from the MUD. When you setup an action it will execute a list of commands for you. Let's look at a simple example of how to make MonkeyTerm eat a bread and play a monkey sound when you are hungry. Bring up the FMT (F5). You can now chose to enter the pattern as a simple pattern or not. Simple patterns are aGLOB's and non-simple patterns are Regular Expressions.

GLOB match: You are hungry. Regular Expression match: ^You are hungry\.

In this case the GLOB match seems to be the most straight forward, so go with that. Right click on actions in the FMT and add a new action.

Key Bindings

Sometimes you want instant action but you won't know when till it happens, this means your actions won't be of much help. ofcourse you could make an alias with a short name so it wouldn't take too long to type. Well if that is the case, a better solution would be to bind a key to a list of commands. Let's say you want a key binded to cast full heal. First add a new keybinding in the FMT. Under Key combination press the F1 key. Under Commands type: cast 'full heal'
  Now notice the extra newline, it will force Monkey Term to send the command right away, without waiting for you to hit enter. If you omit the extra newline you can add something after the text is printed on the screen and then hit enter, but then you would loose a lot of the speed and making an alias with a parameter would probably be a better idea.

Substitutes

Substitutes will change stuff on your screen for you. You can for example remove spam, or change unplesant words to something else. You can also use this to highlight certain text, making it easier to notice. You can use regular expressions in your substitute matches, but let's start with an easy example. Let's say you're tired of seeing Homer's boring name. You want to spice it up a bit, changing it to Papa Homer.

Use the FMT to create the following substitute

From now on you will see the string Papa Homer every time the mud sends the string Homer to you.

Commands and parameter syntax.

Simple actions and aliases are cool, but if you really wanna kick some ass you need to know about the extra commands and learn the syntax for calling them, with or without parameters. Let's take the example from before. The calling of <% application.media.beep %> will access the sub beep in the media object, linked to the application object (learn about the object structure in a later chapter) or check the MOM.

If you want to learn more about VBScript you should go check out the documentation from Microsoft.

Executing vbscript is always done inside '<% %¤>' tags. This looks alot like the syntax used in ASP, so if you are familiar with that this should be easy. Calling functions that returns something or reading variable values is done using an additional leading equal sign '<% = "something" %>'. Let's take an example. Add a new alias:

Name: enemy/tar
Pattern: tar
Command: <%
var("target") = $1
application.sbStatusBar.Panels(1).text = "Target: " & $1
%>
say target is set to %1 Case sensitive: no
Simple pattern: yes
Active: yes

Ok, let's say you use this alias calling it like this: tar sphinx
In line one a new variable target is set to sphinx. Using $1 will take your input and use it as a string. This is needed when you need to pass the value on to a sub or a function or setting a variable.

If you do not use it for input for another sub or function you will use %1 instead like you do in line 3, if you do use $0 then your input will be printed out with a pair of double quotes ". You should fool around with it a little before you get the big picture.

Using GLOB's

GLOB matching is much simpler than Regular Expression matching. While Regular Expressions gives you total control of what you are trying to match, GLOB's are very lazy :) With a GLOB match you simple type the exact string you want to match and using the two wildcards * and ?

* will match any string of letters, spaces, number etc.
? will match one character, one number, one space, etc.

Advanced stuff, how to get the most of your scripts.

Using Regular Expressions.

Books have been written on this subject so i'll make this short and hopefully understandable by most users. If you need more information Check out Mastering Regular Expressions from the O'Reilly & Associates, Inc.

So you want to match some text. Many clients use a syntax that will allow wildcards. Matching the string "The winds whisper 'Hojou has left the realm!!'" would be matched with "The winds whisper '%1 has left the realm!!'". %1 would match anything and in most cases that would enough. This is not how MonkeyTerm works. Regular Expressions gives you the power to make your matches very specific.

Ok i sat down trying to come up with a simple example of where you would want to use regular expressions instead of normal pattern matching, and ended up writing too much text. I'll just tell you how it works, and it will be up to you to figure out how you want to use it. There should be examples using Regular Expressions throughout the Help Library and in the Tutorials.

This was a short, short introduction to regular expressions. If you didn't understand any of this, don't panic. Regular expressions are cool, and if you want to just be able to match anything like you used it, just stick with GLOB patterns (simple patterns), but remember GLOBS match start and end of line by default, so no using fancy ^ and $ when doing GLOB's

MonkeyTerm can match strings spanning more lines. This is more complicated and will be explained later. For fun testing try using \n to match a newline.

Object structure, how to access MonkeyTerm's modules.

We finally managed to document the object hierachy of MonkeyTerm. Check out the Monkey Object Model. Below is a list of the objects that you can readily access using their name in <% %> tags.

Session. A session object is created for each connection you have. This means that if you are playing with eg. two characters at a time, two session objects will be in effect. Stuff that is session dependant will therefore be connected to somewhere around here. Examples are: <% session.terminal.printstring "Mental Note: Play more MUD!" & vbCrLf
msgbox(session.filename) %> You can see more examples in the default script (default.mos).

Application. Surprisingly? this is the object that is bound to the application itself. When you start MonkeyTerm the application object will be available and since there is only one of it, things that should be the same for all sessions are located here. Examples are: <% application.media.PlayWav "sounds\chimp.wav"
application.media.music.requestplay "http://www.phunck.com/Music/vdp.m3u",10,100,1,false
application.media.music.stopplaying
application.media.Beep
application.media.ShellOpen "http://www.mud.com/astromud"
application.sbStatusBar.Panels(1).text = "He likes peanuts." %>

Var. Shorthand for "session.variables". A collection variables bound to the session. These variables will save with your session. <% var("HP")=34 msgbox("I've got " & var("HP") & " hitpoints left.") %>

Web. Shorthand for "session.web". Holds references to web related objects. <% web.browser.locationurl="http://www.eternals.dk/monkeyterm" var("Friend")=web.request("Friend") %>

How to understand and edit the savefile.

Savefiles are not binary data, but the structure might not be easy to understand for normal users. The savefiles consist of XML data and XML data is very strict about the format you use. The reason why we picked it is because it is a good format to store out data in, it's a recognized format and used on all platforms, there are also a lot of XML parsers out there making it easy for us to implement an error-free parser.

First open your savefile (it has the .xml extention) in a text viewer (notepad etc.). What do you see? It looks almost like HTML but just more confusing right? Don't worry it's actually really simple.
The savefile has a structure consisting of XML tags. The tags are nested in levels like HTML or folders on your harddisk. What i mean by that is, try and see the XML data as being containers of data each being able to hold more containers (just like a folder in a folder on your harddisk). The top level (like c: on your computer) is called <savefile> and the matching end-tag is called </savefile>. All your actions, aliases and substitutes are stored in matching nodes (like three different folders on your harddisk), called <aliases> <actions> and <substitutes> they all have matching end-tags called </aliases> </actions> and </substitutes>.

A simple demontrative example of a savefile would look like this:
<savefile>
  <aliases>
    ...
  </aliases>
  <actions>
    ...
  </actions>
  <substitutes>
    ...
  </substitutes>
</savefile>


The dots (...) represent more data, and that is what i'll explain now. For each node (like a folder on your computer) you can place more nodes and data. Let us take aliases for an example. The <aliases> node has subnodes each called alias. Notice that the subnode to <aliases> is <alias>. For <actions> the subnode is called <action> and for <substitutes> the subnode is <substitute>. Take a moment to reflect on that - the subnodes of each group has the same name, just in singular term. It makes sence if you think about it. <aliases> holds information about all aliases, and each of these aliases are called <alias>. The same goes for substitutes and actions.

Let us zoom in on the aliases part (leaving out the actions and substitutes in this example)
...
  <aliases>

    <alias name="basic/tar" format="plain">
      #var("target") = $1
    </alias>

    <alias name="basic/kt" format="plain">
      kill #=var("target")
    </alias>

  </aliases>
...


As you can see, the aliases are all located as a subnode to the <aliases> node, and they are all called <alias>. They are recognized by the name "attribute". If you add another alias to your savefile, it will be added between the <aliases> and </aliases> tags just like the "basic/tar" and "basic/kt" aliases are. If you want to copy the "basic/tar" alias to a friend you just copy this part:
    <alias name="basic/tar" format="plain">
      #var("target") = $1
    </alias>

and he can add it to his own savefile.

In some cases, when you want to add something to an almost blank savefile (one that has no aliases, actions or subsitutes) you will see that there is no normal start of end-tag to the aliases, actions and substitute tags. This is because the XML parser will compact the nodes that are not in use. In that case you will see something like this:
<savefile>
  <aliases/>
  <actions/>
  <substitutes/>
...
</savefile>
As you can see the tags now END with the slash (/) and so the tag <aliases/> is different from BOTH <alises> and </aliases>. If you want to add an alias, there are no start and end tags to place it between. To fix this, you just add them youself - changing
  <aliases/>
to:   <aliases>
    ...
  </aliases>
and place the aliases in the place where i left the dots (...).

I hope you understood this small tutorial on XML and how MonkeyTerm uses XML. I tried to keep it simple, but by doing that i have to leave out parts that you might feel are missing. If you want to understand MonkeyTerm's savefiles, brushing up on XML is a good idea, but for now this ought to be enough for everybody (didn't i hear that before?;).

What you can and can not, and what to expect in the future.

It has always been our goal to make a client that will give you the most power possible when mudding. Power is never gained easily and like in the real world *cough* mud you will see that the same applies. Few things come very easily and you will need to work to get what you want, yeah yeah... bla bla... anyways, what i'm trying to say is, you need to take your time to learn how to use MonkeyTerm if you want to take full advantage of its powers. Much of the efford you put into it can pay off later as the time spend learning VBScript and Regular Expressions can be used later in your real life since neither of them are MonkeyTerm standarts and both are good technologies to use in software development.

VBScript is very powerfull and with it, you can create almost anything you'd want - did i say almost? Well i ment everything ofcourse, except for love and money - well perhaps money :) and i guess if you get really good at it, people will say you love it too. Ok enough rambling.
MonkeyTerm is a good core program that can fire events, parse your Regular Expressions or GLOB's and execute your VBScripts. This leaves you with the task of writing the patterns and scripts. With the scripts you can perform any Windows task but far from everyone can write VBScript. That is where you might say MonkeyTerm falls short, but if you want the computer to do something for you, you will need to tell it one way or the other, we just think that VBScript is an easy and comfortable way of doing so. If you have no plans of ever learning VBScript then don't worry, we will try to write some of the scripts we think you might want to use. Also we hope that, when MonkeyTerm becomes a bit more common, that some people will share their scripts with us by emailing them to us, the creators of MonkeyTerm so we can put them up for download on this page.

If VBScript can do anything, why isn't MonkeyTerm done yet? Well, we could make this client commandline only, but even we like a nice userinterface and some easy to use objects. Some cool things might be very hard and tedious to write in VBScript and some of those things will be hardcoded into MonkeyTerm. Check the list of Expected upcomming features for more information on what we are working on right now.

Things to know.

I'm working on this section, but i figured i'd better write some of the important stuff down.

• Remember that certain characters have special meaning when writing Regular Expression triggers. Pay special attention to the following characters: .+*?()\[]
  All special characters can be escaped by adding a '\' (backslash) before the character. Here is an example: the pattern 'BotOn?' would be written as 'BotOn\?'
• See the white box in the bottom of the screen? It expands over multiple lines. This is because you can type more than once line and send them all at once. Once you press Enter, everything is sent, but if you press Ctrl+Enter you insert a new line to write on. You can change between the lines with arrow up and arrow down.
• Remember that you got full power with MonkteyTerm, that also means that you can do some wierd stuff. It's easy to make a looping trigger or alias, but it's also very easy not to - as long as you know how to control it. If you make an alias called 'recall' and you then put the action 'recall' in the commands list, well then you won't send the command 'recall' to the mud, instead MT will parse 'recall' and see it as the aliases itself, thus looping endlessly :)
• When to use %1, $1 or £1? Well there is an easy way to remember what to use. When you need to send the result to the mud you always use %1. When you need to send the result to a script you use $1 or £1. $1 is whatever match you got, this match could contain the symbol # or a newline character - that's not nessisarily bad, but if you are executing the result of an action someone might be able to abuse it (This only happens if you actually make an action, where you use the result of the match as your own command) It should be obvious, if you automaticly do what it says on the screen you can get hurt, but since some people either like to do so :) or they don't think about it, we added the £1 variable kind instead, it should be safe from excuting scripts or chaining commands. That means, if you do not know what you are doing, you might want to change your $1 to £1 :) If you do know what you are doing, good for you :)
  Easy right? Well if you're not much of a scripter you'll probably only use %1 - that's cool, but that also means you're not taking full advantage of this client.
• Ever wanted to type something like 'buy #5' and you get an error? Well the #-sign is used for calling VBScript code but you can override that by adding a leading \ (backslash) "buy \#5". You will get the same error if you need to write $1 %1 etc. remember to escape those with a leading backlash too. Also if you type in the black window (not the white chatwindow) everything will be send as-is to the mud, so you shouldn't escape anything (typing in the black window is generally a bad idea since it will send each keypress to the mud, and might mess up your actions etc).

Expected upcomming features.

Here is a list of things we are planning to implement either in the near future or later. Much of it has been added by requests from our users.

• Grouped actions/alises/keybindings.
• Automapper.
• Save scrollback history.
• Anchor windows.
• Scheduled commands.
• Anything you like, send us an email (see bottom of the page)

Further questions?

You got more quesitons?
Perhaps you know something about MT we didn't explain and want to share it with other users?
Perhaps you got some ideas for improvement?

Well, email one of the creators at
Aslak Grinsted AKA AsPhunck
Per Schierbeck AKA Hojou