mIRC Tutorial No.1 by Windlord

[Windlord]

mIRC scripts are based on events, reacting to events and sending signals.
What are these events? And how can you react to events?

>> EVENTS
An example of an event would be "on TEXT" which is a signal your mIRC client receives whenever someone speaks on IRC.
To react to events, a prefix called: "on" is used with the name of the event and the parameters needed following after.
An example script that reacts to text, "hi" would look as follows;

Code Select Expand

on *:TEXT:hi*:#: { msg $chan Hey there $nick }

This simple and short line has most of the basic stuff that you need to know about mIRC scripting.

First of all, the most basic and needed prefix "on".
"on" as I mentioned before, tells the script that this bit of script is meant to react to a certain signal called "TEXT" that is mentioned after the "on".

What are the ":" symbols?
The whole chunk after "on", "*:TEXT:hi*:#:" tells the script the parameters with which the script should react to.
What does it mean by parameters? Parameters are options that you choose the script to react to.
The ":" symbol lets you separate out these parameters.
In the case of the "on TEXT" event, there are 4 parameters.

*   :This part symbolises the access level. This little thing can restrict the users that can use this script. For example, if this value was 10, only level 10 users will be able to use this script. Check the mIRC help file for more information regarding user levels.

TEXT:This part tells the script which event it is reacting to. In this case the event is "TEXT".

hi* :This is the text to which the script needs to react to. The symbol: "*" is called the wildcard symbol. This will be discussed further below.

#   :This is the type of "TEXT" event that the script should react to. "?" would let it react to PMs on IRC while "#" would let it react to channel messages, with "*" letting it react to all kinds of messages.

Now comes the fun bit: the actual "reaction" part of the script!
In that short script up there, the reaction part is: "msg $chan Hey there $nick"

  The reaction part of a script must always have a command at the front of it with the appropriate parameters behind it.
  In this script the command is "msg" which can also be written as "!msg" ".msg" or "!.msg" (This will be discussed below).
  The parameter for the command "msg" in this script is "$chan" and "Hey there $nick", a target and the message that it needs to send.
  "$chan" or "$nick" are called identifiers. They are short words with the prefix: "$" that carry important information for your script or carry out complicated data processing.
  Some examples of 'identifiers' would include, $time $ip $date
  This certain command-line, "msg $chan Hey there $nick" would end up reacting as follows;
   
    <Windlord> Hi
    <Bot> Hey there Windlord

  Now some of you may have found that part boring and would expect me to talk about 'aliases' and 'inis'. Well I am not going to.

>> BRACKETS
I will now talk about brackets.
Brackets are used much in any kind of script for mIRC.
Some of the types used are;
     () = Normal Brackets - These are used to enclose parameters for identifiers. For example: "$read(Text.txt)" which would read a random line from "Text.txt" located in your mIRC directory.
     {} = Script Brackets - These are used to enclose scripts. They are often used inside events and 'if' or 'else' scripts to show the starting and ending point of the script.
     [] = Evaluation Brackets - These are used to evaluate an identifier or variable. This means, re-reading and acquiring data. This can be useful since you may need to use "[ $time ]" instead of "$time"

Some basic rules are...
1. mIRC does not support 'tabs'. If you use 'tabs' your script gets easily broken and messed up.
2. Script brackets can be used in two different ways;
    -- 1. The horizontal way.

Code Select Expand

on *:ACTION:*:#windlord: { if ($1 == Windlord) msg $chan What? }
    -- 2. The vertical way.

Code Select Expand

on *:ACTION:*:#windlord: {
 if ($1 == Windlord) msg $chan What?
}
   The vertical way is used if lots of stuff have to be put between the brackets.
   Do not use the brackets in any other way. For example;

Code Select Expand

on *:ACTION:*:#windlord:
{
 if ($1 == Windlord) msg $chan What?
}
   since mIRC won't recognise it.
3. Make sure identifiers are kept alone! "msg $chan ($time)" would only give you an error because the script is not able to separate out the "$time" from "($time)"
   You'd need to use "$+" and make it "msg $chan ( $+ $time $+ )".
   Note: Refer to section: "Some useful tips to making scripts".
4. Never leave brackets open!

>> OPERATORS
Now, let's look at some stuff like...
  isin , iswm , == , >=
which are called "operators"

Operators are used to compare two different variables inside an 'if' statement.
They are basically used in the following ways;
    if (v1 operator v2) { commands }
    elseif (v1 operator v2) { commands }
    else { commands }
where v1 is the first variable and v2 is the second variable that we are comparing.

--> "isin" checks if the certain string is inside the second string. For example, "if (abc isin abcdefghijkl)" would let the script continue on since abc is inside the string abcdefghijkl.
--> "iswm" checks if a certain wildcard is inside the second string. This is similar to "isin" except that you are allowed to move the wildcard symbol around as you wish. For example, "if (N* $me iswm $1-)" which would react to string inputs such as; "No Windlord", "NIE WINDLORD", "Nah I don't care about him anymore, Windlord". You can see that using wildcards may sometimes be pretty useful.
       Note: the v1 needs to have "*" in it for the script to work.
