Creating scripts

Getting started

A script is a collection of customisations known as script items. You can have a single script for all your customisations, or do each one in a different script, or something in between - it's up to you.

Create a script using the New button in the Scripting window. Then edit it using the Edit button to bring up the script editor.

Script editor

In the script editor you can add or delete items as well as edit each item. You can also enable or disable individual items. When you've made any changes (such as adding a script item, disabling one, or editing some code within one) you need to click Save before they will take effect. It's also possible to click Revert, which will undo your changes and return to the previous saved version.

You can only enable or disable the whole script when there aren't any unsaved changes. (In other words, save it first, then enable it.)

Script items

Create script items by clicking Add item, choosing the type of item from the dropdown, and then altering the settings as needed.

You can change the settings later by clicking the Settings button next to the relevant item, or delete the item altogether using the Delete button.

Code blocks

Along with the settings dialog, most script items require you to type in blocks of code, which you can edit directly in the script editor window. For example, the 'Command' item uses the settings dialog to specify the name of the command and any parameters, but you use the code block to specify what actually happens when you type that command.

IRC commands

You can type IRC commands into the code block. If the script item includes parameters or other variables (these will be displayed just above the code block), you can include these in the IRC command as ${variable}. For example:

/msg ${nick} You smell of cheese.

Technically, the contents of ${} can be any Java expression, but it is most straightforward to use simple variable names.

If you want to do 'normal talking' in your script (i.e. exactly the same as if you just typed text in the window), you can't do this just with plain text as this will cause errors. Instead, put /say in front. leafChat automatically works out where to send the text.

/say So I was wondering...

Java code

You can also include Java code in the code block. Any line that doesn't begin with a / is interpreted as Java code. You can mix IRC commands with the Java code, too. For instance:

// List of cheeses
String[] cheeses={"Cheddar","Gorgonzola","Stilton"};
// Pick a cheese at random
String random=cheeses[(int)(Math.random()*cheeses.length)];
// Now send the message using the random cheese
/msg ${nick} You smell of ${random}.

As you can see, standard Java // comments can be used.

One final Java extension for advanced users is that you can use double square brackets to access one of the singleton classes leafChat provides. These are documented in the plugin API. (In scripts you have access to the full leafChat public API from all plugins, without needing to import anything or use full names.)

[[UI]].showUserError(null,"User error","The user has done something wrong");

Code errors

When you save your script, it will be checked for syntax errors. (These are only likely to happen if you use Java code.) If there are errors, you can choose to disable the script and save it, or to cancel (not save). You can't save a script and leave it enabled if there are errors. If you want to do so, try disabling the individual item which causes errors.

leafChat tries to guess the approximate lines on which the error occurred. These will be highlighted in yellow on the script item which caused the error. Sometimes it might guess the wrong line, so be careful. Similarly, the error message is displayed at the bottom of the item, but this might sometimes be wrong or unhelpful.

Script items

There are four types of script item:

Command

The Command item lets you create a new IRC command, such as /cheese. You can control what happens when you type this command.

Settings include the name of the command (be sure to choose a name that isn't already used) and a list of parameters. Parameters are what gets typed after the command. For example, if you expect people to type /cheese Victim, then the nickname is a parameter.

Menu item

The Menu item item lets you add a new option which appears in right-click menus when you click on a user or channel.

When you create the item you give it a name, which displays in the menu (can be anything), and set whether you want it to apply for users, for channels, or only when both a user and a channel is available.

Event

Using Event items, you can script reactions to things that happen on IRC, such as other users saying things.

A tree of available event types appears in the left of the settings window. You can expand folders in this tree to find the type of event you want to respond to. For example, if you want to respond to users saying things in channels, that is under IRC/From user/Channel/Message.

Once you have chosen an event type, a brief description of that type appears on the right along with a list of the variables that will become available for your script. Some types also have filters which you can enable (for example, if you only want to receive the event for a specific named channel).

Your script code then runs whenever the event happens.

Variable

Variable items define named variables that you can use to store information, and can refer to from all other script items in the same script.

Each variable needs a unique name which begins with a lower-case letter, then includes any letters and numbers but no spaces or symbols. For example, tadpoleSize is a valid variable name.

You can choose the type of variable. String variables store text (words) while int variables contain whole numbers. These behave differently if you try to do arithmetic: with ints, 2+2 is 4 but with Strings, "2"+"2" is "22" (and "tad"+"pole" is "tadpole"). Advanced users can use other Java types.

You can specify the initial value of a variable. If you don't specify it, ints start at zero and Strings start with "".

Tutorial

Here's an example of using events and variables. This is an advanced example so you will need a small amount of programming experience in order to understand it.

We're going to create a script that watches out for people who yawn in channel by typing an action such as /me yawns. Once three people have yawned, it sends a message to the channel telling them to go to bed.

  1. First we're going to need a variable that keeps track of the number of yawns.
    1. Click Add item, then choose Variable from the dropdown.
    2. Type in the name, yawns.
    3. Select the type, int. We want this variable to store a number.
    4. Although it's the default anyway, let's type in the initial value of 0 just to be clear.
    5. Click Add.
  2. Now let's create an event that detects channel actions.
    1. Click Add item, then choose Event from the dropdown.
    2. In the tree at the left, double-click on IRC, From user, Channel, CTCP request, and finally click on Action. (Whew!)
    3. Note the warning: events only operate on information received from the server, not on things you send to it, which means you'll have to get somebody else to help if you want to test this script.
    4. Note also the list of variables that will be provided. The important ones are sourceNick (that's the person who did the action) and text (that's the text of the action, everything after /me).
    5. Go ahead and click Add.
  3. Finally we need to write the actual script code for the action in the code box. This involves a mixture of IRC commands and Java code.
    if(text.indexOf("yawn")!=-1) yawns++;
    if(yawns>2)
    {
      /say ${sourceNick} (and others) - GO TO BED!
      yawns=0;
    }
    
  4. That's it! If you want to test it out, don't forget to save the script (and, if neccessary, enable it) first.