MBOT README

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

    Copyright (C) 1998-2000  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/

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

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 advantage is that
several bots can run simultaneously in the same process, making it ideal for
shells where the background processes are limited, but not the connections.
It also spares lots of resources this way, compared to running many instances
of mbot.

Other caracteristics:
 - All the standard irc commands are available
 - Can be in many channels
 - Flood protection
 - Database, dictionary-like
 - DCC Send, easily accessible and configurable
 - DCC Chat with partyline
 - 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
 - Extensions done with dynamic libraries in C++, to which I've called
   modules, and can be added/removed while the bot is running

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

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.
(i don't really understand the "usefulness" of it)
 - 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)
 - Fine-grained user levels
(overly complicated, in my opinion - i much prefer mbot's system)
 - 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.)
 - More complex
(mbot's configuration and usage is far less complicated)
 - Slower and memory-hungry
(in mbot the scripts are hardcoded, so it's faster and smaller than any TCL,
and you need a separate process for each bot)
 - 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 many commands are defined in modules only. For example, to use the
!seen, you need the seen 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, depending on the modules used.

WARNING: 
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 that later on 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 and log creation.
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. USERS

  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.

  Often 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 or you're not in the same channel, 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. LOGS

  The logging system is made of two components: one is main system log file,
which is defined by the "botlog" configuration option. If the bot crashes,
doesn't show up on irc, if there's a problem of some sort - that's the place
to look into.
  The other component is a much more user-definable system, perhaps a bit
complicated at first sight. It's configurable via "logcreate" and "logmail"
options. The idea is, you create a sort of logging facility, defining
caracteristics such as file to log to, timestamp mode, flush mode and rotation
mode, and later in the configuration file you can have modules using them.
Rotanting logs are renewed at 6 a.m. everyday by default, change that in
inc/CLog.h if you want.

  Let's see a configuration example of this:

module mod/log.so
logcreate mychannel 1 0 mychannel.log mychannel.old.log
logcreate pvt 1 1 pvt.log
bot
log mychannel #mychannel
log pvt <privmsg>

  What does that do? First, it creates a logging facility called "mychannel",
using mychannel.log (which rotates to mychannel.old.log) as the log files,
always flushed, and time-only timestamp mode (see example.conf to more details
on the options). Then another one called "pvt", that writes to pvt.log and
doesn't rotate.
  Then, you use them in the log.so module to log all events of #mychannel to
the loghandle "mychannel", which you defined previously, and all private msgs
with the bot to the log named "pvt".
  My purpose with this is to be able to log multiple things into the same
logfile, such as pvt's with the same nick, but on different bots (remember
that mbot is capable of having several bots living simultaneously on the same
process). Of course, you can create as many of those logging facilities as you
like and send whatever you want to them. For example, the log, watch and
alice modules use them.

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

8. ALICE

  A very popular module of mbot is ALICE. It's a "port" of C-Alice to mbot,
with many bugs fixed and security checks added. Still, it's not as stable as
i'd like. You can read all about ALICE at http://alicebot.org. Basically, it
uses a pattern match / response strategy to simulate a human conversation.
  To get the module working, you need the data files that define ALICE's
behaviour. You can either get them from alicebot.org, or you can use the
ones i have at mbot's site (recommended). I recommend that because I
included some tags to make ALICE interact with the "seen" and "word"
modules, and also did some fixes/cleanups. To talk to the bot in a channel,
use the bot's name as the first word of a line. In private, everything
except !commands is interpreted by ALICE. You may want to edit
log/localuser.txt and change it to your settings. If you change any of the
AIML files, you must delete data/patterns.txt and data/templates.txt, so
mbot can update them.

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

9. 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.

