MBOT README

       >>>>>>        mbot - mirage irc bot         <<<<<<<<

    Copyright (C) 1998,1999  Tiago Sousa <mirage@PTlink.net>

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

If you find bugs, improve something or just want to give ideas, contact me
through email or talk to mirage at PTlink or PTnet. :)
The latest version can always be found at:

    http://alunos.uevora.pt/~l12697/prog/mbot.tgz

----------------------------------------------------------------------------

1. HISTORY

It all started with the uncontroled lame wish to have my nick on IRC, 24h. ;)
The problem was that the shells i had at the time didn't run bitchx nor
eggdrop, so I had to look for an alternative...
At the same time, I wanted to start coding in C with Linux, I had done small
programs and wanted to do something more serious. So the project began, about
May 1998.

----------------------------------------------------------------------------

2. DESCRIPTION

It's a bot coded in C++, being started in C. Its main advantadge is that
several bots can run simultaneously in the same process, making it ideal for
shells where the backgound processes are limited, but not the connections.
It also spares lots of resources this way, compared to running many instances
of mbot.

Other caracteristics:
 - Database, dictionary-like
 - Can be in many channels
 - Has flood protection
 - DCC Send, easily accessible and configurable
 - DCC Chat with partyline
 - All the standard irc commands
 - Different access levels, defined with a userlist
 - Recognize and use irc services (Nick/ChanServ)
 - Log channels and privates
 - Can send logs to an email, when they are renewed
 - Scripting done with dynamic libraries in C++ (to which I've called modules)
 - Y2K compliant, 100% cyber-recyclable, no bytes were harmed during the
   coding of this program =)

----------------------------------------------------------------------------

3. WHAT ABOUT EGGDROP?

Eggdrop is the standard bot, but I've never liked it. Much less now. =)
Pros:
 - Easy scripts with TCL.
(which in mbot must be coded in C++, making it harder in many aspects)
 - Botnet.
(this one is on my waiting list, but don't hold your breath ;)
 - Lots of ready-to-use scripts which do almost everything.
(whatever it is, can also be done with mbot, it just has to be coded)
 - No knowledge of C/C++ required.
(same with mbot, unless you want to add something)
 - More things, yes.. for some reason it's the most popular bot...

Cons:
 - Only supports one bot per process
(mbot supports as many bots as the resources you have allow.)
 - Slower and memory-hungry
(in mbot the scripts are hardcoded, so it's faster and smaller than any TCL)
 - Less powerful scripts
(just compare C++ with TCL. Which one is the best? :)

----------------------------------------------------------------------------

4. COMMANDS

Commands are distributed through user levels and can be executed in privmsg
or DCC Chat.

Note that commands are defined in modules only, there are no default ones.
For example, to use the !get, you need the main_dcc module.

Some commands have "[]" or "|" in their sintax. [] means that the parameter is
optional. For example, in "!op nick [#channel]", if you execute "!op nick"
inside a channel, the bot will op nick in that channel. If you execute it
in pvt with the bot, it is necessary, even if the bot is only in one channel.
The "|", as in "!setmsg msg | <none>", means that only one of those two
parameters is to be used, in this case, "msg" or "<none>".

----------------------------------------------------------------------------

5. FILES

The bot uses several files for configuration and internal use, most of them
optional, according to the modules used.

WARNINGS: 
Files must *not* be changed while the bot is running, FOR THEY MAY GET
TRASHED! Turn off the bot or the corresponding module first.
To who will use multiple bots/processes: YOU CAN'T USE THE SAME FILE IN
MULTIPLE PLACES!

Actually, these rules aply only to files that are to be written on, such as
logs, .user, .word, etc. Others like the .get or .motd are ok, but I prefer to
warn about all of them, so later you don't come whining to me.. ;)

The only file which *must* exist is the main configuration one. It has the
following general structure:

<global options>
bot
<this bot's configuration>
bot
<this other bot's configuration>
(...etc...)

The "global options" are mainly the modules to be used. Although they are
present for all bots, each bot has its own configuration inside them.
For example, you may use the word module, and only declare a "word file.word"
in one bot, so only *that* bot uses it, not the others.
Each "bot" section is a bot, fully independent from the others, with it's
own options. They are all documented in example.conf.
Another important thing: all files must end with an empty line, otherwise the
last line of it won't be read.

----------------------------------------------------------------------------

6. USER SYSTEM

For the user system commands to work, the module main_user must be loaded.

The registered users are distributed in levels, which go from -1 to 10.
Registered users not identified with the bot have the ficticious level 1
(with the exception of the -1 level users). The others have level 0.

There are two ways to identify: the !pass command and with !chat, which opens
a DCC Chat, and asks for the password.

Sometimes the "identified" attribute seems to be lost unexplainably, which
sometimes happens with the !user* commands (yeah, bugs :), but most of the
time it's because of some ircd's protection, in not showing real ips when
you're not op, which may confuse the bot's authentification system. In any
case, just identify again.

Level -1 has a special property: besides denying access to all commands, users
with that level are automatically banned from the channel when the bot sees
them (shitlist).

----------------------------------------------------------------------------

7. THANKS

Although the bot was programmed mainly by me, many people have been important
throughout the project:
 - Possidon, for all the conversations we had about the bot, and the initial
   help on C.
 - Vladimir & korsh, for accepting the bot on #Evora even in its initial
   phase, which gave me motivation to continue and improve.
 - bluud, for helping me administer DarkSun, especially when the user
   registers began.
 - Netcyborg, for showing me how to declare variables of functions.
 - zerit0, for the cool mbot logo.
 - Many others, for the ideas, suggestions and using mbot on their channels.

