The format of an Event

on <level>:<event>:<commands>

Commands are much the same in any script type - refer to the MIRC Commands tutorial for more details. The User Levels and the Events themselves are the things you will learn here.

The ':' colons are essential to the correct format of the lines of script. They are used to divide the various sections and some parameters of the event script. Always look at the examples carefully to learn the placement of colons.

That is as much of the formatting as can be covered until the events themselves and the user levels are covered. User Levels are the simpler part so that shall be the next focus of this tutorial.

User Levels in Events

User Levels allow you to teach mIRC to treat some people differently to others. You can define as many different levels as you wish and then categorize the users you know into those levels.

The default level is 1 and this is the level assigned to everyone by mIRC unless you specify differently. When you script events, the code includes the level of user that the reaction you give applies to.

on 1:<EVENT>:<COMMANDS>

The above shows the format of an event script that applies to all level 1 users, which as stated is the default level. This therefore affects everyone except anyone you previously assign another level to.

To change the level of a user you must decide whether to apply the level to the nick (anyone using the specified nick) or you must specify a hostmask to use.

You can use numerical or named levels (level 5 or level Friend for instance). There are two different methods available to assign and change levels to users.

The first method is to directly edit the User List with the mIRC editor. Open the editor as if to edit your Remotes or Popups scripts and then turn to the Users tab.

The format to use is:
<level>:<Nick OR Hostmask>
You can specify multiple levels if you put a comma ',' between each level.

The other method to assign and change the access levels of users is to use the mIRC commands available. /auser, /guser , and /ruser , are some of the commands available to set and change access levels for users.

/auser [-a] <levels> <nick OR address> [info]

The /auser command adds the specified nick/address exactly as it is given to the users list with the specified levels. If you specify [-a], then if the user already exists, the specified levels are added to the current levels the user has.

/guser [-a] <levels> <nick> [type] [info]

The /guser command works the same as the /auser command except that it looks up address of the specified nick and adds it to the user list. It does this by doing a /userhost on the given nickname, and returning an address in the format specified by type (see next few paragraphs). If no type is specified then a default address format is selected.

Since this is really the first example shown that uses hostmask types I had better explain this a little. A user/host address is comprised of several parts. There is the Nick, the Identd, the Host and the Domain.

[email protected]
 

The host and domain portions of the hostmask are the parts that relate to the server they are connected to the internet through. The domain will therefore be the ISP company, while the host is the specific server machine they are logged onto.

The 'nick' portion of the address is simply the nick that they are using, while the 'user' part is the identd that they have set. In mIRC this will be the identd set in the options. In other clients this is usually the name portion of the e-mail address they entered.

The point is that while anyone can use anyone else's nick on most servers, only persons using the same ISP provider could have the same domain too. However for many of us, we get a different IP each time we dialup to the internet (dynamic IP is the term)

Using the entire User/Host address would not work for such cases so we need to apply a mask (hostmask). This mask matches to parts of the full address rather than the whole thing. There are ten types of hostmask.

When specifying a type of mask to use you simply give the number of that mask type.

0: *[email protected]
1: *!*[email protected]
2: *!*@host.domain
3: *!*user@*.domain
4: *!*@*.domain
5: [email protected]
6: nick!*[email protected]
7: nick!*@host.domain
8: nick!*user@*.domain
9: nick!*@*.domain
 

From the above, type 3 is one of the best for our purposes here since it uses only the identd and domain portions, and cannot be thrown by a change of nick or the changing of IP after a redial.

/ruser [levels] <nick OR address> [type]

The /ruser command, if used without specifying levels, removes the specified user from the user list. If you specify levels then these levels are removed from the current access levels of this user. If all a user's levels have been removed, the user is removed. If you specify a type then the users address is looked up with a /userhost and any users in the users list matching this address are removed.

The purpose of user levels is simple: it allows you to set automatic responses to events that treat your friends differently to people you dont know. This can be used to allow your friends to access your fileserver while not allowing people you don't know to do so, for instance.

All this affects our Event script format as follows:

on 1:<EVENT>:<Command>
on 2:<EVENT>:<Command>
 

The first event will apply if the event given was triggered by a level 1 user, while the second event will apply if the event given was triggered by a level 2 or higher user.

You can use a '*' asterisk to specify a 'wild' level, that is the event script will will be triggered by a user of any level.
on *:<EVENT>:<Command>

Prefix any level with a '!' exclaimation mark to prevent it being triggered by your own actions.
on !1:<EVENT>:<Command>

You can use a '+' prefix to limit the event trigger to only respond to users of exactly, specificly the level you set for the event.
on +2:<EVENT>:<Command>
This event will not trigger for level 1 users or for level 3 users (unless they have additionally been set as level 2 users).

You can limit events to being executed only when you have Ops on a channel by using the @ prefix.
on @1:<EVENT>:<Command>

That's the basics of setting access levels. Remember that unless you specify different levels for some users, everyone is level 1 and therefore the on 1:is the only level you will need (with or without the ! or @ prefix).

Events in mIRC

Now its time to look at the events themselves. The events are things you want mIRC to react to. The events cover pretty much anything that can occur in IRC.

TEXT events

