From WikiChip
mirc/introduction
< mirc
Revision as of 14:57, 22 June 2014 by Zmodem (talk | contribs)

Template:mIRC Guide

This article focuses on the very basics of mIRC Scripting. The target audience is people with no knowledge, or very limited knowledge, of the mIRC scripting language.

Where does the code go?

All of your code, regardless of its type, should go in the Script Editor. To open the script editor press-and-hold the <ALT> key on your keyboard, and then tap the R key (<Alt>+R). Alternatively, you can go to the Tools Menu -> Script editor.

Below is a screen shot of the mIRC Script Editor:

Remote Editor

You will notice that there are five selectable tabs: Aliases, Popups, Remotes, Users, and Variables. Let's try and get you familiar with each one.

Aliases

Aliases are special commands that allow you to personalize the functions of mIRC. For example, as an mIRC user, you are most-likely familiar with the command /join. This command, followed by a channel name, allows you to join a channel when you are connected to an IRC network. This is an example of a built-in alias in mIRC (although we refer to the provided aliases as mIRC Commands).

Unlike the Remotes section, which also allows you to code aliases, custom aliases in the Aliases section do not need to be preceded by the word alias. Let's take a look at a very simple example:

myname {
  echo -a Your current nickname is: $me
}

If you were to place that code in the Aliases section and then either click File->Save, or click the 'OK' button to save and close the editor, you would have just created your first alias! You can use your new alias by typing the command /myname. mIRC will process the alias you have just created, and will then echo your current nickname to the window you typed the command in.

Keep scrolling below to find more information regarding coding aliases.

Popups

You've seen popups in mIRC already, haven't you? Of course you have! They are those little menus, such as the File, View, Favorites, etc menus at the top of mIRC. You may have also seen popups when you right-click on a status window, channel, or private chat window. You may have even seen some popups when you right-click on user names in the nicklist in a channel.

Well, mIRC allows you the awesome luxury of creating your very own popups! You can, alternatively, use a keyboard shortcut to open up the Popups section of the script editor as well: <ALT>+P. Again, this means to press-and-hold ALT on your keyboard and tap the P key.

Depending on whether you've coded some popups before, have a custom mIRC script, or you're using the default popups included in mIRC, you may or may not see code in the Popups tab. Like aliases, popups can also be coded within the Remotes section of the editor as well, although it takes a bit more code to do so (see the Popups page for more details on popups).

Remotes

The remotes section is the most powerful area of the script editor. You can code aliases, popups, user levels, and even variables into the remotes section. One of the biggest benefits of the Remotes section is the ability to listen for Events.

Events

The remotes section is also used to listen for events. Events are certain situations where you want mIRC to listen for a specific circumstance. All of the events that you wish to listen for, and or script, go inside of the Remotes section of your mIRC Script Editor (review under 'Where does the code go?' above to find out how to open the mIRC Script Editor window).

Without going into too much detail, for now don't worry about understanding the following, but let's just say you want mIRC to trigger an event when someone says your current nickname on a certain channel. The following would be an example of that event.

ON *:TEXT:$me:#: {
  echo -a $nick just said your name!
}

Events almost always begin with an ON event listener activator, followed by the event you want to listen for. The * character tells mIRC that you want to listen for all access levels (more on those in the Users area). TEXT lets mIRC know that you want to listen for the event in which someone types text to you. The $me parameter fills in the area for the text you want to listen for. In this case, we've specified that we want this event to listen for when someone types your name in a channel. The next parameter is the # listener, which means that you want to only listen for this event on channels.

Do you see how simple that is? If not, don't worry! With much practice, you'll start to easily fall into the code practices of mIRC.

Let's move on and start learning some elementary knowledge of mIRC scripting.

The very basics

Before we can do anything productive, we must understand some of the most basic parts of a script. Therefore, let's take a few moments to help familiarize you with the following key components:

Statements

Every script is composed of one or more statements. A statement describes something that needs to happen. Each statement must go on its own line, or it must be separated by a pipe, which is the '|' symbol. For example, the following two are the same:

Piping
statement 1 | statement 2 | statement 3 | statement 4

and:

Code blocks
statement 1
statement 2
statement 3
statement 4

What's with the slashes?

If you asked any script related question in a help channel, you were probably told to type some code that begin with a forward slash. In order to execute any code from the mIRC editbox (the box where you normally type all of your text), you must prefix the code with at least one forward slash.

The difference between using one or two forward slash is that with one, the rest of the line is not interpreted as a command, we will discuss this difference later.

We usually refer to commands by prefixing them with a slash.

/echo command

The most common type of statements are commands. Commands are a way to tell mIRC to perform a basic operation. By far the most common command you will be using is the /echo command. The /echo command simply prints text to the screen. Every echo command prints on a line of its own.

Let's dive right into an example! Type the following code into your editbox:

//echo Hello World!

