MIRC Scripting/Basics/Basics

You've got the foundation to use mIRC and the Scripts Editor. Now we can start with learning how to script. Read this chapter section by section and follow along with the examples. You will need to understand the skills in this chapter to move on and make any sort of script whatsoever. This is a very long chapter, especially for beginners, so take your time reading this.

Types of Scripts
There are three types of scripts in mIRC.; aliases, popups, and remotes. Each one is comprised of different parts and has its own tab in the scripts editor.

Aliases
Aliases are user-defined commands that stand for a set of one or more commands. Aliases are usually used to simplify everyday IRC tasks, such as identifying your nickname. The syntax of an alias is:

An example of an alias placed in the aliases tab of your script editor would look something like this:

The first part of the alias is hello. This is the alias' name. You would type the command /hello in the command line. The say Hi, I'm $me and I am an mIRC user. part is the command that is executed when you type /hello. Typing /hello and pressing Enter would result in the line showing up in the current window saying "Hi, I'm mynickname and I am an mIRC user."

One important thing to take note of is that I didn't use a / before the alias name or the command. This is unnecessary in the scripts editor. mIRC prefixes every command in a script with a //, which runs every command and evaluates any variables or identifiers in the command automatically. So, mIRC would treat both of these the exact same way:

Multi-line Aliases
mIRC requires anything spanning multiple lines to be enclosed in brackets ({ and }). For example, the alias hello that we had above could use /say twice. This could be accomplished using this code:

WARNING: Another method of doing multi-command blocks of code in mIRC Scripting is called piping, where a pipe character (|) is stuck in between the two commands, such as /echo hi! | /echo goodbye! This makes hard to read code, takes mIRC longer to process, and in general is bad coding practice. Use it sparingly.

Function Key Aliases
Function keys can also be given functions using aliases. Enter the following script in your script editor under Aliases.

Now push F1 on your keyboard. You should see a little dialog box pop up asking for your nickname and password. Enter a nickname, and a password for NickServ if you have one, and hit enter. The script should try and change your nick and identify you to NickServ. Note that depending on your network, you may not have a Nickname Service.

If 12 Fkeys aren't enough for you, well, you can assign up to 36 commands to Fkeys. Use c or s behind an fkey to make the alias work for the key combinations "shift + FX" or "Ctrl + FX."

See the s before the F1? It's the only thing that changed since the last example. However, instead of pressing F1 to activate it, hold shift and press F1. The same thing should happen as last time.

One more notable thing about function key aliases: you can can use them on the command line by typing the name of the alias, like any old alias name. For the alias we made, you would simply type /sF1.

Aliases in Remote Scripts
Aliases also serve a much more important purpose than simply doing a set of commands. Aliases in remote scripts can be used to shorten code and reuse a certain set of commands over and over, which makes writing code a lot easier. Aliases change their syntax a bit when in remote scripts.

To do an alias in a remote section, it must have the <tt>alias</tt> prefix. For example, the command I just made above would now look like

The alias prefix is the only thing that changes. Running the alias still works the same; type <tt>/hello</tt> to see the lines of text on the screen.

The real advantage of putting an alias inside a remote script is being able to use it repeatedly. For example, maybe you have an alias that increases a number three times. Technically, you can use the <tt>/inc</tt> command to do this, but for the sake of the example, we'll make our own alias.

See how I used the <tt>incnum</tt> alias three times? If this was a longer script, I could have saved myself a lot of time and typing by using aliases multiple times. People familiar to other programming/scripting languages will notice that aliases, in this respect, are similar to functions or subroutines that can be recycled.

Local Aliases
If you only want a command to be able to run in one script, or it would overwrite a command built-in to mIRC or another script, you can do <tt>alias -l</tt> in front of the alias name. The <tt>-l</tt> is a switch that tells the alias ONLY to work when called from a script inside that remote file. Let's take our previous example and add a local alias.

Now you cannot use <tt>/incnum</tt> from the command line or from other scripts, but the alias <tt>/incnum3</tt> CAN call it.