You can react to text, either specific words / phrases, or to text from specific users / nicks. You can react differently to those words in ACTION text or Notice text, Channel text or Private Message text.

on 1:TEXT:<text to match>:<location type>:<command>
 

The text to match can be an exact phrase:

on 1:TEXT:hello $me :<location type>:<command>
 

or a word or phrase in the text:

on 1:TEXT:*help*:<location type>:<command>
 

or any text at all using a * wildcard:

on 1:TEXT:*:<location type>:<command>
 

The location type can be a channel (#):

on 1:TEXT:*:#:<command>
 

one or more specific channels:

on 1:TEXT:*:#mIRC,#beginners:<command>
 

a query window (using '?'):

on 1:TEXT:*:?:<command>
 

or in all normal or private text (use *):

on 1:TEXT:*:*:<command>
 

For more on location types see the OPEN / CLOSE events description further down the page.

The following examples should help you to understand exactly how the formatting of a TEXT event works. Note that the following examples use commands that you should be familiar with from the Commands tutorial.

on !1:TEXT:*help*:#:/msg $chan Do you need some help $nick $+ ?

The above event looks at all text in any channel (from a level 1 user that is not the user of this script) for the word 'help' and if it finds it, sends a message to channel asking the person who triggered the event if they need help.

on *:TEXT:*hello*:?:/msg $nick Hello $nick

The above event will trigger when anyone says 'hello' somewhere in the text of a private message or query and will send a private message 'hello' in return.

NOTICE and ACTION events

The on ACTION and on NOTICE events use exactly the same format as on TEXT, and trigger on an action and on a notice event respectively.

on !1:ACTION:*waves*:#:/describe $chan waves cheerfully back at $nick
on !1:NOTICE:*:#:/echo -a Notice from $nick ( $chan ) $1-

The above events respond to an Action and a Notice message respectively. The $1- identifier used in the Notice example contains the entire text content of the notice.

The /describe command is identical to the /me or /action command, but allows you to give a location of which window to send the Action to. The $chan identifier gives the location as the same channel where the notice that triggered the event came from.

JOIN and PART events

The Join / Part events are triggered when a user of the level specified joins or parts (leaves) a channel you are in. Unless otherwise set, this includes your own joining and parting of channels.

on !1:JOIN:#:/msg $chan Welcome to $chan $nick

The above example will trigger when any default level user (except yourself) joins any channel, and will welcome them. Note that the /say command cannot be used in an events script since it cannot specify where to send the text. The /message <channel / nick> works exactly as /say however.

on Friend:PART:#mIRC:/msg $nick See ya soon!

This one triggers when a user with level 'Friend' parts from the channel #mIRC when you are there. It sends a private message saying 'See ya soon' to them.

CHAT events

on 1:CHAT:*hello*:/msg =$nick Hello there!

The on CHAT event is similar to the TEXT events. The above example triggers when a level 1 or above user says 'hello' in a DCC Chat. The equal sign in =$nick is required to send the reply as a dcc chat message. If no equal sign is used, the message is sent as a private message.

OPEN and CLOSE events

on <level>:<OPEN or CLOSE>:<window type>:<command>
 

Window types are like the '?' for Private messages and '#' for channels that we have used already in some of the earlier examples.

# means a Channel Window
? means a Private Message or Query Window
= means a DCC Chat Window
* means any window type
! means a File Server Window
@ means a Custom Window
 

You can't use OPEN or CLOSE events in relation to channel windows however. You must use JOIN and PART events instead.

on ^1:OPEN:?:halt
on 2:OPEN:?:msg $nick Hi, be right with you $nick

The above open event is an example of a ^ prefix event, which allows you to halt events. In this example, if the incoming message is from a level 1 user the query window is prevented from opening by using the /halt command. A level 2 or higher user would be subject to the second event script instead.

MIRC Events always try to use the highest applicable level for reacting to any event you have set.

on 1:OPEN:=:/msg =$nick Hi! I'll be with you in a second...

This triggers when a dcc chat connection is first established. The equal sign in =$nick is required to send the reply as a dcc chat message.

on 1:CLOSE:?:/echo -s you just closed $target query window

This event triggers when you close any Query window, it displays the 'echo' to the status window. In case this seems rather pointless, remember that because logging can be applied to only specific windows, you could choose to log your status window only, and keep track of all major events there where it would be copied into the log - an activity log kind of arrangement.

Other Events

There are many more events yet but all follow the same basic principles as those above.

on *:CONNECT:
on *:DISCONNECT:
on 1:OP:<Channel*>:echo -s $nick gave ops to $opnick
on 1:DNS:
on 1:FILESENT:<file (e.g. *.txt)>:echo $filename sent to $nick
on 1:FILERCVD:<file (e.g. *.wav)>:echo $filename received from $nick
on 1:GETFAIL:<file (e.g. *.mid)>:echo Failed to receive $filename
on 1:SENDFAIL:<file (e.g. *.zip)>:echo Failed to send $filename
on 1:INPUT:#mIRC:/echo You entered the text " $1- " in the #mIRC window
 

For the full list of events and more tips on their use read the help in mIRC on the subject of 'Remotes'.