When you are finished typing this echo command, hit your Return or Enter key on your keyboard. You should see the following result (Note: Your editbox will not have anything in it, it will be cleared once you press the Enter or Return key):

Hello World!

Hello edit.png

Recall we said earlier that multiple statements can be combined by using the pipe '|'? Let's print 3 lines to the screen using the echo command and some pipes. Type the following code into your editbox (Remember to hit the Return or Enter keys from now on):

//echo Scripting | echo Is | echo Fun!

You should hopefully see the following results:

Scripting
Is
Fun!

Fun edit.png

You will notice that after the first //echo command, once we've piped, we do not need to type anymore slashes; this is because mIRC interprets the rest of the statements via the first initial slashes. If you use one slash here, "Scripting | echo Is | echo Fun!" will be echoed, because the pipes have not been interpreted. We usually refer to this as 'evaluation', we will discuss it later.

Let's make it into an alias, shall we?

Aliases are used to describe any piece of scripting code that can be reused. Aliases have a name by which we can refer to them, and they also have a body. The body of an alias contains a statement, or a list of statements, that execute(s) when we call that alias. You can think of aliases as commands, much like the echo command is. All aliases can be called from your edit box by preceding them with one or two forward-slashes, just like commands.

Basic Alias

A basic alias will look something like this:

alias name <statement>

We can tweak the statement of this alias just a little in order to perform multiple statements through the use of piping:

alias name statement 1 | statement 2 | statement 3

Notice that with the piping, this alias now performs multiple actions.

Let's make the code we used above to print "Scripting Is Fun!", all on separate lines, and call this new alias "fun":

alias fun echo Scripting | echo Is | echo Fun!

Before we continue, let us note a few things regarding the above code:

  1. The two // were removed; we only really need one or two forward-slashes when we want to execute code directly from the editbox. Using slashes in your script editor adds nothing but clutter.
  2. Because we used the alias keyword, the code must go in the Remote Tab of the script editor. In order to use that code from the aliases tab, you must remove the "alias" keyword. The rest of the code stays the same.

Remote tab

Fun alias 1.png

Aliases tab

Fun alias 2.png

Note: When you want to execute an alias, you would refer to it as wanting to call the alias.

To call on our alias fun, all we have to do is use its name, preceded by a forward-slash in any mIRC editbox:

/fun

Note: Two forward-slashes will also call it, but for now, let's only use a single forward-slash

That should print our text again:

Scripting
Is
Fun!

A block of code:

When we have a group of related commands, we call it a block of code. Most scripts, however, are not as short as our example and putting it all on one long line, or piping, is messy. We can use the second format we talked about, which is storing each statement on a new line, in order to keep our code clean and easily editable. The way that we accomplish the task of creating a code block is to tell mIRC "this block of code belongs to this alias". We do that by enclosing the block of code in a pair of brackets:

alias name {
  statement 1
  statement 2
  statement 3
}

