mScriptBox Tutorial
How To Make A mIRC Bot

Written by Merlin
Based on the original tutorial by DuffJ.

Table Of Contents

  1. Introduction
  2. Creating A New Bot
  3. A Simple Greet Message
  4. More Complex Commands
  5. The Aliases Section
  6. The Popups Section
  7. The Remotes Section
  8. Other points of interest
  9. Lists of useful stuff
  10. Places to go
  11. Example Protection Script
  12. Conclusion
  13. mIRC Bot FAQ - Frequently Asked Questions


1. Introduction  Back to Top

If I wrote this section in full it would take me years. There is so much you can write into a bot, and you can only learn how through asking people, reading FAQ's like this one and doing it for yourself. So anyway, this FAQ will try to take you through the basics of making your own bot.

Nearly all the features of a bot are contained in three sections of mIRC: The aliases section, which is a feature for condensing many long commands into one short word, which when typed will run all the commands inside it; the popups section, which contains custom menus that appear when you right-click in different windows, and also on the menu bar; and the remotes, which tell the bot what to do when something happens (this is the main and most powerful section)

This Tutorial has been revised to deal with mIRC 6.x

2. Creating a new bot  Back to Top

Here are first steps before you can actually start scripting a bot:
  1. Create a new directory called bot (or something like "bot")
  2. Copy mirc32.exe/mirc16.exe (Note: if you have mIRC 6.x it's mirc.exe) into the new directory
  3. Rename the mIRC executable file to mircbot.exe (if you really want to)
    Note: The renamed mIRC excutable must start with mirc
  4. Run the new program ie. mIRC32.exe or mIRC.exe or bot.exe from that directory
  5. Remember that this bot will be almost entirely empty (no little enhancements) so all commands eg. connecting to servers will have to be typed in by hand. Also remember that this new "copy" is now a bot, even though it does NOTHING at the moment. It is a bot BY DEFINITION.
  6. Set your bot's mIRC options up (eg. in the options section)
  7. You will also need to create a "new" script section in your bot's remote section. Simply open the remote section (by hitting ALT+R) and choose "new" from the "file" menu.

NOTE: Instead of Steps 1-3, I always would prefere a new install with the latest mIRC from http://www.mirc.com/get.html.
That would make sure I have all the files needed, like the servers.ini and the mIRC Help file.

You are now ready to start putting in "scripts" for this bot to work properly. This means that you are going to type in lines of stupid looking code which mIRC will something cool with, that's all a script is! For those of you who know about scripts, a bot is simply a collection of scripts, most or all of which should be controllable by a remote user. That's why we use the "remote" section... (doh)


3. A Simple Greet Message  Back to Top

Let's start off by making your bot say "Hello" or something whenever someone enters a channel.

For this we'll use the "Remotes" section and the "Popups" section. Since you also want your bot to be remote-control (that is the whole point of a bot) we'll add some script so that you can turn the "auto-greet" on and off just by msg'ing the bot. First, open the remote section, and type (or copy and paste) the following into the large text box:

#greet on
on 1:JOIN:#:{ .notice $nick Hi there, welcome to $chan !! }
#greet end

(We'll talk about lines 1 and 3 in a minute, concentrate on line 2 for now)

This tells mIRC that whenever someone joins a channel, to send that person a notice saying "Hi there, welcome to #name_of_channel !!"

The "on" bit tells mIRC that this is an EVENT. It's not really important to know the difference until we get onto other remotes later.

The number 1 is called a user level. All people automatically have a user level 1 unless you set them to a different level. You can also change the DEFAULT user level to a different one, if you don't like 1. User levels determine what events are accessed by various people. We'll come to that soon.

The "JOIN" bit tells mIRC to do the task whenever someone joins a channel. There is a large variety of these EVENTS, including JOIN, PART, TEXT, KICK etc...

The # means any channel (You can specify a name eg. #chatzone if you like, which means that only people who join #chatzone will get the message. You can even specify more than one channel, by separating them with a comma).

The .notice bit tells mIRC to send the user who has joined a NOTICE. The full stop in front of the command makes the notice send invisibly, as it is a nuisance to see a notice being sent every time someone joins a channel... If you don't get me, try leaving out the full stop and see what happens.

The $nick and $chan bits are called identifiers, which refer to certain values depending on how and when the task is carried out:

$chan means the channel that was joined, and $nick is the nickname that joined the channel. These are very useful, as nearly all the features of your bot will be triggered by a $nick doing something, usually in a $chan. Understand?

Now we will set an option to easily turn the greet message on and off, in the popup section.

Open the popups section and click "Status Bar". This option will appear in a menu in the status bar. Type these two lines into the large text box:

Turn greet message on:/.enable #greet
Turn greet message off:/.disable #greet

This tells mIRC to enable or disable the part of remotes called #greet (lines 1 and 3 in the last part tell mIRC where #greet starts and ends)

The final thing we must do is turn the auto-greet on and off by msg'ing the bot and TELLING it to turn it off. This is where the userlevels come into play, with a few more remote events.

Type this into your script section of the remotes, on 2 blank lines underneath your current 3 lines:

on +100:text:autogreeton:?:{ .enable #greet | /msg $nick The auto-greet is now switched ON }
on +100:text:autogreet off:?:{ .disable #greet | /msg $nick The auto-greet is now switched OFF }

This is translated by mIRC like this:

when someone with user level 100 sends me a msg saying "autogreet on", I must switch the group ON and msg that person to let them know what I've done.

when someone with user level 100 sends me a msg saying "autogreet off", I must switch the group OFF and msg that person to let them know what I've done.

For those of you familiar with these type of lines, these 2 lines shouldn't be hard to figure out. Here's the STEP BY STEP guide to the lines:

As before, the "on" means that it is a remote EVENT, triggered in these lines by "text" somewhere.

The "somewhere" is the question mark after the text. # means "in a channel" and ? means "in a msg". ( by the way, * means "in either")

The actual text that triggers these lines is "autogreet on" and "autogreet off"

The 100 is a USER LEVEL. We don't want your bot to be controlled by just anyone, so the lines that control what it does can only be triggered by someone with a higher user level, in this case 100. I like to use 100, but some people may want to use a different number... Now do you see how useful user levels can be? You should only give access to your bot to someone with a very high user level, or anyone will be able to change what your bot is doing. Similarly, you can create a BLACKLIST, which is for your enemies. You can give people you don't like a certain user level (I use 666) and then you can have nasty EVENTS which trigger when a member of the blacklist joins a channel.

To add and remove user levels, we use the /auser and /ruser commands. There are others such as /guser, but they make use of mIRC's Internal Address List, which we'll come to later. To cut a long story short, /auser and /ruser are the simplest.

/auser <level> <nick> will give a nick a certain userlevel. The one you want to use is:

/auser 100 Merlin (please, put YOUR OWN nick instead of "Merlin". You want your usual nick to be in there, NOT the nick of the bot. That would be pointless. If YOU want to access the commands, YOU must have a high user level in the eyes of the bot.

A word of warning about user levels...

User levels work on the principle that anyone with that level OR HIGHER can access that particular EVENT. Now then, since my MASTER level is 100 (that's in my bot) and my BLACKLIST level is 666, simple Math should tell you that 666 is higher than 100. SHOCK! How can we avoid this, oh master Merlin? Well, it's simple. You can use various "flags" (a geeky way of saying characters) in front of user levels to say more preciscely what user levels it responds to. The most commonly used one is the plus sign +, which tells mIRC to ONLY allow user level 100 to access the event.

It's very handy, as you'll see later on.

There's a new command in there, /ENABLE and /DISABLE, which make use of the 1st and 3rd lines of the original auto-greet. When the group is DISABLED or OFF, the commands inside the group (#greet in this case) will be totally ignored. This is basically a switch to turn your bot's commands on and off.

Another new bit is that there are 2 parts to the bot's response to this EVENT. First, it ENABLES or DISABLES #greet on whether it is told "on" or "off". Then, it msg's the user who told it to do that, and tells him/her(/you in this case) what it has done. One EVENT can trigger MANY commands, and this is where the difference between the advanced bot and the simple bot begins to be seen.

Multiple commands can be separated by the pipe character | (find it above your backslash key).

You can have 2, 10, or even 50 commands for one EVENT, with each one separated by |. Another way of separating commands is to put them on separate lines, with curly brackets joining them to the EVENT. You'll see examples of this later.

Well, phew! We've actually got something done! Now you can use your bot to send an automatic message to a user when they join the channel, which you or others with userlevel 100 can turn on and off by msg'ing the bot with "autogreet on" and "autogreet off". The bot will even talk back to you, telling you about this wondrous thing that you have done ;).


4. More Complex Commands  Back to Top/font>

Do you think you are ready to experience more complex commands? DO YOU? oh, ok then...

Let's now try adding something called "text flood protection" to the bot. This will involve more lines and more complicated commands than a greet message. It will mean that a user typing in too much at one time will be kicked, as they will be FLOODING the channel. Add these lines to your script section:

#textflood on

ON @1:TEXT:*:#:{ .auser 200 $nick | /timer2 1 3 .ruser $nick }

ON @+200:TEXT:*:#:{ .timer2 off | .auser 201 $nick | .timer3 1 3 .ruser 200 $nick }

ON @+201:TEXT:*:#:{ .timer3 off | /auser 202 $nick | /timer4 1 3 /ruser 201 $nick

ON @+202:TEXT:*:#:{ .timer4 off | .auser 203 $nick | .timer5 1 3 .ruser 202 $nick }

ON @+203:TEXT:*:#:{ .timer5 off | .auser 204 $nick | .timer6 1 3 .ruser 203 $nick }

ON @+204:TEXT:*:#:{ .timer6 off | .ruser $nick | .kick $chan $nick Text Flood Detected }!

#textflood end

Now put 2 lines in your popups "Status Bar" section to turn this on and off:

Turn text flood protection on:{ .enable #textflood }

Turn text flood protection off:{ .disable #textflood }

Also, put 2 lines as before in your script section:

ON +100:text:textflood on:?: { .enable #textflood | .msg $nick Text flood protection is now switched ON }

ON +100:text:textflood off:?:{ .disable #textflood | .msg $nick Text flood protection is now switched OFF }

Well, you can understand the popups and the on/off events, but what's all that crap inside #textflood? You can see that it is switched on and off by the popups or events, so better leave it off for now! *GRIN*

However, upon looking closer there are loads of things you actually do understand, and if you don't you can easily find them in the mIRC help file...

The @ flag means that the events only trigger if the bot is OP of the channel. It just saves a whole lot of error messages when the bot tries to kick a flooder and can't if he isn't op.

The /timer command is interesting, for more help see the help file (doh). In this case, it removes a certain userlevel from a nick after 3 seconds. It is used a lot, because this is only triggered by someone writing 6 lines in 3 seconds, usually a flood (if you are picky you can work out using the timers how long a user actually has). If they were kicked every time they wrote 6 lines, I think we both know they'd be more than pissed off.

STEP BY STEP:

When a normal user (level 1) types anything in channel where the bot is op, it gives him/her userlevel 200, and removes it after 3 seconds. If they write something else suring the 3 seconds, they are given level 201 and the timer is reset. This goes on until they type for the 6th time, when they are kicked from the channel. Not hard, is it?

 


5. The Aliases Section  Back to Top

The aliases, as described in the mIRC help file, are basically where you type long commands and run them with one short command, like a batch file really. For instance, I could type "/poo" then a lot of long commands into the aliases section, and run the commands just by typing "/poo"

To create a new alias, type "/name_of_new_command" (without the ") into A NEW LINE in the big text box, then type the commands you want "/new_command" to do when it is typed. Here is an alias for adding a user to your userlist then telling the person what user level he has been set to.

/userset {
  .auser $$?="What userlevel do you want to give?" $$?="Who do you want to give it to?"
  .notice $nick you have been given user level $1 in my list. Enjoy it!!
}

 

You can see the curly brackets coming into evidence here. The alias starts with { and ends with }. Anything between the 2 brackets is considered part of that alias. NB, this is a major and common booboo, forgetting curly brackets or not having enough. It is detailed in the troubleshooting section.

Every time you type "/userset" it will bring up a user level box and a nickname box, type in a level and a nickname and it will give that nick a user level, displayed in the "users" section.

Since mIRC doesn't know what PARAMETERS (um, I don't know the exact meaning, look in a dictionary) it is being given, because you have used $$?, it brings up a DIALOG BOX with the text inside the double-quotes. It does this twice, for userlevel and nick.

NB: everything with $ in front is considered a PARAMETER by mIRC. $$ is useful, because it means mIRC will not execute the line unless it has all the necessary parameters.

Now then, I hear you cry, what good does this do? This is the beauty of aliases with bots:

You can type an alias ONCE into the aliases section, then use it ANYWHERE, in remotes is the best place. Here's an alias, with a remote events after it using the alias:

  /userset {
  .auser $$1 $$2
  .notice $$2 You have been given level $$1 in my userlist! Enjoy!
}

ON +100:text:add user*:?:{ userset $$3 $$4 }

The star after the "user" means that the event will be triggered, WHATEVER is typed after "add user". Make sure you do it properly, "add user I hate broccoli" will severly confuse your bot and cause it to add weird userlevels. The proper format should be: "add user 50 Merlin", so the /auser command in /userset will work properly. The remote event executes the "/userset" command, using $$3 and $$4 as /userset's $$1 and $$2. Try it out, you'll see what I mean.

There is a different method to add aliases. Instead of putting them in the alias section you also can add them to your remote file. Here is the syntax:

alias userset {
  .auser $$1 $$2
  .notice $$2 You have been given level $$1 in my userlist! Enjoy!
}

The only difference is the preceeding word alias which tells mIRC the following is an alias. The usage is exactly the same - but it allows you to add you aliases into your remote file instead of creating an alias file.

You can also make this alias to be "local" by just adding the "-l" option:

alias -l userset {
  .auser $$1 $$2
  .notice $$2 You have been given level $$1 in my userlist! Enjoy!
}

This exactly means the alias is only known to the routines in the remote file where this alias is placed - no other file will know about it.


6. The Popups Section  Back to Top

 

The popups are a set of boxes that turn lines in them into various menus in mIRC. There are 5 popup menus in mIRC, the most recent mIRC to be released at the time of writing this:

Status window, chat/query window, channel window, nicknames list, menu bar. Type lines into these boxes, assign commands to go with the lines and they will appear in a menu when you right-click in that window. Clever huh? I'll show you some good examples of this as we go on, you've already seen examples with the auto-greet and text flood. Popups follow much the same format as aliases, except the name and the commands are separated with a colon instead of a space, probably to allow you to type names with spaces as a list item. By the way, popups can run aliases as well. Oh yes! :)

Another feature of popups is CASCADING MENUS. This is a geeky word for menus with other menus inside, or "sub-menus". To do this, you use dots in front of the popup lines. It's simple to do, but hard to explain, so I'll let Khaled do it in the mIRC help file. You won't be using popups much as you become more advanced with your bot, because you should really have no need for them. All you should be doing in your bot is writing code...


7. The Remotes Section  Back to Top

The mIRC Remotes section contains 3 sections: users, variables, and scripts, which can be toggled between by using the "view" menu option.

The users section contains all the users (surprisingly) and their userlevels. In my bot, I am listed as level 100

100:Merlin

so that I can use the many remotes I have for level 100, the master level.

The variables section contains things called variables. These are useful in that you can set a variable using the /SET command, and then use that variable over and over again. All variables start with a percentage sign % and are one word long. They then have a VALUE, which can be any combination of words and numbers.

The scripts section contains the real meat of the remotes. You can "file/load" as many script files as you like. There are 3 types of remote script lines: CTCP's, EVENTS (which we've looked at) and RAWS.

CTCP = client to client protocol (you don't NEED to know that)

CTCP messages are sent from one user's software to another, and the software usually replies directly without you knowing about it. All that appears normally is a little red message saying PING or something. However, this will soon all change with CTCP remotes!

The format of a CTCP line is mostly the same as an event:

ctcp 1:ping:{ .notice $nick go away!!!! | halt }

When someone sends you a ctcp PING, it will notice them with "go away!!!!" and prevent the normal PING reply from being sent. This is another way of sending commands to your bot:

ctcp +100:textflood on:{ .enable #textflood | .notice $nick Text flood protection enabled }

Raws are probably the most advanced, and they deal with raw messages from the IRC server you are on. When you type /whois Merlin, you are seeing what the server tells you about Merlin. Each reply has its own little number, which mIRC can respond to:

raw 312:*:halt

This will prevent you seeing any 312 messages. Incidentally, raw 312 tells you what server someone is on when you do /whois, so it's not really that clever to turn it off unless you have a reason :)

To find a long list of raw replies, check the RFC1459 file. It was written by the creators of IRC to tell people about the technical stuff of IRC. Don't try to read it all, it's HUGE.
To find info about a certain raw event you might look at the RAW Events page.
Another alternative is the RAW Events Help file, an easy to read version with all the numbers in some sort of comprehensible order, written by my good friend the Jeepster (op in #mIRC)


8. Other Points Of Interest  Back to Top

You can make your bot do ANYTHING completely remotely. You can even run the program, make it connect to a server etc. without ever even looking at the screen. This is via a method called DDE, where you can communicate remotely with a program. Look in ddefaq.hlp for more information on this.


9. Lists Of Useful Stuff  Back to Top

Here are all the lists of things in mIRC that I like to keep next to me when I'm scripting. You should leave this text file open or just print it out to make use of these lists. 

Colour codes:

 00  White
 01  Black
 02  Blue
 03  Green
 04  LightRed
 05  Brown
 06  Purple
 07  Orange
 08  Yellow
 09  LightGreen
 10  Cyan
 11  LightCyan
 12  LightBlue
 13  Pink
 14  Grey
 15  LightGrey


 

Color codes:
Copy and paste that into your alias section, and type /colors to activate it.

colors echo -a Colorbar: $chr(3) $+ 0,0 $+ $chr(3) $+ 1,0 0 $chr(3) $+ 0,1 1 $chr(3) $+ 0,2 2 $chr(3) $+ 0,3 3 $chr(3) $+ 0,4 4 $chr(3) $+ 0,5 5 $chr(3) $+ 0,6 6 $chr(3) $+ 0,7 7 $chr(3) $+ 1,8 8 $chr(3) $+ 1,9 9 $chr(3) $+ 1,10 10 $chr(3) $+ 1,11 11 $chr(3) $+ 0,12 12 $chr(3) $+ 0,13 13 $chr(3) $+ 0,14 14 $chr(3) $+ 1,15 15 $chr(15)


ASCII character codes:
Copy and paste that into your alias section, and type /ascii to activate it.

This is useful for when you want to find the ASCII number of a character. If you don't know what ASCII numbers are, you don't need to use them (yet!).

ascii { 
  window -l -t15,30 @ASCII -1 -1 400 300 
  aline @ascii Character $+ $chr(9) $+ ASCII value $+ $chr(9) $+ Alt+<keypad>
  VAR %a = 32 
  WHILE (%a <= 255) { 
    aline @ascii $chr(%a) $+ $chr(9) $+ %a $+ $chr(9) $+ $base(%a,10,10,4) 
    INC %a 
  } 
}


10. Places To Go  Back to Top

After you've read this tutorial, you should be ready to start out on your own as a botmaker (what fun). Don't assume that this tutorial will teach you how to make a complete, superadvanced bot, this is just a starting point and you should refer to other documents to get help. The most useful documents, and the ones I use most frequently are:

mIRC help file: it comes with mIRC

mIRC FAQ: a VERY GOOD reference

Jeepster's Numeric help: contains raw reply numbers, available from IRC

The most useful source of information, however, is OTHER PEOPLE. I hang out on DALnet, because it is by far the best and most organised, and I'll be happy to help out with any questions.

The channels you should visit for help are:

#HelpDesk is the DALnet recommended help channel for scripts and bots. Ask an op to help you writeing a short script, or to correct your existing script, and he/she will be glad to help. However, please do not ask "how to make a bot" or "make me a bot" as these questions are just plain stupid and almost rude. Specific questions are WELCOME.
Also keep in mind when asking: No one will write your script! You should read the mIRC Help file first before asking there!

#HelpDesk's homepage is at http://helpdesk.zaz.net

#mIRC is the DALnet recommended help channel for the mIRC client. They will also help with small scripts, although they are better with general mIRC help. For large script and bot questions go to #HelpDesk, although many #mIRC ops are also #HelpDesk ops.

#mIRC's homepage is at http://www.mirc.org/

#dalnethelp is the official DALnet channel for help with DALnet services eg. ChanServ

#operhelp is the IRCop/CSop channel for people who need the services of someone important.

If you forget your NickServ or ChanServ password, join #operhelp and ask for a CSop. If someone is giving you hassle, ask for an IRCop

DALnet's homepage is at http://www.dal.net/

Here are some useful Web sites for scripts/bots:

These sites are reviewing scripts so you don't have to worry to downloads scripts containing viruses or backdoors:


11. Example Protection Script  Back to Top

I strongly recommend to to to these sites and look for more protection examples you might want to add to your bot:

Here is an example for a simple Nick Flood Protection (copy/paste in your Remotes Section):

#nickflood on
on @+1:nick: {
  /auser 30 $newnick 
  .timer 1 5 /ruser 30 $newnick
}
on @+30:nick: {
  /auser 31 $newnick 
  .timer 1 5 /ruser 31 $newnick
}
on @+31:nick:{
  /auser 32 $newnick 
  .timer 1 5 /ruser 32 $newnick
}
on @+32:nick:{ 
  /auser 33 $newnick 
  .timer 1 5 /ruser 33 $newnick
}
on @+33:nick:{ 
  /auser 34 $newnick 
  .kick $chan $newnick Nick flood protection!
  .mode $chan +b $newnick
  .notice $nick 30 second ban for nick flood 
  .timer 1 30 mode $chan -b $nick /invite $nick $chan
}
#nickflood end

on +100:text:nickflood on:#: {
  .enable #nickflood
  msg $chan NickFlood Protection Enabled!!
}
on +100:text:nickflood off:*:{ 
  .disable #nickflood
  msg $chan NickFlood Protection Disabled!!
}

I strongly recommend you to read the mIRC Help file (type /help) about the above commands to undetstand fully what this piece of code is doing.


12. Conclusion  Back to Top

By now, you should have some ideas how to make a bot and how to continue to develop it. This tutorial isn't complete and it never can be. We just tried to give you an idea what you can do.

We hope you enjoyed our tutorial and we have been able to help you to start your own bot.