
Version: 1.3
Written by: GaB|Mindcrime (in real life Remy Wetzels <mindcrime@chello.nl>)
Copyright: 2002-2004 by Remy Wetzels

Mindcrime's IRC Live Reporter Bot.
==================================

The main focus of this document will be on the RTCW/ET version, but since the SOF2/STEF/MOHAA
version is not that different from the RTCW version you can use this document too...

Since the first beta versions of this reporter bot a lot of (bug)fixes and features have
been added. The problem with adding features is that for first-time users or for users with
little knowledge of the working of RTCW/SOF2 game engine and it's available modifications
(in short mods, like OSP, BANImod, SHRUB (all available for RTCW)) a programs tends to
become to difficult to use. This document is my effort to try and help you getting the bot
to work in a step by step guide without (hopefully) paying too much attention to all the
features this program has which only distracts you from the ultimate goal:

- Showing a game LIVE on an IRC channel for all you (clan)mates and (hopefully) showing
  to these (clan)mates what a great player you are!

From this point on I will try to explain to you how to use the bot as if you were a person
who - is using some version of the Windows Operation System (XP, 2000, ME, NT, W98) and
wants to run the bot in client mode (don't ask! this is a dummy guide on how to use this
bot and running the bot in server mode is beyond the scope of this document) - has just
downloaded the bot and never has tried it before and you never have done anything with
RTCW/SOF2 console commands.
It also focuses on connecting to servers running OSP. This is because most leagues these
days have a rule that states that games MUST be played on servers running OSP.
What I do ask from you is that you have a general knowledge of how to use IRC. (how to get
on an IRC server/channel, how to send private messages to a person on IRC) Knowing how to
work with a program like mIRC should be enough...
I also expect that you already downloaded the bot, you unzipped it and - if you have
downloaded the setup version you have - run the setup.exe program.


FIRST TIME SETUP
----------------

The bot in itself is a simple program. It just reads a logfile generated by RTCW and send
information it finds in there to an IRC channel...
For the bot to be capable to do that it needs to able to do two things:

1. The bot must be able to read the logfile generated by RTCW.
2. The bot must be able to connect to the IRC channel.

If you have downloaded and installed the bot there should be at least these files present:

- WolfBot.exe: the windows front-end
- WolfCMD.exe: the real bot (the part thats doing most of the work)
- irccolors_rtcw.cfg: configuration file for colors (gametime and gamestats)
- mapinfo_rtcw.xml: data file containing information about the rtcw maps

Let us first tackle the problem of generating a logfile. To do this you have to take the
following steps:

1. Start RTCW
2. Connect to a RTCW server
3. Wait untill you have connected to a server and you get into the limbo mode (the mode
   where you can choose sides, choose your function and weapons).
4. Open the console window of RTCW, the default key to get the console window is the
   backtick "`" (left of the 1 on the keyboard, just below the escape key). The console
   window should come scrolling down on the screen. At the prompt type the following
   command and then press the enter key:
   /logfile 2
5. Wait a second, if all goes well a statement should follow saying something like:

   Logfile opened on April 01 2002 12:12:12

6. Go play on the server for a couple of minutes or just be a spectator.
7. Quit RTCW

If all went well RTCW (SOF2/STEF/MOHAA) will have generated a file called rtcwconsole.log
(and in SOF2/STEF and MOHAA a file called qconsole.log). Now we got a small problem. RTCW
has the (for me and you a bad) tendency to change the location of this logfile if
you have played on a server running a mod like OSP. Normally the logfile is located
in the 'main' directory, but if you run OSP it will actually appear in the 'osp'
directory. 

Now we tackle the problem of getting onto the IRC channel...

Go to the folder where you installed the bot. When you installed the bot it should
have two executables:

1. WolfBot.exe
2. WolfCMD.exe

WolfCMD.exe is beyond the scope of this document. Let me just say that WolfBot.exe
is just a simple front-end - for running the bot, setting up the bot correctly and
being able to save these settings - for WolfCMD.exe, which has really all the
bot's intelligence.

1. Start WolfBot.exe

When you start WolfBot.exe for the first time you will see something like the picture
images/wolfbot10_01.jpg. What you see is the front-end of the bot which enables you to
configure some settings of the bot.
On the top right part of the window below the game icon you should see a checkbox with
'expert mode' next to it. Check the box...