A few notes about the language limitations:

  1. The opening bracket ({) must be on the same line as the alias keyword
  2. The opening bracket must not touch anything
  3. The closing bracket must not touch anything else
  4. The closing bracket must be the last part of the block of code

Right Examples

alias example { echo hello! }

Note the spaces before and after both the opening and closing brackets. This is a good example of a proper code block.

alias example {
  echo hello!
}

The initial opening bracket is on the same line as the alias name, and it has proper spacing before itself. The statement within the block is also perfectly executed, and the closing bracket is on its own line. This is another example of a proper code block.

Wrong Examples

alias example{echo hello! }

The opening bracket is touching the "example" and "echo".

alias example { echo hello!}

The closing bracket is touching the "hello!".

alias example
{
  echo hello!
}

The opening bracket must be on the same line as the "alias" keyword.

Using a block of code

Let's reuse the fun alias from before. However, this time we will put each statement on its own line:

alias fun {
  echo Scripting
  echo Is
  echo Fun!
}

Notice how this is a perfect example of a Good code block, much like the sample that we viewed above? If you are noticing the repetitiveness of the echo command, don't worry, in later examples we will show you tricks on how to get around repeating certain reused commands in your code.


Comments

Comments are normal, readable text that can be placed inside of your script, and they are a good practice to help better explain to other scripters what's going on in your code. Technically speaking, a comment can say whatever you want it to say, and they are ignored when the program is executed, meaning they have no effect on the actual behavior of the code.

All comments are preceded by the ; character, which is the semi-colon.

Single-line Comments

The most basic comment is the single-line comment, which has the following syntax:

; This is single-line comment.

Note on how the comment begins with a semicolon and ends at the end of the line; anything on this line is now ignored.

Here is another basic example of a single-line comment:

alias fun {
  ; print "Scripting"
  echo Scripting
  ; print "Is"
  echo Is
  ; print "Fun"
  echo Fun!
}

Fun comment.png

Multi-line Comments

The second type of comment is the multi-line comment. A multi-line comment can, as its name suggests, span multiple lines. Multi-line comments are enclosed between the /* & */ characters. The syntax for a multi-line comment is:

/* This is
  a multi-line
  comment!
*/

Your text must go between the /* and the */ in order for it to be treated as a comment.

A few notes about the language limitations:

  1. Text may touch the opening /*
  2. The closing */ must be on a line of its own

Right Examples

/* testing
   out
   a multi-line
   comment
*/

or

/*
   testing
   out
   a multi-line
   comment
*/

In both of the above examples, the opening comment parameters are properly executed, the lines are spaced out and the closing parameters are by themselves. These are both examples of proper multi-line comment blocks.


Wrong Examples

/* testing
   test */

The */ is not on a line of Its own.


/* comment */

The */ is not on a line of Its own.


Identifiers

Main article: aliases - mIRC


Before we wrap up this tutorial, we need to talk about one last concept: $identifiers. All identifiers have a dollar symbol sigil and have the following syntax:

$name
;or 
$name(<argument 1>, <argument 2>, <argument 3>, ...)

Identifiers are very similar to commands except that we use identifiers when we want a value.

Commands seperate their parameters/arguments by space, while identifiers use a comma. Both commands and identifiers are also reffered to as alias(es): you create a custom command/identifier by using the "alias" prefix (in the Remote section of the script editor only)

For example, if we want to print out your current nickname, we would use the following code:

//echo -a $me

Evaluating/Interpreting

Here we used two slashes. This indicates to mIRC that it must interpret the line. In the script editor, you don't need any slash, lines are always executed as though two of them were used, the difference only applies when you execute commands from the editboxes in mIRC.

Interpreting or we also say 'evaluating' a line or an expression means the line/expression is processed according to the language's semantic. Just like commands, identifiers are just functions, evaluating an identifier is the action of calling that function and replacing the identifier with the value returned by the function.

So
//echo -a $me
Here the value of your nickname is retrieved by the built-in identifier $me and is inserted in the line; if your nickname is Clickhere, the line becomes:
//echo -a Clickhere

In general we use the terms evaluating/interpreting for the whole job done on a line, there are a few others things mIRC is doing besides grabbing identifiers's values and replacing them accordingly.

For example, variables are also special and need to be evaluated the same way as identifiers are to produce the value hold by the variable.

Another example, piping, which we saw earlier, is also working because the pipes characters are special and are interpreted in a special way: they are the delimiter for commands on one line.

$rand()

One of the most common operations we use is to generate random numbers. This is where the $rand() identifier comes into play; it can generate a random number between a given range. The $rand() has the following syntax:

$rand(<low>, <high>)

Given both low bound and high bound number values, $rand will return a random number in between, and including, the two numbers. For example:

alias random {
  echo The dice rolled on the floor .... $rand(1, 6)
}

Here is what we got when we called out /random alias a few times:

Random example.png The results that mIRC generates for you will be different than the ones listed above in the screenshot; this is the nature of the $rand identifier.

On your own:

Below are a very few, basic commands that you can use to experiment with in a safe manner. Go ahead, try them out!

Colors:

Just like you can add colors when you talk by typing CTRL+K on your keyboard, and then selecting a color number, you can do the same in your aliases. Here is a simple example:

alias example {
  echo -a �3This �4is �6a �10cool �15example�1.
}

You may have noticed that we added a strange new thing, -a. The -a is called a switch; switches slightly alter the way a command behaves. In the case of the /echo command, the -a switch specifies that we wanted the command to echo to the current active window. There is another switch, the -s switch, which can be used to tell the echo command to print to the status window instead, regardless of which window you have open.

Below is an example of how we use the -a switch:

Color example.png

Will produce:

This is a cool example.
//echo -a The number �42� is even.

Will produce the following result:

The number  is even.

Notice that the number is not showing. That's because it was considered part of the color number '42'. Prefixing the color value with a zero will fix this issue:

//echo -a The number �042� is even.

Will produce the following result:

The number 2 is even.

Actions

Actions are very similar to your normal channel messages, except that they are displayed in a slightly different manner.

; This is good for the channel you are in right now:
me <message>
; This is good for any channel you specify (as long as you are in that channel)
describe <#channe> <message>

For example:

alias feel {
  me Feels Happy!
  me Leaves
}

The code should produce something like this (Your name will obviously be different):

* @FooBar Feels Happy!
* @FooBar Leaves

Action example.png

If we wanted to specify a channel, we could have used:

alias feel {
  describe #MyChannel Feels Happy!
  describe #MyChannel Leaves
}

Where do we go from here?

By now you should be grasping the basics of mSL, or at the very least beginning to understand how things work. It is highly recommended that you take it upon yourself to play around with the code on your own, in order to see what happens when you change different things around.

Next up are the aliases. If you feel comfortable with aliases, feel free to move on to variables.