--> "==" checks if two variables are equal.
--> "===" checks if two variables are equal. (case wise as well... case-sensitive)
--> "!" means... "not" and this can come useful in many ways.
      -- "!=" checks if two variables are not equal.
      -- "!isin" checks if v1 is not in v2.
      -- "!iswm" checks if v1 is not a wildcard in v2.
--> "isnum" checks if a string is a number.
--> "isalpha" checks if a string is only formed of alphabets.
--> "islower" checks if the letters are all lower-case.
--> "isop" checks if a v1 is an operator on channel v2.
and etc....
Check the mIRC help files for more information.

>> ALIASES
Now for the stuff that everyone tries to make... Aliases.
Aliases are used to shorten long processes in scripts.
For example, if you want to check the in-game player's level for a certain command, and that certain level-checking script was about 5 lines long, it would be pointless to copy+paste that script for every single command.
Instead an alias can be used.
The most basic form of an alias is:
       alias <alias name> <commands>
These aliases act like normal default commands or identifiers depending on their properties.

For example, the following alias;
       alias smell msg #windlord WINDLORD SMELLS!
can be used by typing "/smell" in your chatbox or by adding it to a script such as...
       on *:TEXT:*:#windlord: { smell }

Another type of alias would be...
       alias version !return 13.37
which would return 13.37 when used in a script. For example,
        on *:TEXT:*:#windlord: { msg $chan $version }
would send the message, "13.37" everytime someone speaks.
note: you need the prefix "$" in this case.

Aliases can have chunks of scripts in them.
One alias that I made while I was bored is;

Code Select Expand

alias cr {
  var %words = $numtok($1-,32)
  var %a = 1
  while (%a <= %words) {
    var %word = $gettok($1-,%a,32)
    var %letters = $len(%word)
    var %b = 1
    while (%b <= %letters) {
      var %stuff = $+($chr(3),$rand(1,15),$mid(%word,%b,1),$chr(3))
      if (%b == 1) var %result %result %stuff
      else var %result %result $+ %stuff
      !inc %b
    }
    !inc %a
  }
  if (%result) msg $chan %result
}

which returns your text's letters in multiple colours if you type "/cr message"
You are free to do anything inside aliases but make sure that you remember that the alias only works with the information it gets.

Example of a common error:
    <actual command part of the script>
    elseif ($3 == slap) { vcmp.slap $1 $2 $4 }

    the alias would have to be
    alias vcmp.slap vcmp.say $1 $vcmp.name($1,$2) slapped $vcmp.name($1,$3) O_O

    NOT
    alias vcmp.slap vcmp.say $1 $vcmp.name($1,$2) slapped $vcmp.name($1,$4) O_O

Make sure you check what you send to the alias and what the alias processes.

NOTE: Aliases only react to stuff that it receives... Don't use the same identifiers inside the aliases that you use for a certain signal... unless every single part of the signal is sent to the alias.

>> SAVING DATA
Saving data is extremely useful in many ways.
Temporary data can be saved to increase the efficiency of the script for example.

-- Variables
Variables are generally identified by the prefix, "%".
Data can be 'assigned' to variables and be recalled later when needed.
There are two types of variables. A temporary one and a permanent one.
A temporary variable only exists during the length of the script while a permanent one is saved onto a file which is (for most people) called variables.ini
(Eg. If a variable is temporarily saved inside an alias, it disappears/gets unset after the script in the alias is carried out.)

"set %<variable name> <data>" Sets a permanent variable
"var %<variable name> = <data>" Sets a temporary variable.
"unset %<variable name>" removes a variable.

Identifiers do not usually like being put as variable names.
They are not processed and if you do something like "set % $+ $nick Yes" you're most likely going to get a variable called "%$nick" not "%Windlord"
Evaluation brackets come handy here. "set % [ $+ [ $nick ] ] Yes" lets you set the variable "%Windlord Yes" where the "$+" and "$nick" have to be evaluated to be used as the variable's name.

-- Inis
Inis, or initialisation files are files that can store important data.
A typical ini file looks like this.

[Section]
Item1=Data1
Item2=Data2

To write data into an ini, the basic command-line is "writeini <Filename> <Section> <Item> <Data>"
To delete a line from an ini, the basic command-line is "remini <Filename> <Section> <Item>"

For example, "writeini Hello.ini World I am so here" would make a file called "Hello.ini" with the following data in it.

[World]
I=am so here

and "remini Hello.ini World I" would make the file;

[World]

There are several things that you need to take note of though.
For example, if you do not specify the directory of the "Filename" they will be saved in your mIRC's Application Data depending on where your settings file; "mirc.ini" is located.
Most scripts like having inis in the directory of the scripts themselves.