In the top left part of the window you see the IRC OPTIONS. These options are all
about getting onto an IRC channel. And that is the part which we need here.

Set these options as follows (DO NOT CHANGE THESE UNLESS I STATE OTHERWISE, TOO MANY
ERRORS ARE MADE BY PEOPLE THINKING THEY KNOW WHAT THESE FIELDS ARE):

IRC OPTIONS:

Irc Server: irc.de.quakenet.org
Irc    Port: 6667
Irc Channel: #rtcwlivebot
Irc Chankey:
Irc Nickname: RTCWLBotXX          (for XX please use a random choosen number between 00 and 99)
Irc Language: English
Irc Username: MindBot             (DO NOT CHANGE, THIS IS NOT THE BOT'S NICKNAME!!!)
Q Usercode:
Q Password:

BOT PASSWORD:

enter a password (without any 'space' characters please!)

BOT OPTIONS:

enable OSP: off
show [kills/deaths]: on			(only available in 1.0)
team mode: off
messages on: off
start from EOF: off
continue from line: off, value 0	(you won't see the value in the new version)
quiet mode: off

TO THE RIGHT OF CONFIG OPTIONS:

Clientlog: on
Loglanguage: English (I currently support only the English/German languages of the game)

CLIENTLOG OPTIONS:

show match time: on			(only available in 1.0)
show stats after: on, wert 0

CONFIG OPTIONS:

game logfile: click on 'BROWSE' and select your existing rtcwconsole.log.
wait before opening: off
delete before opening: off		(only available in 1.0)
game mapfile: click 'BROWSE' and select the mapinfo_rtcw.xml file
color configfile: click 'BROWSE' and select irccolors_rtcw.cfg 
game server:

It should look something like images/wolfbot10q3_02_de.jpg or images/wolfbot10_02_de.jpg
(new version).

You should now have the setup for a first test run:

1. Go to IRC (using mIRC or something like that) and join the #rtcwlivebot channel
2. Click on START within the WolfBot.
   A DOS-box should appear (which minimalizes itself automatically) in the taskbar.

   In that DOS-box some messages will appear after a couple of seconds:

   XXX lines read...
 
   When it says something like:

   Error read_buf ...

   or the DOS-box disappears after a couple of seconds, then the bot seems to have a
   problem connecting to the IRC channel. Possible reasons might be that it can't connect
   to the IRC server or you have entered wrong IRC data into the IRC options (existing
   nickname, wrong channelname)
3. After a couple of seconds (this can take up to a minute (or 2) on some occassions) the
   bot should appear on the channel. It should show you the frags that were made on the
   server where you played a couple of minutes ago (after you had type /logfile 2 into the
   RTCW console).
4. The test has succeeded if the above happened, if not, then you probably had some problem
   described in 2.
5. Stop the DOS-box by opening it (in the taskbar below) and by clicking on the cross in the
   top right corner. The bot should now leave the channel and quit IRC.

If all is correct you should have WolfBot.exe still running.

For Live broadcasts you should change some things so that a live broadcast can be done
as good as possible:

Change at BOT OPTIONS:

start from EOF: off		(continue from line should automatically disappear)
enable OSP: on			(only for OSP games!!!)

Change at CONFIG OPTIONS:

delete before opening: on	(only available in 1.0)

It should look something like images/wolfbot10_03_de.jpg.

Open with NOTEPAD the file irccolors_rtcw.cfg (ONLY IF YOU HAVE VERSION 1.0Q3!!!) and
change:

# see also [playerstats] for the colors
# 1 = show, 0 = don't show
showplayerstats=0

into

# see also [playerstats] for the colors
# 1 = show, 0 = don't show
showplayerstats=1

This will show short player statistics (only frags/deaths) for each player.

Repeat the above test, but what happens next *if you are running OSP*:

- The bot appears on the channel after some seconds:

  [16:04:10] <RTCWLBot>  Mindcrime's RTCW LiveBot v1.0 

  but after that (probably) nothing more. (maybe the same message after a minute)

That's ok, that's how it should be.

Please take care to close the DOS-box each time after use. (THERE SHOULD ONLY
BE 1 DOS-BOX RUNNING SIMULTANEOUSLY!)

You now have the correct setup for broadcasting live matches. To save all you
settings you just have to close (by clicking on the cross in the top right
corner) the WolfBot.exe and click YES at "Save Options?"

Wenn you start the WolfBot.exe again you will see that it has save all changes.
(At least it should have).

Making live broadcasts:
-----------------------

When you want to broadcast live matches you should take the following steps
EACH time:

1. Remove (with you explorer in Windows) the old RTCW/osp/rtcwconsole.log
   (or let the bot do this for you automatically by checking "delete before opening"
    in the new 1.0 version)
2. Start the bot (maybe change the IRC Channel and/or Nickname) by clicking START
3. Check if the bot has joined the IRC Channel (it's ok for the bot to complaint
   about a logfile not present, because you just deleted the old one)
4. Start RTCW
5. Connect to the OSP server
6. When you are connected to the server, type into the RTCW console:
   /logfile 2
7. THIS ITEM IS OPTIONAL:

   do one of these things:
   a)
   make a video restart by typing into the RTCW console:
   /vid_restart
  
   or
   b)
   depending on the map, type into the RTCW console:
   /lbot map mp_beach

   possible mapnames:

   mp_assault
   mp_base
   mp_beach
   mp_castle
   mp_chateau
   mp_dam
   mp_depot
   mp_destuction
   mp_keep
   mp_ice
   mp_rocket
   mp_sub
   mp_tram
   mp_trenchtoast
   mp_village

   (any mapname defined in mapinfo_rtcw.xml)

   The bot should say something into your RTCW console like:

   Mindcrime's RTCW LiveBot: MAP SET TO mp_beach...
   Mindcrime's RTCW LiveBot: MAPTIME SET TO 08:00...

   You should only need to do a) or b) once. It is optional but it
   lets the bot know which map is currently played. Each mapchange from
   now on will automatically be detected by the bot, so there is no need
   to do this again.