Recursive Aliases
mIRC cannot call an alias from inside itself. For example, this code would not work:

You cannot use <tt>/echomyname</tt> recursively inside itself. You CAN call it from another alias, however.

That would work, although it would loop forever, and most likely crash mIRC. Crashing programs is generally a bad idea. And it's quite embarrassing for you when your own program locks up in an infinite loop. So don't do it.

Now, there is one caveat to this recursive alias business. Say you wanted to write over an alias with a custom one of your own. When you call an alias from inside itself, and it has a built-in mIRC version, the alias will call mIRC's version. Take a look at this example:

Let's say you wanted to overwrite the kick alias to say how many kicks you've done. You could do <tt>/k</tt> from now on. Or, using the knowledge that mIRC can't recurse aliases, you could do this:

This will increase your kick count and kick the user you want from the channel, WITH the Total Kicks message. This comes in very useful in more advanced scripting, especially when making themes for full scripts.

Popups
Popups are user-defined context menus that show up at certain places in mIRC when you right-click. There are five popups you can customize; one on the Menu Bar, one in the status window, one on the nicklist, one in channels, and one in private messages.

Making Menus
Open your scripts editor to the Popup tab. I'll be using the Channel tab for the purposes of this book. To define a simple menu item, the syntax is:

So, to make a simple menu item that would change your nickname to "mIRCUser" you could do this:

Submenus
Now right click in any channel. You should see an option saying "Change Nick →" appear. Click it. Your nick, provided it isn't in use, should change to mIRCUser. But what if you have more than one nickname you like to use. Maybe you have the nicknames mIRCUser, Cakeman, and Blackknight. You can add a submenu to this existing menu.

Now, right-click in the channel again. You should see a menu looking something like "Change Nick To →". If you hover over the menu, you get three choices; mIRCUser, Cakeman, and Blacknight, all three of your nicks. You can even make submenus inside your menus.

Multi-Line Menus
But what if your server has a Nickname Service and you identify with your nicks, like in the fkey alias example? Well, popup menu definitions can have multi-line sections just like other parts of scripts using { and }.

Nicklist Menus
Making menus in a nicklist is relatively similar to making regular menus, except you need to specify which nicklist nick is being affected. This is specified by the identifier <tt>$1</tt>. Take note that these menus go under the Nicklist view in the Popups tab.

The identifier <tt>$$1</tt> in this case means the same thing as <tt>$1</tt>. It is the nickname selected on the nicklist (if there is one and you are in a channel). When you click on an option (kick, ban, or kickban), it will do that option to whatever nickname is in <tt>$$1</tt>. For example, the kick option kicks <tt>$$1</tt> from <tt>$$chan</tt> with the message, <tt>"You got kicked by mynick!"</tt>

Now, allow me to use this example to explain the double $$ prefix. When used with an identifier, this will stop a command from executing if the identifier returns <tt>$null</tt>. For instance, if you did not select a nick on the nicklist, <tt>$$1</tt> returns nothing and halts the command. As an added aesthetic bonus, if a double-prefixed identifier returns nothing in a menu item, the menu item will not show up. In this example, the entire menu would be hidden from view if you did not select a nick on the nicklist.

Nicklist menus also support everything regular menus support. You can use multi-line commands, submenus, etc. They work exactly the same. The only real caveat to using pop up menus that target a user in the nicklist is to remember to use <tt>$1</tt> or <tt>$$1</tt>.

Menu Bar Menus
Menu Bar menus work like the rest of the popup menus, except they appear in the menu bar at the top of the mIRC Windows under the "Commands" menu. You can also change the name of the Commands menu, if you'd like. On the first line of a popup file under the menu bar section, put the word <tt>Pie</tt>. Save the file and look at your menu bar. The menu should now be labeled <tt>"Pie."</tt>

Identifiers and Variables In Menu Items
Variables and identifiers in menu items are evaluated each time a menu is opened. As seen in the previous example, a nicklist menu like this:

