Revision as of 14:00, 20 August 2014

Template:mIRC Guide Triggers or more commonly On Events are blocks of code that gets executed when a certain event occurs. This is how most channel bots, scripts, and games work. All events, with the exceptions of custom ones, get automatically called. (We will talk about custom events later on)

Syntax

Generally, most events will follow this format. Some will have additional parameters.

on <level>:<event>:<commands>
 
; or
 
on <level>:<event>: {
   ;Statement block
}

We should probably mention that the colon (":") is an important part of the event line. It effectively divides the different sections of the event into parts. As a result, certain parameters that accept input like text cannot include that character in them. We will touch on that a little later in this tutorial.

At this point I feel the need to talk more about how events work with respect to multiple script files. When some kind of an action take place, like a user entering a channel or a user quitting, mIRC will scan each file for a matching event. When a matching event is found, the code gets executed, and mIRC moves on searching of a matching event in the next file. As a result, you cannot have two identical events in the same file, only the first one will get executed.

Levels

All events have an access level parameter. The access level parameter indicates which user access level can trigger this specific event. It is important to understand that mIRC's access levels are NOT related to access levels that are controls by IRC services like Anope's Services (ChanServ/NickServ).

Built-In Events

Main article: List of on events

Built-In events are events that get executed whenever certain action took place in mIRC. For example, when a user joins a channel, you can write a script that will utilize the on join event which will voice the user.

When an event gets executed, a number of additional identifiers become accessible, we call them local identifiers. Some of the most common identifiers are (whenever applicable):

• $nick - The nickname of the user that triggered the event
• $chan - The channel name of where the event took place
• $target - The name of where the event took place. (This can be a window, a query, or a channel name)
• $wildsite - The address of the user who triggered an event (in *!*@host format)

Note: This is not an exhaustive list

On Join

The on join event triggers when a user joins one of the channels you are on.

Format:

on <level>:join:<target>:<commands>

Example:

on *:join:#:{
  notice $nick Welcome to $chan $+ !
}

In the example above, we made the on join activate for any channel (by specifying no name) by any user (denoted by the wildcard * character). When a user joins, this script will notice him and say "Welcome to #channel!"

On Kick

The on kick event triggers once a user has been kicked from a channel you are on.

Format:

on <level>:kick:<target>:<commands>

Example:

on *:kick:#:{
 
  msg $chan $nick $+ , Why did you kick $knick $+ ?
 
}

In the example above, we have used the very basic setup like the on join example. $knick is an identifier that returns the name of the kicked user.

On Text, Action, and Notice

All three events trigger when a user says something, as an action, as a notice, or in a channel.

Format:

on <level>:text:<matchtext>:<target>:<commands>
on <level>:notice:<matchtext>:<target>:<commands>
on <level>:action:<matchtext>:<target>:<commands>

• <matchtext> - The match text is the text pattern that mIRC will use to compare with every user message. Once the text has been matched (and the channel if provided), the event will trigger.

Wildcard text pattern

The matchtext can contain wild characters:

• * - matches any text
•  ? - matches any single letter
• & - matches any single word

For Example:

•  !test - the matchtext will only match if the ONLY word is "!test"
•  !test* - the matchtext will match if the text starts with "!test"
• *!test - the matchtext will match if the text ends with "!test"
• *!test* - the matchtext will match any text that has "!test" in it (anywhere)

The basic text pattern

The most basic on text event is the normal wildcard pattern:

on *:text:!help:#:{
  notice $nick For Help just state your question and pastebin any relevant code.
}

Sometimes we want to get the user's input. We can use the & to match a single word (in this case it will be a name, although it doesn't matter)

on *:text:!color &:?:{
  var %color = $gettok(white black red blue brown yellow orange green, $rand(1, 8), 32)
  msg $chan $2's random color is: %color $+ .
}

RegEx text pattern

The matchtext parameter can also be a Regular Expression Pattern by prefixing the user level with a dollar sign ($)

Example:

on $*:text:/^!test$/i:#:{
  msg $chan Test Worked!
}

Dynamic text pattern

Text matched patterns can also be dynamic, for example your name at the time of the execution ($me), a variable or time. In order for mIRC to know to evaluate the expression, it must be enclosed by the $() identifier.

Example:

on *:action:$(*slaps $me $+ *):#:{
  describe $chan Slaps $nick with dried-up sandwich!
}

If the entire match text pattern contains a SINGLE variable, the $() is not required.

Example:

;Assume %text is set to !cool
on $*:text:%text:#:{
  msg $chan I am the coolest! 
}

It is also possible to use regular expressions with dynamic match text.

on $*:action:$(/^slaps $me $+ /Si):#:{
  describe $chan Slaps $nick with dried-up sandwich!
}

Target

The target parameter of the event defines the locations of where the event can be triggered from. For example, the on text event can be triggered by a channel message or by a query.

•  ? - defines query location
• # - defines channel location
• * - defines both query and channel locations
•  %var - A variable containing a channel or a list of channels is also acceptable

Example:

;let %chan equal #mSL,#help,#supprt
on *:text:!hi:%chan:{
  notice $nick Hello!
}

Custom Events

Custom events or signals are events that get called by a certain script instead of mIRC itself. These events are usually used in a framework script that lets the user that implements the script add his own code using the signal events without modifying the original script's code.

Syntax:

on *:signal:<eventName>:<command>

A custom signal event can be called using the signal command:

/signal [-n] <eventName> [parameters]

See also

• List of on events