8. THIS ITEM IS OPTIONAL:

   When the OSP game starts (when you hear FIGHT!) the bot will
   start transmitting the game into IRC. Since 0.8 it is possible
   to show objective/dyna plants/flags taken on the IRC channel.
   The only thing the bot can't show is who is playing on which
   side (Axis/Allies) and what the current score (in terms of
   (stopwatch) round wins).

   You can give that information to the IRC channel by:

   either
   a)
   You use the 'say' command to send a line of text to the channel,
   if you type into the RTCW console:
   /lbot say you can say something here
   
   The bot will transmit "you can say something here" onto the IRC channel.
   You could say something like:

   /lbot say RTCW-Liga MP-1: GaB-m][: 3-0 (ice 2-0/village 1-0)
   /lbot say SW round 4 about to start... GaB starts as Allies

   After each /lbot say XXX the bot says into the RTCW console:

   Mindcrime's RTCW LiveBot: DONE...

   or
   b)
   You use the 'score red', 'score blue' and 'showscore' RTCW console commands
   (or IRC commands):

   /lbot score red 4
   The bot sets the score of the Red/Axis team to 4

   /lbot score blue 2
   The bot sets the score of the Blue/Allies team to 2

   /lbot showscore [AN OPTIONAL TEXT HERE]
   When you use this command, the following appears on the IRC channel:
   
   [HERE COMES THE OPTIONAL TEXT]
   SCORE: Red - Blue: 4 - 2

9. Wait untill the game has finished... :)
10. Stop RTCW
11. Stop the DOS-box
12. Stop WolfBot.exe

THERE ARE A LOT OF OTHER /lbot COMMANDS. THEY ARE ALL DESCRIBED IN CONSOLECOMMANDS.TXT.

Some usefull ones:

- !renameteam red NAME    or  /lbot renameteam red NAME

  Sets the Red/Axis team name to NAME
  With !showscore this name will be show (substituted Red)

- !renameteam blue NAME   or /lbot renameteam blue NAME

  Sets the Blue/Allies team name to NAME
  With !showscore this name will be show (substituted Blue)

- !swapteams or /lbot swapteams

  This swaps the names and scores of both teams.

ALSO CHECK THE IRCCOMMANDS.TXT FOR ALL COMMANDS WHICH CAN BE SENT TO THE BOT VIA IRC.
There's also a mIRC script available which gives you control over the bot via the
mouse.


