========================================
========================================
=         "How to create a mIRC bot" Tutorial            =
=                         2/5/07                                   =
=  Pass - irc.unhandledexceptions.com - #Testing    =
========================================
========================================

Well, mIRC scripting is easy, for the most part. The hardest part, honestly, is remembering what identifiers to use.
For the record, I'm basing this tutorial on thinking that you, the reader, know almost nothing of mIRC's abilities.


========================
=          The Beginning           =
========================

Bots are scripts that are made to react to actions, or "events" as labeled in mIRC's /help file.
There are many types of events, but for now, I'll cover the basic ON TEXT event for bots, since that's how you communicate with it.

<Example #1>
ON *:TEXT:*:*:{ command }
</Example #1>

Now what Example #1 did was provide a template for the ON TEXT event.
Let's disect the example, shall we?

ON <level>:TEXT:<text>:<*,?,#>:{ command }

 - "level" refers to user levels. I will not being covering them. However, you may use "!" to signify that the user [your Bot] will not be included in the action
  -> example: ON !*:TEXT:*:*:{ command }

 - "text" is the text that the script will be searching for. 
  -> example: ON *:TEXT:*test*:*:{ command } 
   --> This will be triggered whenever someone types "test", or a word with the word test inside of it, seeing as "*" are wildcards. * Note: Wildcards are not mandatory.

 - "*,?,#" are the locations the bot will be listening on. "?" refers to queries [/msg's]; "#" refers to channels, and "*" refers to anywhere. * Note: "=" is used for DCC chats
  -> example: ON *:TEXT:test:#:{ command } - Searches for "test" in a channel, and will be triggered if a user types it.
  -> example: ON *:TEXT:test:?:{ command } - Searches for "test" in a query, and will be triggered if a user types it.
  -> example: ON *:TEXT:test:*:{ command } - Searches for "test" in both queries and channels. Will be triggered if a user types it.

* Tip: Using "ON *:TEXT:*:?:{ }" is more secure when users are registering for bots, as to prevent password leakage. 
 

========================
=          Storing Data             =
========================

Data storing is key to writing a good bot. Bot's that require registration should most definitely store data in OUTSIDE sources, not via variables.
To me, password protection [ie, encrypting] isn't a big deal, however, others may want to look into it. I do not take IRC so seriously as to do that.
So, if you're looking for password encryptions, this isn't the place.

; HASH TABLES - USAGE 

Now, this is where bot scripting gets tricky, and from here out, is going to be based on my bot scripting beliefs. Fuck other people.

I believe that HASH TABLES are one of the best ways to store data that needs to be retrieved while playing a game, or even just checking lists
 since it is the fastest method.
Also, they can store information almost exactly like .ini files, but are proven faster.

To make a hash file, you're going to want to use the "/hmake" command.
 Syntax: /hmake <table name> <#>

The table name, as it states, is obviously the name of the hash table that will be created. 
The "#" refers to the max number of items that can be stored in the hash table. The default is "100", and is generally good enough.

To retrieve information from hash tables, you would use the "$hget" identifier. 
 Syntax: $hget(<table name>,<item/#>)

Table name = Hash table name
"item" is the item you're searching for. Hash tables store data like so:

<Example #2> 
              [TABLE]
      __________________
#1] ITEM       |       DATA
#2] ITEM       |       DATA

</Example #2>

So, as Example #2 shows, you can either search via the Item name, or the item number. Both works.

To add items to the hash file, you simply need to use the "/hadd" command. 
 Syntax: /hadd <table name> <item> [data]

When using the "/hadd" command, it is not mandatory to add the [data] section. However, the rest is. With hash tables, you ARE allowed to add items with no value.

To delete items from a hash table, the "/hdel" command is what you want.
 Syntax: /hdel <table name> <item/#>

The "/hdel" command allows for either specifying the line number you want to delete, or the item itself. 

"/hfree" is the command needed to delete, or "free up" an entire hash table.
 Syntax: /hfree <table name>

....Self-explanatory, agreed? Agreed.

; *.INI FILES - USAGE

INI files are useful in the sense that you can manually edit them with ease, and are relatively good for storing data that isn't intended for use whilst the bot is in action.
I use INI files for saving user information, and use hash tables when the script is in motion, so a combination generally works pretty well.

INI files are setup like so:

[SUBJECT]
item=value

So, let's start from there. 
To add an item to an INI file, use "/writeini".
 Syntax: /writeini <filename.ini> <subject> <item> <value>

As you can see, it requires a lot of effort than just typing "/hadd table item", but that's part of scripting. Remember, custom aliases can make your job a LOT easier.
Now the "filename.ini" obviously is the filename, with the extension ".ini". The "Subject" is the section in the INI that has the [] brackets around it. item/value = self-explanatory.

In order to remove an item from an INI file, use "/remini"
 Syntax: /remini <filename.ini> <subject> [item] 

Removing items from an INI file is basically the same as adding them, minus the "value". To delete an entire section, and not just an item within a section, you
may leave out the item in the command.