External scripting is probably the most powerful feature in KMuddy (in my opinion at least). It allows you to write programs or scripts that can help you play, perform some actions for you, or even play entirely for you! (if you know enough about AI, that is).

Note that scripting will only work if you have the scripting plug-in installed and enabled. It comes with the standard KMuddy distribution, so you likely do have it running.

First of all, you should be aware of one risk involved - many MUDs don't like using scripting too much, especially when it's used to raise some skills and so forth. I recommend reading the rules of your MUD before using scripts for anything of this sort. I take no responsibility for your deleted characters or anything else. But don't worry, scripting can be very useful without violating any rules, so read on! (frustrating paragraph, isn't it? ;-) )

In order to use scripting, you have to know some programming language. No matter which one, the only condition is that it must support standard input/output (almost all available languages meet this criteria, maybe Smalltalk is an exception, but who would write scripts in Smalltalk?). You can also use interpreted languages, like Perl or Python, and you can even use shell scripts.

You no longer need to use external scripting for simple tasks, as KMuddy now also offers its own internal scripting language. It is relatively simple, but new features will be added in future versions. Refer to the section about internal scripting for more information.

Enough of theory, let's go scripting! You can only define scripts for profile-based connections. The most important thing is the Profile / Scripts dialog box. Here you can define all the scripts you'll be using. Important options are:

Script name defines a name for this script. You can use it later to invoke this script from the input line or from an alias or a trigger.

Command to execute defines a command that is to be executed. If the executable/path contains spaces, you can use backslashes or quoting, as usual. This can also include parameters. Note that if you want to be able to specify additional parameters when launching this script from the input line, you'll have to enable the Allow custom parameters option. Remember that you have to write the script first. Depending on the language you choose, you may also need to compile it prior to using it.

Working directory defines a working directory for your script. This is only needed if your script works with other files.

The default script location and default working directory can be set in Profile / MUD preferences.

Enable script input enables sending of mud server output to the script. If you also enable Send user commands, then both server output and your commands will be sent to the script. To distinguish between these, you may want to Enable adv. communication, which allows your script to identify lines by prepending the numbers 1, 2, and 3 in front of them. Lines of server output have number 1, user commands have number 2. If your MUD supports sending of GA (go-ahead) signal, then you'll also receive lines with number 3, containing the prompt. Note that the following 1-line will include that prompt as well, so keep this in mind. Also note that your script has to support this type of identification.

The GA (go-ahead) signal means that the server is ready to accept new input, so you can use the 3-lines for that purpose. Also note that you may need to use some server command to ask it to send you GA signals. Even if the server does this by default, older versions of KMuddy (up to 0.4.1) were sending the SUPPRESS-GA option to the server. It's therefore likely that you will have GA-sending disabled if you used the older versions with that MUD.

IMPORTANT: If your script reads anything from its standard input, you must either enable script output or use shell expansion and let it read input from a file. Otherwise results may not be as expected.

Enable script output will catch output from the script and either display it to you or send it as a command to the MUD, depending on the Send script output option. Note that script output may have two different parts - standard output and error output. Error output will only be included if you enable the Include error output option.

No flow control disables the flow control mechanism for this script. Flow control is applied by default to all scripts and will carefully control how information is fed into scripts to make sure they are all processing the same line received from the MUD at the same time. This prevents the situation where one script is processing line 10 while another is processing line 5, which can cause a lot of headaches. A flow controlled script must process all input quickly, to prevent holding up all other running flow controlled scripts.

Communicate variables allows the script to create, read and alter the variables defined in Profile / Variables. You MUST set this option if you plan on using the getVariable() and setVariable() functions in your script.

Output prefix and Output suffix specify strings that will be prepended / appended to every line of script output prior to displaying or sending it. Note that if you want to separate the prefix/suffix with a space, you have to include that space too.

Enable shell expansion will run your command via shell, allowing you to use all sorts of shell expansion like wildcards or pipes.

Single-instance script allows only one instance of the script to be running at any time. Please note, if you maintain multiple connections using the same profile (strange, but could happen), then every connection can have a single instance of the script running.

