mIRC ScriptBox
Basics: Introduction into Remotes

Written by Merlin

Table of Content

  1. How to open the Editor for Remotes?
  2. What is a remote?
  3. What is an event?
  4. What are commands?
  5. What is RAW?
  6. Userlevel
  7. Proper ordering
  8. Where are the remotes?
  9. Event triggers


Introduction

This tutorial has first been made public available during my successful CBT Project started in 1998, where Eggdrop Bots on various IRC networks have been set up to give courses on IRC.

These courses have never before been released on any web site or have been submitted to anyone.


1. How to open the Editor for Remotes?  Back to Top

To open the builtin editor and go to the Remotes section there are two ways you can use:
  • Hold down the ALT-key and while holding it down press the letter 'R' and then release both keys or
  • Click 'Tools', then 'Scripts Editor'.

You can see now a line that looks like this:

Below that there are 5 tabs (because you used ALT-R, the 'Remotes'-Tab is put in the foreground):

Below that you can see the Editor window - exactly where we will edit our remotes throughout this tutorial.


2. What is a remote?  Back to Top

Remotes allow your mIRC to react automatically to things which happen while you are on IRC. These things that happen are broken into three major categories:
  1. Events
  2. Commands
  3. Raw


3. What is an Event?  Back to Top

An event is all the things which happen around you. Joins, parts, kicks, bans, quits are all events. Starting and stopping mIRC are also events. Connecting and disconnecting too. Even someone on your notify list showing up is an event.


4. What are Commands?  Back to Top

Commands are a bit different. Ping, version and clientinfo are ctcp commands. A command is just that, it commands your mIRC to send information back. Though an event can be scripted to send information back, a command is different.


5. What is RAW?  Back to Top

Perhaps the hardest thing to grasp is what RAW is. Certain things sent to you by the IRC sever itself can only be reacted to based on its numeric value. The IRC protocol defines these numerics, and you can see them in the RFC1459.

You have seen perhaps responses to a /whois nick. That information is sent to you by the server, and NOT the client of the nickname you whois'd. This information is seen by RAW numerics.

The main point to all this is, when you decide you want to write a remote, you first must consider how exactly you will react to it. What will be triggering this script? Event, command, or raw?


6. Userlevel  Back to Top

Before we begin, there is more general information you must learn, at least to some minimal degree.

mIRC stores access levels to YOUR client internally. This has nothing to do with channels services (Chanop bots) and has nothing to do with them being an Op or voiced user. YOU decide who has what access.

Users are added to your remotes in the remote users section. Though you CAN add persons to word based levels, I suggest STRONGLY that you do not.

Say you have a friend who uses the nickname Joe. Joe has an IRC address that looks like me@ppp12.isp.com . You want to give JOE access to certain areas of your script.

Say you wanted to make Joe a level 10 user. You would add Joe as a user with the command /guser 10 Joe 3

/guser is the command to add persons. 10 is the level you assign to Joe. The 3 is the wildcarding that will be done to the address so it will still match when Joes address changes between connections.

If you looked in your remote users, you would find an entry similar to this: *!*me@*.isp.com. Notice some of the address has been changed to * characters? This is the wildcarding that mIRC does to an address so it wil match at all times. All users are added much in the same way. /guser level nick 3 (I suggest you stick to using the type 3 address. It works).


7. Proper ordering  Back to Top

Now a brief description of what the syntax style of all 3 types of remotes looks like. Do NOT add these lines to your remotes!

ON 1:TEXT:words:#: commands
CTCP 1:VERSION: commands
RAW 352:*: commands 

Though each of the 3 look very different, they have much in common. mIRC needs to know certain information to react in a script.

Four questions must have to be answered:

  1. What type script? (ON, CTCP, RAW).
  2. What particular thing are we watching for? (Text, VERSION, 352).
  3. Are there any parameters to this? (words, *).
  4. What do I do? (commands)

Let's look at each closer. First the channel text one:

ON 1:TEXT:hi:#: { commands }
This should read to you as: watch for a level 1 or higher user to say 'hi' (just this single word and nothing more) in a channel, then do 'commands' when you see it.

ON 1:TEXT:
Text from a level 1 or higher user

ON 1:TEXT:words:
The specific text to watch for is 'words'

ON 1:TEXT:words:#:
Watch in channels. Since # is meant for channels, ? means watch in queries/msgs and * means watch everywhere.

ON 1:TEXT:words:#: { commands } 
When you see this event happen, perform 'commands' which are placed between the braces '{' and '}'

So you see, though its written in a language that you may not understand, there is an orderly logical method to the madness :)

Lets look at the command.

CTCP 1:VERSION: commands
and
ON 1:TEXT:words:#: commands
. This should read to you as: watch for a level 1 or higher user to say 'words' in a channel, then do 'commands' - which are placed between the braces '{' and '}' - when you see it.