Would have <tt>$$1</tt> evaluated each time you open then menu.

If you have variables set called <tt>%mytext</tt> and <tt>%mycmd</tt> then the menu item will appear clickable. If you only have <tt>%mytext</tt> set, the item will appear, but grayed out and disabled. If you only have <tt>%mycmd%</tt> set, The menu item will evaluate to <tt>$null</tt> and not appear at all in the menu.

The advantage of using identifiers and variables in popup menus is to make them more dynamic, as seen in the kick/ban menu example above.

Popups in Remote Files
Much like aliases, popups can be defined in remote files, in almost the same way. You simply use the <tt>menu [menuname]</tt> prefix, and then enclose the menu commands in brackets. <tt>Menuname</tt> is the location of the popup; either channel, status, query, menubar, or nicklist. Unlike the Popups tab, a menu under the Remote tab does not know where to open it the menu, so you must say it after the menu prefix.

This is roughly the same as the default menu in mIRC under the Popups/Channel tab, however, it is in a remote file now, with the menu prefix attached.

Menus in remote files can also have multiple menu names of where the menu should pop up. This one will pop up in a channel window OR a query window.

Popup Menu Styles
Menu Styles are used to change the look of your menu items. You can make a menu item appear checked off or disabled using menu styles. There are three menu styles you can use, using the <tt>$style</tt> identifier.

This is an example of a menu that uses styles to disable items if you are not connected to a server.

If mIRC is not connected to a server, both commands will be disabled. If you ARE connected, both of them will be enabled and have check marks (√) next to them.

$submenu
<tt>$submenu</tt> is a fairly advanced identifier that makes a dynamic submenu for a popup menu. It calls a custom identifier with the parameter <tt>$1</tt>, where 1 is a number that increases each time it runs through the identifier, until it stops. Sound confusing? Perhaps this code example will help.

The main thing to pay attention to here is how <tt>$submenu</tt> is used. <tt>$submenu</tt> Inserts the value 1 into <tt>$1</tt>, then increases that each time it goes through until it ends. So for <tt>$chan($1)</tt> in the custom identifier <tt>$_infochan</tt> will return the first channel you are on, then the second one, and so on, until you run out of channels.

Let's assume you are on #mIRC, #Windows, and #Scripting, and ChanServ is on your network. If you right-click in your status window, you will see a menu saying "Get Channel Info →" and three menu items in that menu's submen; #mIRC, #Windows, and #Scripting. Clicking on one of those will do a <tt>/msg chanserv info</tt> on the channel. This command returns information about a registered channel, if it is registered. The output would look something like this:

Menu Separators
To separate menu items, you can use a single '-' (hyphen) in between items.

Remote Scripts
Remote scripts make up the majority of what you will script in mIRC. They are a combination of aliases, popup menus, and event-driven blocks of commands. Unlike aliases and popups, you can have multiple remotes loaded at the same time. Each remote file usually contains one script. An individual script is a remote file (a file ending in .mrc or .ini) with related events, aliases, and popup definitions. An example of a script could be a script that makes you join a channel when you connect to a server, or manage a list of quotes people have said on IRC. The basic syntax of a remote event looks like this:

Remote Events
The <tt>*</tt> is what user level the event will trigger on. User levels are defined later in this section. Typically, events will usually have a user level of <tt>*</tt> or <tt>1</tt>. <tt>*</tt> means the event will trigger on any level, and the <tt>1</tt> means it will trigger by anyone with a user level of 1 or higher (1 is the default level in mIRC, unless you change it, so this will also usually mean anyone). The <tt>event</tt> is the name of the event you are defining. Examples of events are Text, Action, Ban, Join, and Part. You should only have one type of each event in a script for them to work right. The <tt>parameters</tt> part of the event can be anything. It's usually match text, where the event takes place, both, or neither of them. Inside this event block are all the commands you want the script to do.

