Editing mirc/on event

{{mIRC Guide}}
{{mirc title|On Events}}
'''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.

<syntaxhighlight lang="mIRC">on <level>:<event>:<commands>
 
; or
 
on <level>:<event>: {
   ;Statement block
}</syntaxhighlight>

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:

<syntaxhighlight lang="mIRC">
;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:{

}
</syntaxhighlight>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:

<syntaxhighlight lang="mIRC">
on *:text:!help:#help:{

}
on *:text:*:#help:{

}
</syntaxhighlight>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 ==
All events have an {{mIRC|access levels|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 ==

{{mIRC|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 {{mIRC|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:

<syntaxhighlight lang="mIRC">on <level>:join:<target>:<commands></syntaxhighlight>

Example:

<syntaxhighlight lang="mIRC">on *:join:#:{
  notice $nick Welcome to $chan $+ !
}</syntaxhighlight>

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:

<syntaxhighlight lang="mIRC">on <level>:kick:<target>:<commands></syntaxhighlight>

Example:

<syntaxhighlight lang="mIRC">on *:kick:#:{

  msg $chan $nick $+ , Why did you kick $knick $+ ?

}</syntaxhighlight>

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:

<syntaxhighlight lang="mIRC">on <level>:text:<matchtext>:<target>:<commands>
on <level>:notice:<matchtext>:<target>:<commands>
on <level>:action:<matchtext>:<target>:<commands></syntaxhighlight>

* '''<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:

<syntaxhighlight lang="mIRC">on *:text:!help:#:{
  notice $nick For Help just state your question and pastebin any relevant code.
}</syntaxhighlight>

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)

<syntaxhighlight lang="mIRC">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 $+ .
}</syntaxhighlight>

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

Example:

<syntaxhighlight lang="mIRC">on $*:text:/^!test$/i:#:{
  msg $chan Test Worked!
}</syntaxhighlight>

==== 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:

<syntaxhighlight lang="mIRC">on *:action:$(*slaps $me $+ *):#:{
  describe $chan Slaps $nick with dried-up sandwich!
}</syntaxhighlight>

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

Example:

<syntaxhighlight lang="mIRC">;Assume %text is set to !cool
on $*:text:%text:#:{
  msg $chan I am the coolest! 
}</syntaxhighlight>

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

<syntaxhighlight lang="mIRC">on $*:action:$(/^slaps $me $+ /Si):#:{
  describe $chan Slaps $nick with dried-up sandwich!
}</syntaxhighlight>

===== 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:

<syntaxhighlight lang="mIRC">;let %chan equal #mSL,#help,#supprt
on *:text:!hi:%chan:{
  notice $nick Hello!
}</syntaxhighlight>

== 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:

<syntaxhighlight lang="mIRC">on *:signal:<eventName>:<command></syntaxhighlight>

A custom signal event can be called using the {{mIRC|/signal}} command:

<syntaxhighlight lang="mIRC">/signal [-n] <eventName> [parameters]</syntaxhighlight>

== See also ==
* [[List of on events - mIRC|List of on events]]

[[Category:mIRC]]