mSriptBox Tutorial
Introduction to Groups

Written by blue-elf
Published with permission.

Table Of Contents

  1. Introduction
  2. Group Components
  3. Naming Groups
  4. The Group "Body"
  5. The Group "End"
  6. Controlling Groups
  7. Miscellaneous
  8. Hints, Tips, And Other Info
  9. Conclusion

1. Introduction  Back to Top

This tutorial is meant for those who are fairly new to mIRC scripting. But intermediate and advanced scripters are not prohibited from reading this.

What are groups? Let us begin with an quick explanation of the remotes section of mIRC. As all scripters know, mIRC has that section where you can have scripts to automatically react to certain events, whether these events may be coming from the server (RAW), or from other users (CTCP or ON TEXT/ACTION/NOTICE..etc), or from within your own script (such as ON DIALOG, ON CLOSE, menu definitions).

The whole of this section of mIRC can be turned off or disabled. Which means that when we type /REMOTE OFF mIRC will not react to any of our events even if we already scripted some ON TEXT events or the like.

As scripters improve, they tend to become more aware of what the remote section can do, and what the limitations are. Sometimes, we want to have a small section of our RAW or our CTCP's to trigger and sometimes we don't. This is where the groups come in.


2. Group Components  Back to Top

Below is an example of a group. Take a look at it first before proceeding to the explanation.
#mygroup off 
on *:ACTION:*slaps*trout*:#:{
  describe # slaps $nick with a lawsuit - that's what you get for animal abuse!
}
#mygroup end

As we can see, the first line consists of #mygroup. This means that the group name is "mygroup". All groups begin with a "#" - this is for the purpose of telling mIRC that we have a group in that part.

The "off" after "#mygroup" signifies the beginning of the group. And "off" means that it is currently disabled and will not trigger at all - even if your remotes are enabled. For now, forget about the on or off part, that will be explained later.

After the groupname, you can see a remote event. The example shows an on ACTION event. It checks if somebody does a /me in the channel and the words "slap" and "trout" are in their action. And if your script finds those words, it will "slap that nick with a lawsuit".