This is an example of one of the more popular remote events, and one of the easiest to understand. It triggers whenever someone says text that matches the matchtext. The matchtext in this case is <tt>*</tt>, the wild card symbol. This means it will match anything. The if-then-else statement in the event's body determines what text it matches. This is a better idea in practice when using events. Instead of using multiple events that match different things, using one event that uses if-then-else statements will ensure that everything is processed in the right order. In this case, the script checks to see if the word <tt>"hello"</tt> is in the text said, but only in channels. The <tt>#</tt> after the <tt>*</tt> is what determines where the event triggers. You can also specify a <tt>?</tt> for private messages only, and <tt>*</tt> to make it trigger in both channels and PMs.

This is another example of a remote event. This one has no parameters. The event simply triggers when you load the script it is in. When you load this script, it will display the line on your screen, <tt>"Thank you for loading my script!"</tt>.

One important thing to know about remote event scripts is that most of them do not work when you trigger them yourself. Some events do, like On Kick or On Ban, while others like On Text will not work when you say something in a channel with the script loaded. mIRC will generally say in the help file when you can or can't trigger it yourself. Otherwise, it's trial and error.

CTCP Events
CTCP Events are events that trigger when you get a CTCP (client-to-client protocol) from another client. A CTCP event can be used to override a default mIRC action for a CTCP event (with the exception of VERSION), but can also be used to make your own CTCP replies.

A CTCP event looks very similar to a regular remote event. However, instead of the <tt>On</tt> prefix, CTCP events start with <tt>CTCP</tt>. The <tt>*</tt> is still the same; the access level required to trigger the event. <tt>Ctcpname</tt> is the name of the ctcp the event should trigger on. This could be anything from a built-in CTCP event such as <tt>TIME</tt> or <tt>VERSION</tt> or a made-up event such as <tt>BLAH</tt> or <tt>HELLO</tt>. The location parameter, again, is the same as a regular event. <tt>#</tt> is a channel, <tt>?</tt> is a PM, and <tt>*</tt> is both.

This event will respond any time someone CTCPs you with the text <tt>"secretword."</tt> It will check and see if the word they gave matches the secret word. If it matches, the script will PM them saying so.

Using a variable (<tt>%secretword</tt>) as the matchtext for the CTCP event, you can change the secret word any time and shorten the code. Now, the script will only respond when they CTCP you with the correct word.

While you can't hide the original mIRC version reply itself, you can add your own reply to the standard one. This one will send a CTCP reply back using <tt>/ctcpreply</tt> to the person who CTCP'd you with your custom version reply, after the mIRC one.

By enclosing the matchtext in wildcards, this script will trigger any time anyone says the word <tt>help</tt> anywhere in the CTCP query, and msg them back.

Raw Events
Raw events are advanced events that trigger when you receive a raw numeric from a server. This happens when you send a query to a server using a command such as <tt>/whois</tt> and you get a reply back.

Unlike remotes and CTCPs, Raw events ONLY trigger in your client, when you receive raw numerics from the IRC server. This happens when you get a reply after sending a query to a server; for example, using <tt>/whois</tt> or <tt>/away</tt>.

This event replaces mIRC's default reply for Raw 431, the message you get when you fail to specify a target for a command like <tt>/whois</tt> or <tt>/nick</tt>. It silences the default reply using /haltdef.

You may know how to use remote events now, but they are only a small fraction of making remote scripts. Making the events themselves is simple, but there is a huge amount commands to put inside the events. This is the real challenge of mIRC scripting, and what the remaining bulk of this book will cover.

Variables
Variables are dynamic values that evaluate each time the script is run to a certain value. Variables are assigned a certain value and always return their current value when called upon. In mIRC Scripting, variables are untyped. This means that a variable can store any type of data; text, numbers, or any combination of the two. A variable starts with a <tt>%</tt> prefix. There are two kinds of variables; local and global.

Local Variables
Local variables are created during scripts, and do not overwrite other local variables or global variables of the same name. Local variables are destroyed after the calling script executes.