Matching text and Comparison type can be used to filter text/commands that are sent to the script. Their usage is comparable to similar options available for aliases and triggers. The Positive matching option determines whether the text is sent when it matches the test (option ON), or when it does not match it (option OFF).

There are two ways how to run a script. The first one is to use the Run! button in Profile / Scripts. This is quick and efficient, but you cannot pass any parameters to the scripts.

The second way (which you will probably use much more frequently), is to run it from the input line - like any other command. This way can also be used to launch the script from an alias or a trigger (this is where all those possibilities begin). To execute a script, you just type a script-launching character ('/' by default) followed with the script name, and, optionally, some parameters. For example, if you want to run a script called foobar (a very popular name indeed), passing it parameter hello, you just type /foobar hello and it's off and running! Note that there mustn't be any space between the script character and the script name.

As an alternative to those who disable the script-launching character for any reason, the \m sequence can be used instead of that character.

If you want to see a list of all running scripts, you can find it under View / Show running scripts. This will display a list of all running scripts. Several options are available:

Suspend and Resume can be used to suspend and/or resume the script. Note that this is done by sending the SIGSTOP and SIGCONT signals, so it may not work properly if your script installs a handler for these (I'm not sure if it is possible to ignore the SIGSTOP signal, but who knows?)

Terminate will terminate your script. The script can install a signal handler that will ignore the SIGTERM signal, so this may not always work. The Kill command, on the other hand, always kills the script, there is no resistance :). Please note that it is better to try terminate first and only use kill as a last option, as it can lead to a loss of script data (if any).

One of the commands you can execute as the result of an action, trigger or a command typed from the input line is the /notify command. This will send a line of text to a TCP/IP port on the local machine. The general format of the command is:

/notify portnum data

The portnum is just a TCP/IP port number (a number between 1500 and 65535) that your script is listening to, or a variable which you have set to a port number, so it's possible to do /notify $myport hello there, for instance and hello there will be transmitted to whatever $myport is set to.

One reason to use /notify is efficiency - you can set up triggers in KMuddy to identify important events and then use /notify to communicate them to your script. When your script needs to send information back to KMuddy it can do it using the sendCommand() function, described in the Sending commands to KMuddy from your own scripts section.

Using /notify makes your scripts shorter and easier to write because you only need to have them process the important information and not have to sift through many lines of unimportant rubbish. This helps a lot if you are programming in a language that isn't very good at checking for text patterns and doesn't directly support regular expressions. It also provides a clean mechanism to separate the task of identifying important lines from the MUD (KMuddy triggers) and working out what to do with them (your scripts).

The /notify mechanism also has less latency than the Enable script input / Enable script output method of communicating with scripts.

If you are writing your scripts in C, C++, Perl or Ruby, there are example scripts you can use as templates for receiving data sent using the /notify feature in the scripting/ directory of the KMuddy package. More information can be found by reading the comments in the scripts themselves, but the basic idea is you call the initIPPort() function to set up which port your script will listen to, then you call getEvent() every time you wish to receive an event. Your script will go into a highly efficient sleep mode while waiting for an event, using up no CPU time until it actually has something useful to do.

KMuddy has its own set of variables you might wish to manipulate in your own scripts. If you are writing your scripts in C, C++, Perl or Ruby, there are example scripts in the scripting/ directory of the KMuddy package you can read through to get an idea of how it's done.

If you are exclusively using /notify to communicate with your scripts, you should not use Enable script input, Enable script output or Send script output feature to send commands to KMuddy. Instead there is the sendCommand() function provided in the example scripts in the scripting/ directory of the KMuddy package.

The sendCommand() function uses a similar transport mechanism to /notify to communicate commands to be sent to the MUD. It has all the same benefits of /notify - it is more efficient and less prone to latency. In addition it will halt the running of your script until the command has actually been sent, which helps keep your scripts syncronised and maximises overall system performance.

KMuddy can communicate variable values/changes with external scripts. UNIX domain sockets are used for this purpose. The scripting/ directory in KMuddy's source distribution contains some sample scripts in C, as well as a header file useful for writing other C/C++ scripts. Similar files for perl, python and ruby are available as well.