This is the readme for spicytrivia.pl a jabber trivia bot written in perl. Written by Daniel Wedul (daniel@wedul.com) JID: spicylemon@dirtyredcommie.com spicytrivia.pl is meant to be run from a linux command line and has not been tested to run on a windows machine or a mac. In order to run it you need to install following perl packages: Authen-SASL-2.09, XML-Stream-1.22, Net-XMPP-1.0, and Net-Jabber-2.0 in that order. To do that run the installpackages shell script in the packages folder that this came with. Contents SpicyTrivia/spicytrivia.pl the main program SpicyTrivia/setupspicy.ini setup info SpicyTrivia/triviadb/* a bunch of questions SpicyTrivia/oldscores/ a folder for old score files readme This document Packages/Authen-SASL-2.09/* Authentication perl package Packages/Net-Jabber-2.0/* jabber perl package Packages/Net-XMPP-1.0/* XMPP perl package Packages/XML-Stream-1.22/* XML stream perl package Packages/installpackages script to install packages Setting up and running the program 0. run the installpackages script that is in the packages folder. This only needs to be done once and should scroll a lot of stuff on the screen and shouldn't end in an error. You may need superuser access in order to do this. You must be in the Packages folder for it to run right. 1. Create a login and password using any regular jabber client. 2. Open up setup.ini to set it up. a) enter the username from the login you just created in the USERNAME= field b) enter the password from the login you just created in the PASSWORD= field c) enter the server of the login you just created in the SERVER= field. If you are using a port besides 5222 then enter that into the PORT= field (you may have to add this field). d) decide on a room where the fun will be and put it in the ROOM= field. e) put the username that you will be playing with in the ADMIN= field. f) put some information about yourself in the OWNER= field. for example, my OWNER= field looks like this. OWNER=JID:spicylemon@dirtyredcommie.com (email: daniel@wedul.com) 3. Save and close setup.ini 4. put any files that have your trivia questions in the folder you decided on (default is triviadb). 5. It's a good idea to log in using your own jabber account and create the room ahead of time. This way you are the owner of the channel. 6. At the command line type perl spicytrivia.pl and hit enter 7. Now log in using your personal jabber account (if you haven't already) and join the trivia room that you chose. 8. Start having fun! Commands: All commands start with a ! There are two types of commands. "User commands" are commands that anyone in the channel can use. "Admin commands" are commands that only the user defined in the ADMIN= field can use. Commands are not case sensative. They can be given either in the group chat channel or through a private message. However, all responses will occur in the group chat channel. User Commands: !start if the triviabot isn't asking any questions this command starts the fun. !score this command displays the user's score. !topscores This command shows the top 5 scores !report This command is used to report an error in the question DB usage: !report Question F8.Q2003 is broken These will be stored in the file described by the REPORT= field of the setup file !suggest This will store suggestions in the file described by the SUGGEST= field of the setup file usage: !suggest I should get more points !stop This command will force the triviabot to stop asking questions after the current question has finished !help give a list of possible commands !bang Easter egg. Play safe. !addquestion This will store a suggested question in the file described by the SUGGEST= field of the setup file usage: !AddQuestion This does nothing but give the owner of the bot an idea for another question. It doesn't actually add the question to the database. !owner Outputs some information on the owner of this bot. The owner is the person in charge of running it. !invite This will send a groupchat invite from the triviabot to a user. usage: !invite The jabberid must be the full jabber id of the user you want to invite. A jabber ID has the form @ Admin commands: !disconnect logs the triviabot out, saves the scores and ends the program immediately. !exit same as !disconnect. !savescores Archives the old scores and saves the current ones. !resetscores Resets all scores back to zero. !leaveroom logs the triviabot out of the room !enterroom logs the triviabot into the room described by the ROOM= field of the setup file. !reloaddb Reloads the trivia database. Use this if you add or remove questions from the triviadb while the bot is running. If you removed stuff, do this right away or the bot may end up looking for a question that's not there and may cause it to crash. !timebetween Change the amount of time between when one question ends and the next question is asked (in seconds). usage: !timebetween value is the number of seconds to set the timebetween as. This is 20 when the bot starts. If the value is ommitted or anything besides a number, the bot outputs what the current timebetween is. !!! Cause the triviabot to send a message to the room it's asking questions in. usage: !!! This is best done in a private message to the triviabot. That way, no one sees you sending the command to the bot and the bot just spouts off whatever you want. setup.ini details setup.ini is the setup file that (by default) is used to easily change certain veriables in the trivia bot. Each line of this file consists of a variable name, followed by an equals sign (=) and the desired value. There should be no spaces. The entries can be in any order. Here is a list of the necessary entries and a description USERNAME The user login that the trivia bot will use PASSWORD The password for the user login that the trivia bot will use SERVER The server that the user login was created on ROOM The group chat room that the trivia bot will be asking its questions in. It should be a full room id. A full room id looks like this @ ADMIN The user that will be allowed access to certain commands that only the administrator should be allowed to use. Ideally this would be the username or nickname that you will be using while you are playing the game. OWNER The owner is some conct information on the person (generally you) that is running this bot. here are the optional entries NICK The trivia bot's nickname if you don't want the username to be used in the group chat. If this entry isn't used then the nick used will be the value set by USERNAME PORT The port that should be used to login. If left out the default port is 5222. DB The folder where all the questions are kept. SCOREFILE The file where the most recent scores are kept. SCOREARCHIVE The folder where score files will be archived. Scores are archived every time the scores are saved and a scorefile already exists. SCORES A string that describes the possible point values of questions. Each entry has this form x and each entry is comma delimeted. Here is an example: SCORES=100x4,2000x1,3000x1 When the point value for a question is chosen it is picked randomly from an array of possible scores. With the above line as the SCORES input the array looks like this (100, 100, 100, 100, 2000, 3000). FYI, there is also a 1/15 chance that a score value will be doubled when the question is asked. The default for this, if it isn't included is 100x4,200x4,300x4,400x3,500x2,1000x1,2000x1,3000x1 REPORT This is the file where question problems will be saved SUGGEST This is the file where programming suggestions will be saved ADMIN2 This is a secondary optional administrator ADMIN3 third optional administrator ADMIN4 fourth optional administrator ADMIN5 fifth optional administrator ADMIN6 sixth optional administrator ADMIN7 seventh optional administrator ADMIN8 eighth optional administrator ADMIN9 ninth optional administrator question database information: There is one questions per line. The first character in the line is the delimeter that is used. Between the first and second delimeter is the category. Between the second and third delimeter is the first answer. At some point there is two delimeters in a row. After the two delimeters in a row resides the question. Here are some examples /category/answer//question |guess|five|5||how many fingers am I holding up? ]TV]Jerry]]What is Seinfeld's first name? \category\answer1\answer2\answer3\answer4\\question? currently the trivia bot is set up to only accept the first given answer but the triviadb can hold more for future needs. To add a file full of trivia questions to the database simply put the file in the folder triviadb (or whatever you have DB= set to in the setup.ini). The way a question is chosen from the DB is that a file is picked at random, then a question from that file is picked at random. For this reason it is a good idea to do your best to spread the questions evenly among files in the DB. If there is a type of question that you don't like, then just put all those questions in one file and spread the other questions out among more files. For example, if you have 180,000 questions, but 80,000 are scramble questions then it might not be too fun to get a scramble question on 9 out of every 20 questions. Simply put all the scramble questions in their own file and spread the remaining 100,000 questions among 19 other files. That way there is a 1 in 20 chance to get a scramble question instead of 9 in 20. There is a provision for scramble questions. The scramble questions should look like this in the file /Scramble/word//word. The bot automatically scrambles the answer if the category is Scramble. So, even though the question and answer are the same, when asked, the characters will be scrambled. However, to keep the parser happy, a category, answer AND question must still be present in the question line. Also, the point value of scramble questions is loosly based on the word length. The archived score files are named with the base of the original score file with a date tag added then the original score file extention. If the file is scores.scr then an archive file could be scores--2005-04-22-13-34-56.scr the numbers, respectively, are the year, month, day, hour, minute, and second the the scorefile was archived. dbinfo.txt explanation In this file you will find a list off all the files in the question database. The first number is the index that the program sees that file as. The second number is the number of questions in that file. So, if you get a !report for F7.Q2882 that means someone thought something was wrong with question 2882 in file 7. Use dbinfo.txt to find out which file was file 7.