If you type <tt>/saysomething</tt> and hit enter, a box will come up asking, <tt>"What should I say?"</tt>. Enter some text and hit okay. That text will get put into <tt>%text</tt>, and then whatever is in <tt>%text</tt> will be echoed to the screen. <tt>%text</tt> will not exist after the script ends. Try typing <tt>//echo -a %text</tt> into the command line. You should get a <tt>* /echo: insufficient parameters</tt> error. This is because variables evaluate to <tt>$null</tt> if they do not exist.

Global Variables
Global variables stay around once they are set, until they are unset, unlike local variables.

When you connect to a server, the server will ask you what you want your nickname to be if the variable <tt>%connnick</tt> doesn't exist. Either way, it will change your nickname to whatever is in <tt>%connnick</tt>. Now, open your script editor and open the Variables tab. You should see a variable called <tt>%connnick</tt> with a value of whatever nickname you chose. You may also see other variables, if you have run other scripts. These variables are all global, and will stick around under the Variables tab and return a value, until you use the <tt>/unset</tt> command.

Notice the difference in this script? The variable <tt>%connnick</tt>, in a sense, will act like a global variable in this script because of the <tt>-u0</tt> flag in the <tt>/set</tt> command. <tt>-uN</tt> make the global variable unset after N seconds. However, if you specify 0 for N, the variable will unset when the script finishes executing. It is not completely like a local variable; other global variables can overwrite it, and vice-versa. However, it is still a way to make sure the script cleans up all its global variables when it finishes.

Mathematical Equations With Variables
There are two ways to perform mathematical operations on variables; the commands <tt>/inc</tt> and <tt>/dec</tt>, and the <tt>=</tt> (assignment operator).

This alias will take any number you give it, assign it to a variable, and increases it twice using <tt>/inc</tt>. For example, if you did <tt>/incnum2 7</tt> you would get the message <tt>"Your number was increased by two! You got 9!"</tt>

Now the <tt>/inc</tt> commands have changed to <tt>/dec</tt> commands. This will decrease your number by two. The same <tt>/incnum2 7</tt> changed to <tt>/decnum2 7</tt> would give you the number <tt>5</tt>.

This code snippet uses the assignment operator to perform math on the variable. The first thing this code does is check to see if you gave it three parameters. It makes sure <tt>$1</tt> is a number, <tt>$2</tt> is a mathematical operator (+, -, *, or /), and <tt>$3</tt> is a number. If they are all correct, the script then puts the two numbers into variables <tt>%num1</tt> and <tt>%num2</tt>. <tt>%num1</tt> and <tt>%num2</tt> have an operation done to them (whatever you put into <tt>$2</tt>) and reports the result. Doing the command <tt>/math 3 * 2</tt> would output <tt>6</tt>.

A simpler alias than the last one, this command simply takes the first number you give it and multiplies it by itself. <tt>/square 3</tt> will give you <tt>9</tt>.

Identifiers
Identifiers are similar to variables. They are dynamic values in scripts that evaluate when they are parsed in the script. However, unlike variables, they do not always return a static value that is the same every time. Like variables, they can evaluate to <tt>$null</tt>.

For example, one identifier we have used a lot so far is <tt>$1</tt>. <tt>$1</tt> evaluates to the first parameter, if any, passed to a command when it is run. However, this is not always in the same. In the example above, we could use the command <tt>/square 3</tt>. <tt>$1</tt> in this case is <tt>3</tt>. Let's change that <tt>3</tt> to a <tt>4</tt>. Now <tt>$1</tt> is <tt>4</tt>. Pass nothing to it, and <tt>$1</tt> will evaluate to <tt>$null</tt>.

Another popular identifier used is <tt>$chan</tt>. <tt>$chan</tt> returns whatever channel a script or command triggers in. Make sure you have two channels open. Go to one of them, and type <tt>//echo $chan $chan</tt>.The effect of this action is to print in the current channel(the first occurrence of "$chan")right the name of current channel(evalutate by the second "$chan"). Now go to a different channel and do the same command. Notice you still get the channel name. This is because <tt>$chan</tt> re-evaluates every time is occurs in a script.

