INSTALLATION ------------ Barp is distributed in two pieces: - barplib.0.3.3.tgz contains the source code to run the game - barpdata.0.3.3.tgz contains the initial maps and other game data For the initial installation, you must install both the source code and the game data. Subsequent installations may install either or both files. For example, if you edit the maps, you may not want to install the game data. You need to know the directory where Barp will live on the server. For example, the final installation might be /webserver/htdocs/barp. In that case, in the instructions that follow PARENT refers to "/webserver/htdocs" and ROOT refers to "barp". Note: the following instructions should work on most Unix systems. If you're installing this on another operating system, use equivalent commands. ---------- For an initial installation (or to install over the top of an existing installation), execute the following commands: cd PARENT cp /some/other/directory/barplib.0.3.3.tgz . cp /some/other/directory/barpdata.0.3.3.tgz . gunzip barplib.0.3.3.tgz tar xf barplib.0.3.3.tar --atime-preserve perl barplib.0.3.3/install.pl ROOT Once this has completed, you may delete barplib.0.3.3.tar and barpdata.0.3.3.tar. ---------- Version 0.3.2 included a number of unnecessary files that will remain on your system unless you do a clean install. Note that a clean install will not preserve any changes to maps you have made on your system. For a clean installation, execute the following commands: cd PARENT cp /some/other/directory/barplib.0.3.3.tgz . cp /some/other/directory/barpdata.0.3.3.tgz . gunzip barplib.0.3.3.tgz tar xf barplib.0.3.3.tar --atime-preserve perl barplib.0.3.3/install.pl TEMPROOT -- be sure to copy the files from your existing ROOT installation -- when asked if you want to configure your system, reply "no" mv ROOT SAVEROOT mv TEMPROOT ROOT Once this has completed, you may delete barplib.0.3.3.tar and barpdata.0.3.3.tar. ******************************************************************************** CONFIGURATION (AUTOMATIC) ------------------------- The installation script asks a series of questions to configure the installation. If the configuration changes, simply run the configuration script as follows: perl configure.pl ******************************************************************************** CONFIGURATION (MANUAL) ---------------------- If for some reason you cannot run the configuration script, you will have to manually configure your system as follows: 1) Edit barp.cf in the root directory (the one containing this README file). 2) If the path to your Perl executable is not /usr/bin/perl, you will have to edit all the executable files in the following directories so that they point to your Perl executable: gamecgi gamecgi/admin gamecgi/perl replay 3) Edit the following files replacing #PATH# with the path of the respective file: gamecgi/admin/.htaccess gamedata/.htaccess ******************************************************************************** WEB SERVER (Apache) ------------------- Players should be directed to a URL that corresponds to ROOT/index.html; for example, http://www.mydomain.com/barp/index.html Note: this configuration assumes you are running Apache (or a web server that can parse .htaccess files in the same way that Apache does). If this is not the case, you will probably have to do additional work to get the installation to run. Apache must honor the directives in .htaccess files. This means that the following Apache directives must apply to ROOT: AccessFileName .htaccess AllowOverride All Note: if you are not running Apache, then you may need to manually configure the web server to honor the settings in the following files: ROOT ROOT/gamecgi ROOT/gamecgi/admin ROOT/perl Among other things, this implies that all files with the suffix .cgi in these directories must be treated as executable Perl scripts by the web server. ******************************************************************************** FILE PERMISSIONS ---------------- When the files are accessed from a CGI script executed by the web server, the script must have read/execute permission for all files and directories and must also have write permission to gamedata and all its subdirectories. ******************************************************************************** MULTIPLE COPIES --------------- You may install multiple copies of the game on a server. In particular you may want to have one copy that your players use and another copy where you make your local modifications to the game. ----- If you are running on a system that supports symbolic links, your two versions can share maps, player files, etc. For example, from PARENT, you might execute: ln -s barplib/gamedata barptest/gamedata ln -s barplib/gameimage barptest/gameimage ----- You may find synch.pl to be very useful to synchronize the two versions. This Perl script assumes that the directory barplib contains one version and barptest contains the other. If your directories have different names, you will have to edit the script. The script saves old versions of all files that are updated in the directory barpHistory. It will save up to 9,999 versions of each file. It may be invoked as follows: perl synch.pl It accepts the following parameters: FILENAME The name of a file to be synchronized; otherwise, all files are synchronized. --auto Process all files without prompting --list List the files that would be processed ******************************************************************************** GAME ADMINISTRATION ------------------- For the most part, you will administer the game from within the game. The character designated as OWNER_PLAYER in barp.cf always has full administrative powers (that is, the player is automatically a Creator). To get information on all the administrative functions available from within the game, click on HELP and then get help for Immortal commands. You may choose to give other players various levels of administrative access using the immgiveimm command as follows: - immgiveimm PLAYER 1 makes the player mortal (the default) - immgiveimm PLAYER 2 makes the player a Helper - immgiveimm PLAYER 10 makes the player an Immortal - immgiveimm PLAYER 50 makes the player a God or Goddess - immgiveimm PLAYER 100 makes the player a Creator You can use the immgivecommand command to give your own player character access to administrative commands; this will allow you to play the game without being pestered by players as much. Speaking of being pestered, you can use stealth mode to make yourself invisible to everyone except Gods, Goddesses, and other Creators. You do this by: - using "immstealth on" or "immstealth disc" in the game - signing on via ROOT/gamecgi/stealth-v3.cgi Of course, you can use immgivecommand to give other player's access to commands they would not otherwise have access to. Additional administrative commands are in the ROOT/perl directory. The following commands can be used from the command line of a terminal session: - allwarp.pl Information about maps and how they are accessed. - browser.pl Analyzes the browsers that are being used to access the game. - cleanicons.pl Gets rid of unused player icons. - cleanplayers.pl A template for getting rid of unwanted player files; the script must be edited to specify the condition. Run it once to get the list of players that will be deleted. If the list looks reasonable, run it again with the argument --confirm - cron.pl A script that can be run daily to maintain the game - findemail.pl Find all players whose email address contain the string specified on the command line - fixplayerfiles.pl A template for updating player files; the script must be edited to specify the condition(s) under which changes are to be made and to update the data. - immortal.pl List all Helpers, Immortals, Gods, Goddesses, and Creators - locks.pl Check all game locks. If the game is running correctly, the last message will be "All checks performed." - logins.pl Access to the information about players who are logged in; can be used to send messages to individual players or to broadcast messages to all players (whether or not you're logged into the game). Enter "help" from the prompt. - reportvulgar.pl Generates a report on all vulgarities used in chat or tell messages. - searchplayers.pl A template for searching player files; the script must be edited to specify the condition(s). - tiles.pl Generates a report on the map tile icons that are available. The following administrative commands can be executed from a web browser: - backup.cgi Backs up all player files. Note: player files are automatically backed up every time the player logs in. - clean.cgi Cleans up player action logs (see Debugging below) - daily.cgi Execute a series of daily system maintenance functions - icons.cgi Show custom icons uploaded by players - report.cgi Send a daily report to the owner ******************************************************************************** LOCAL ENHANCEMENTS ------------------ The directory ROOT/gamecgi/local contains files that you may update to further customize your site: barpcmd.js Additional commands available in the "Slay Error Bunny" window (see Debugging) news.ht Site news that is added to the login screen ******************************************************************************** DISCUSSION LIST --------------- You may integrate YaBB (Yet Another Bulletin Board) to support Discussion Lists in the game. Information about YaBB is available from http://www.yabbforum.com/ For notes on integrating YaBB into your Barp installation, see the README file in ROOT/yabb. To activate the Discussion List in the game, the following variables need to be set correctly in barp.cf: - DISCUSSION_DIR set the the relative URL of the directory where YABB is installed - DISCUSSION set to 1 ******************************************************************************** DEBUGGING --------- The file barp.dbg is evaluated at runtime to determine if debugging processing should be performed or not. To enable debugging, edit the file and enter the appropriate conditions for debugging to be enabled. Some examples: $ENV{REMOTE_ADDR} eq "0.0.0.0" # if accessed from 0.0.0.0 $CHECK{playername} eq $CONFIG{OWNER_PLAYER} # if the owner is playing $CHECK{playerwizard} > 99 # if a Creator is playing 1 # always Note: only use "1" in extreme cases as this may seriously hamper the playability of the game ----- A special debugging version of the game is available when the following conditions are satisfied: - debugging is enabled (as described above) - the variable EVALUATOR in barp.cf is set to 1 - the player's wizard level is greater than or equal to the variable EVALUATOR_LEVEL in barp.cf. In this debugging version of the game, a window marked "Slay Error Bunnies" is added below the playing area. This window provides a JavaScript evaluator the will evaluate any JavaScript expression and show the results. It also supports a number of built-in functions. For more information on the built-in functions, enter "help" (without the quotes) in the "Expr:" box and click Evaluate. ----- Logs of all information returned to a player's browser can be created by setting the variable ACTION_LOG to 1 in barp.cf. These files can be manually perused when a player reports a problem. Note: the action logs are huge and will consume a lot of disk space. Entire player sessions can be replayed from the action logs. You access this powerful debugging feature by executing the command immreplay from within the game. Before you can replay a session, you have to extract it from the action log. Enter the name of a player (and optionally some text from the session) and click "Get sessions". Select the session you want to replay and then click the Session ID. From the list of extracted session, click "Replay" and you will be able to see exactly how the player session progressed. In the "Slay Error Bunnies" window, you can use the following commands while replaying a session: step Execute the next step in the session. list List the steps in the session. break # Set a breakpoint on step #. go Run the session until it reaches the breakpoint. stop Stop a running session before the breakpoint is reached. Once you're finished with a session, simply delete it. ******************************************************************************** GETTING HELP ------------ If you have problems getting Barp to run, send a message to barplib@yahoogroups.com and ask for help.