In this case, $scriptdir can be used.
Example: writeini $scriptdirTest.ini Section Item1 Data1

Sometimes $scriptdir doesn't work and that is because the directory has spaces in them.
You need quotation marks in that case.
Example: writeini " $+ $scriptdirText.ini" Section Item1 Data1


<Some useful tips to making scripts>
-- If you need to check out certain script lines; "//echo" is your best friend.
   For example, if you need to check what "$calc(1 + 2)" would give, you just need to type;
                             //echo -a $calc(1 + 2)
   in your chat window.
   The "-a" parameter lets you make sure that the data appears in your active window.

-- For server scripts, make sure that you do not call on data from the dll too much.
   It is better to temporarily save a player's location data in a "!drop" script for example.

Code Select Expand

elseif ($3 == drop) {
  var %loc = $vcmp.location($1,$2)
  vcmp.setlocation $1 $2 $gettok(%loc,1-2,32) $calc($gettok(%loc,3,32) + 200)
}
   would be a better example of a script than;

Code Select Expand

elseif ($3 == drop) {
vcmp.setlocation $1 $2 $gettok($vcmp.location($1,$2),1-2,32) $calc($gettok($vcmp.location($1,$2),3,32) + 200)
}
   Note: $gettok is an identifier used to finding 'tokens' in a string of text. In this case, the 'character' that is used to separate out the string is character ID '32' which is a space. $gettok(%loc,3,32) returns the third number in the location string; the z-coordinates of the player.

-- If you want to stick two things together, "$+" is your best friend.
   For example, if you want your script to output; "Hello $nick!" you will have to use "msg $chan $nick $+ !" since "msg $chan $nick!" would not work.
   "$+" can be used between words or in front of a bunch of words as follows;
                $+(Hi,there,i,rule) would give Hithereirule

-- If you'd like to use brackets in your scripts in the form of messages, using ( ) [ ]  may not always work since these also function as parts of the script.
   You'll need to use $chr(number) instead. The number in this case is the number/ID that is assigned to every single character that can be used on IRC.
   Use these aliases to find the numbers out easily.

Code Select Expand

alias asc echo -a $asc($1) $asc($2) $asc($3) $asc($4) $asc($5) $asc($6) $asc($7) $asc($8)
alias chr echo -a $chr($1) $chr($2) $chr($3) $chr($4) $chr($5) $chr($6) $chr($7) $chr($8)
   /asc finds out the character id for you if you type for example: "/asc ( ) [ ]".
   /chr finds out what the character is from the character id.

That's all for today folks.
Hope this makes it easier for you to understand mIRC scripts.
Hashes and loops will be dealt at a later date.

Cheers,
Windlord

Note: All examples relating to vcmp scripts have been made using the aliases for "VRocker's mIRC Admin".

[VRocker]

wow very nice tut windy its sure to help out a lot of people.

Well done explaining these

[Windlord]

Thanks for bothering to read this uhm lengthy and easy(?) tutorial D:!

* Windlord hopes he did not make any mistakes... *^^*

[Knucis]

Very Nice!! Thanks again 

[Chezor]

Thanks for bothering to read this uhm lengthy and easy(?) tutorial D:!

* Windlord hopes he did not make any mistakes... *^^*

heh, yeah no mistakes i checked Good job.

[Juppi]

Great job Wind! 

heh, yeah no mistakes i checked Good job.

[Windlord]

Thanks, I really appreciate it.

When I feel up to it I'll write up something for hashes and loops

heh, yeah no mistakes i checked Good job.

Right.

[Orpheus]

Awesome tutorial wind, maybe i can learn something, when incan be bothered / find the time to read it, cos ATM teachers are FAILING and saying i have a deadline the day before the deadline ! when i aint started cos i didnt even know we had to do it !! I H8 joining a year late !

[Windlord]

lol Orph

Thanks for the appreciation!
Hopefully the newbies will bother reading this lol

[Tamas]

Nice work Wind, i red it because im really a newbie 

[qwq]

whats wrong here:
on *:text:idiot*#:$chan $kick
and this:
on *:text:idiot*#:$chan writeini curse.ini $nick say idiot

[Orpheus]

put both under same heading

on *:text:idiot*#: {
$chan $kick
$chan writeini curse.ini $nick say idiot
}

something like that, i think

[VRocker]

it would actually be:

on *:TEXT:*idiot*:#:{
kick $chan $nick
writeini "curse.ini" $nick say idiot
}

Read the mIRC help file for what identifiers work

[Windlord]

Inside the help file...

Commands are prefixed with "/"
Identifiers are prefixed with "$"

All scripts must start with a command.
No script must have identifiers at the front of it.
(There are exceptions but yeah)

Thanks VRocker

[qwq]

its for my mirc channel not vcmp