Built-In Identifiers
Built-In identifiers are identifiers coded into mIRC. There are dozens of built-in identifiers, but some of the most used are <tt>$nick</tt>, <tt>$chan</tt>, <tt>$me</tt>, <tt>$1</tt>, and <tt>$+</tt>. Identifiers built-in to mIRC have priority over custom ones and cannot be changed or re-coded, unlike built-in commands.

Custom Identifiers
A custom identifier is an alias that can return a value. Custom identifiers take the form of a regular alias, but are used differently. They are called with the same <tt>$</tt> prefix as regular identifiers instead of the <tt>/</tt> prefix used when calling an alias as a command.

The script first starts off by again, checking to make sure the two parameters are valid numbers. Then, it returns the value of the two numbers added together. The proper way to use this is <tt>//echo -a $addnum(n1,n2)</tt>. If you type this as a command, nothing will happen. <tt>/addnum 1 2</tt> will return a value of <tt>3</tt>, but nothing will show up because it returns a value, instead of echoing it. You can change this, however, using the identifier <tt>$isid</tt>.

<tt>$isid</tt> returns <tt>$true</tt> if the alias was called as <tt>$addnum</tt> and <tt>$false</tt> if it was called as the alias <tt>/addnum</tt>. Combined with another identifier, <tt>$iif</tt>, we can determine if <tt>$isid</tt> returns <tt>$true</tt> or <tt>$false</tt> and take an action based on what the result is. If <tt>$isid</tt> is true, that means <tt>addnum</tt> was called as an identifier, and will return a value. If <tt>$isid</tt> is false, then <tt>addnum</tt> was called as an alias, and will echo a value to the screen. Try the command both ways now with <tt>1</tt> and <tt>2</tt>. Both times, you should get <tt>3</tt>

Custom Properties
You may notice that some identifiers have properties. For example, if you type <tt>//echo -a $chan(1).topic</tt>, the topic of the first channel you are on will display on your screen. <tt>.topic</tt> is the property of the identifier. You can add properties to your identifiers, too.

Again, using <tt>$iif</tt>, we can check the property of the identifier. If you use the command <tt>//echo -a $addnum(1,2).neg</tt>, instead of returning <tt>3</tt> you will get <tt>-3</tt>. This because the property <tt>.neg</tt> was used with <tt>$addnum</tt>.

'' Note: Built in identifiers to mIRC will take precedence over custom ones with the same name. You cannot re-script <tt>$chan</tt> to return <tt>42</tt>. mIRC will still return the name of the channel you are on.''

Comments
Comments are a very important part of coding when your scripts start to get very large and complex. You will hopefully remember tomorrow what your code did last night, but can you say you will remember what a line of code should do six months from now? Comments are lines of code that are ignored by mIRC's interpreter and can be used to remind you what a certain part of a script does. This is what the last example could look like if we commented it.

Single Line Comments
All the comments in this code were one line comments. One line comments start with either <tt>;</tt> or <tt>//</tt> and a blank space, then the comment. We could just as easily have used <tt>//</tt> for comments in that script instead of <tt>;</tt>. All one line comments end at the end of the line they start on.

Multi Line Comments
Multi line comments span multiple lines. They start wherever a <tt>/*</tt> is placed in the code and ends wherever there is a <tt>*/</tt> in the code.

Using multi-line comments, we achieved the same effect as the one line comments, but in one multi line comment.

Command Prefixes
There are three types of prefixes that are placed in front of commands, and one prefix placed before identifiers, variables, and operators.

Control Codes
Control codes are special characters that are placed in text to modify the look of text.

If you've made it this far, congratulations for making it through this long chapter! You can now make some basic mIRC scripts, and you should understand a few of the concepts required to script. If you're ready, you can go on to the next chapter.

Back To Top