The reason there are so many fewer : : sections is because ctcp does not occur in channels. So, :#: is not needed. Its a much simpler protocol.

CTCP 1:
watch for commands from level 1 users or higher

CTCP 1:VERSION:
the specific command to watch for is 'VERSION'

CTCP 1:VERSION: { commands }
when you see it, perform commands which are placed between the braces '{' and '}'.

Different, yes, but the same ordered logical madness. Let's look at the RAW (don't panic YET).

RAW 
this is a server triggered event (users do not apply here)

RAW 352:
The numeric reply to watch for is 352 (this happens to be the reply to a /who request)

RAW 352:*:
Is something in the reply supposed to trigger this event? * means match ALL text, so we respond to ALL 352 replies here.

RAW 352:*: { commands } 
When we see a 352 reply, perform commands which are placed between the braces '{' and '}'.

Again, same orderly logical madness (now you can panic if your TOTALLY lost) Just kidding actually. If you are confused, take a minute to scroll back and re read the parts that are confusing to you.


8. Where are the remotes?  Back to Top

Now we want to make certain you understand where to add remotes. Ok, this process is confusing until you catch on. I promise to go slow. You promise to read carefully and follow exactly. I hope I have no errors.

First, where are remotes? Three ways to access the remote editor.

  • Press the button on your toolbar that says '/a' .
  • Press Alt + r (Means hold down the ALT-key and simultaniously press the letter R, then release both buttons).
  • Click on Tools", then "Script Editor" and then click on the "Remotes" Tab.
All three take you to the same place.

Remotes has 3 sections. Users, variables, and scripts. I bet you can guess that scripts go into the script files. To be CERTAIN that your adding this into the right place, I am going to describe the creation, loading, and editing of a file called test1.mrc

First, lets create it. This I will go slow with. Open the remotes (alt + r) and click on the 'File' menu. In 'File' is the choice 'New'. Click NEW so we can create a new file.

Now, it defaults to script.ini. We have to fill into the new script. So please enter this in the empty window:

 ; My first remote-script.

We don't want it to be named script.ini . In FILE, click the 'Save as' option. Write the name of the file as

test1.mrc
then press OK.

Congrats, you created a new file called beta.mrc which we later will edit to include some remotes. Let's make sure this went well for you :) Just a small test. Type this command in the channel window

//say $findfile($mircdir,test1.mrc,1) has been created.

We will now show you how to Load and Unload. First, to unload this file do this:
Click on

File
and on
Unload
OK, we have a new file to put remotes in, but it isn't loaded yet! We have to load it. This is another process in itself. Again, I will go slowly.

Open the remotes again (alt + r) and go in

File
and go to
Unload
then to Script, browse the dialogue box until you highlight test1.mrc, then hit OK.
Great, all done. Another small test :) . Type this command in the channel please:
//say $script(test1.mrc) has been loaded.

Now, you have a script file loaded that is ready to be edited to add scripts to. The HARDEST part is behind you. Trust me, new scripters have the hardest time finding 'where in the world do I put this stuff'. You now know the file!

One last minor hurdle, and I can't even test you on this one, so be precise here.

Open your remotes and you must select the file to edit. NOT in the File menu, but across the top there are menus. Two of them are 'View' and 'Listen' . Open the View one and place a check beside the test1.mrc file. It's selected for editing now.

Now, you may place lines of code in the edit box, and the will be saved to the test1.ini file and are ready for use.

Add this line there please:


  ON 1:NOTICE:fubar:*: msg #CBT I am NOT fubarred!
  RAW *:*: echo 2 -a $numeric has replied with $1-  

I think the ability to wildcard the numeric number like that is actually a mistake on Khaled's part, but it sure is nice! Now do a /whois on your nick.

You get the reply same as above, but you also get a bunch of weird stuff! and it has numbers in it. The first Number is the server numeric for that RAW event. That would be the number you used to write a real line for it.

Use this trick and you will NEVER need to download the RFC1459 that contains the raw numerics :). Remember, RAW comes from servers, so there are no USER levels involved.


9. Event triggers  Back to Top

If you made it this far, you are coming along nicely on where to add script code, and maybe even some syntax of how to write them. Let me throw out a list of common event triggers. Dont add these, as it is incomplete code.

All have will start with ON 1:EVENT:, so here they are:

JOIN, PART, QUIT, TEXT, KICK, BAN, NOTIFY, UNOTIFY

They ALL have much the same common characteristics. Some have less parameters than others, and you can see examples of these by type /help TYPE (like /help on join).

Remember to use your USER levels wisely, and you can create some rather complicated looking scripts very easily.

I know your eager to start writing Super ROCK your World v666 by YOU, but your NOT ready.

Fiddle with on texts, on notices, and kick and ban events. Fiddle with some raw, and create some new commands (CTCP 1:MYSECRETWORD:) and then maybe your ready.

The greatest of a script idea will fail MISERABLY if you do not understand the underlying principles of syntax and order. So walk, then run!