Semiconductor & Computer Engineering
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)
Contents
Syntax[edit]
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. It means the order of definition of your event does matter, compared to aliases:
;this event triggers whenever someone says anything (the *) on the channel #help on *:text:*:#help:{ } ;this one triggers when someone says !help on the channel #help on *:text:!help:#help:{ }With that order, when someone says !help, since the first event triggers for any text, it will triggers for !help, meaning the second event will never trigger, so this configuration doesn't make sense. However the other way around does:
on *:text:!help:#help:{ } on *:text:*:#help:{ }Now when someone says !help, it will trigger the first event, as we expect, while the other event will still trigger for any other text.
Note: These events are empty for the sake of the example
Levels[edit]
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[edit]
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)
On Join[edit]
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[edit]
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[edit]
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[edit]
The matchtext can contain wildcard 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[edit]
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[edit]
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[edit]
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[edit]
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[edit]
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]