README

Henzell
-------

Henzell is the announcement and stats IRC bot for ##crawl on Freenode IRC.


Dependencies
------------

Henzell needs the Bot::BasicBot, DBI, and YAML::Any perl modules.

To install these on Debian, run:

    sudo apt-get install libbot-basicbot-perl libclass-dbi-perl libyaml-perl

If you want to use Henzell with a non-DGL crawl, at least build it
with these flags:

    make EXTERNAL_DEFINES="-DDGL_MILESTONES -DDGL_WHEREIS -DDGL_EXTENDED_LOGFILES"


Configuring Henzell
-------------------

Henzell can do several things based on how it's configured:

1. Make Crawl game announcements based on events in any number of
   Crawl logfiles and milestones files (if announce=1 and
   announce_channel is not empty).

2. Store new game events from any number of logfiles and milestone
   files into a MySQL database (if sql_store=1).

3. Answer queries for games and milestones (if sql_queries=1).

You configure Henzell by supplying a henzell.rc in the *directory from
which you run Henzell*. You can alternatively specify the rc filename
as a command-line option with:

perl henzell.pl --rc=some/path/to/myweirdrc

Some sample henzell rc files are included in this repository
(henzell.rc.cao, henzell.rc.sequell, henzell.rc.ircnet).


Henzell for announcements
-------------------------

If you're running a Crawl server and want Henzell to make
announcements, edit def.logs and def.stones and add entries for your
Crawl logfiles and milestone files. Enable announcements (announce=1
and announce_channel=##crawl) in your henzell.rc.

Also choose a unique abbreviation for your server. For instance,
crawl.akrasiac.org is abbreviated as cao, and this must be set both in
henzell.rc and in def.logs/def.stones to identify local logs:

In def.logs:

[local:cao]
/home/crawl/chroot/var/games/crawl04/saves/logfile

In henzell.rc:

bot_nick = NotTheRealHenzell
host = cao
announce = 1
announce_channel = ##crawl

This unique abbreviation is quite important if you're using sql_store=1.


Henzell for SQL queries
-----------------------

This is a lot more complicated than a simple announcement bot:

1. Install MySQL, create a database 'henzell' and a username 'henzell', and
   give the user access to the database with no password.

   Tip: For security, it's a really good idea to make sure your MySQL
   is listening only on localhost, or only on Unix sockets.

2. Set up the database schema with:

   mysql -u henzell -p henzell < henzell.sql

3. Make sure def.logs and def.stones are set up correctly.

4. Run Henzell with an rc that includes:

   sql_store = 1
   sql_queries = 1
   commands_file = commands/commands-sequell.txt

If you want the bot to do both announcements and SQL queries, you must
merge the commands files into one big list of commands.