Once the on ACTION has ended, you can see the "#mygroup end". That signifies that your group named "mygroup" has ended there. Similarly with the beginning of the group, the end has to be prefixed with a "#" character and it must have the same name as the first one (#mygroup). The only difference is that it would say "end" instead of "off" or "on". Thus, we can divide a group into three parts: the beginning, the actual script, and the end.


3. Naming Groups  Back to Top

Groups can be named with practically most anything. But the important thing that you should note is that, make sure you name them in a way that:

  1. They can be easily remembered
  2. They are easily typed
  3. They do not have the same name as other groups - which means you can only have one group name for the whole script. So you can't have a #test in events.mrc and another #test in ctcps.mrc because it will only confuse mIRC.

All these are for the purpose of making your scripting activity easier, and also to save space in your scripts.

The important thing is that, groupnames cannot have spaces in them. I have not personally tried using commas in groups but I am sure that paces in groups are not possible.


4. The Group "Body"  Back to Top

In this context, group "body" (as I would call it) refers to the actual script contained between the #groupname beginning and end. The body can be one line or more. So you can have two events in a single group like the on OPEN in the following example:

#group.sample off 
on *:OPEN:?:{
  IF ($nick == blue-elf) {
    msg $nick Hi, I read your article on #groups
  }
}
ON *:OPEN:?:{
  IF ($nick == $me) {
    echo 4 -s I just messaged myself! 
  }
}
#group.sample end

The above example and the first example are both valid groups.


5. The Group "End"  Back to Top

All groups must have an end. It means that you must end with a "#groupname end" as can be seen in the above examples. Below is a bad example using the on START Event:

#bad-group off 
on *:START: { echo 2 -s *** Hello }

If there is no "#bad-group end" after the ON START event, mIRC will think that your group goes to the very end of the file. This behavior is not usually what you want, is not good programming style, and might change at a future date, so you should always close your groups with a "#blah end"example.


6. Controlling Groups  Back to Top

Controlling groups means the disabling and enabling of groups as and when we wish it. The command used is "/ENABLE #groupname" to turn the group ON and "/DISABLE #group" to turn it off. Groups can be enabled or disabled from anywhere in a script, be it an alias, or a popup, or another remote event outside of the group.

You can tell that a group is ON if the word after the groupname says "on". For example:

#group on 
ctcp +40:OP:?:{ .msg $nick I cannot op you! }
#group end

The above group will trigger because it is on.

Remember that groups can be disabled from within itself but it cannot be enabled from within itself. Let us look at another example:

#mygroup on 
on *:START:{ 
  echo 4 -s After this, it will not trigger again unless the group is enabled again. 
  .disable #mygroup 
} 
#mygroup end

Alternatively, you can remove the ".disable #mygroup" but you would have to use the /disable #mygroup to turn it off. Again, this can be done with a popup or an alias or another remote event.

Here is an example of how it can be disabled from another remote event.

#mygroup on 
on *:START:{ echo 4 -s This group will be disabled after I connect to the server! }
#mygroup end 
on *:CONNECT:{ .disable #mygroup }

Groups can be disabled or enabled using wildcards. For example, if you have #group.1, #group.2, and #group.3, you can turn them all off using /DISABLE #group.* or you can enable them all at once with /ENABLE #group.* Similarly, you can disable or enable the same groups by using a "?". Thus, /ENABLE #group.? will enable all those groups. The ? signifies a single character and the * signifies one or more characters. These wildcards can be placed in between the group names. Thus, /ENABLE #*up.? will also enable #group.1, #group.2, and #group.3.

Another way of enabling and disabling multiple groups is by specifying the names in a single command. Therefore, /ENABLE #group.1 #group.3 will enable #group.1 and #group.3. They can also be disabled in the same way.


7. Miscellaneous  Back to Top

If you have many groups in your script, you can check if they are on or off, and what file they are in by using the /GROUPS command.

Another way of checking if a group is enabled or not is using the $group() identifier. For example, $group(#mygroup) would return on or off. Read the mirc.hlp on $group for more information.


8. Hints, Tips, And Other Info  Back to Top

Remember that once a group has been enabled, it will function normally. By this, I mean that if your group contains an event, and there is another event below the group, the latter will not trigger. Here is an example:

#number on 
on *:JOIN:#mirc:{
  echo 4 # This will trigger. 
}
#number end 
on *:JOIN:#mirc:{
  echo 4 # This will not trigger as long as the group #number is on. 
}

Groups can contain anything that can be put in a remote script. This means that you can have aliases, menu definitions, remote CTCP events, and other normal ON events within it. However, there cannot be groups within groups. If a group is within another group, one of those groups will not function properly. For example:

#more_groups off 
on *:TEXT:#:*:{
  echo 4 -s $nick said $1- in # 
}
#innergroup off 
on *:ACTION:#:*:{
  echo 4 -s $nick acted $1- in # 
}
#innergroup end 
#more_groups end

The above example is -wrong- and the #innergroup should be taken out of #more_groups.

Most of the time, using groups can speed up your routines. I co-wrote an addon and there was a speed problem - so the best solution that made the whole thing faster was to group the aliases depending on when they are needed. Here is an example of how they can be used for aliases:

#alias.1 off 
alias cycle { 
  part # $+ $lf $+ join # 
} 
#alias.1 end 
#alias.2 off 
alias cycle { 
  part # $+ $lf $+ join # $chan(#).key 
} 
#alias.2 end

As you can see, they have the same aliases but the alias works slightly different in both groups. This is a very good alternative to making your script faster.

Finally, here is an example of a small script that shows the usage of groups and how they enable and disable themselves, and how the commands are "bounced" from one event to another. Try it out and see what it does.

#a off 
ctcp *:TEST:?:{ 
  echo 4 -s the first group triggered 
  .enable #b 
  .msg $me proceed to the next group 
} 
#a end 
#b off 
on *:OPEN:?:{ 
  IF ($nick == $me) { 
    .disable #a 
    echo 4 -s the second group triggered 
    .enable #c 
    .notice $me proceed to last group 
  } 
} 
#b end 
#c off 
on *:NOTICE:*:{ 
  echo 4 -s The group bounce is over 
  .disable #b #c 
} 
#c end 
on *:CONNECT:{
  .enable #a
  .ctcp $me TEST
}


9. Conclusion  Back to Top

Groups are very useful in scripting. Hopefully, this tutorial will enlighten the reader and will give him or her more ideas on how to use them fully. But take note that groups are not needed all the time. Sometimes, you can do away with groups and have a separate file for a certain remote event - but that is a different tutorial already.