PBEMTOOLS(1)

NAME
pbemtools - tools for running play-by-email roleplaying games

SYNOPSIS

movepipe <pbem> [<character>]
movefilter <pbem> [<group>]
moveremind <pbem>

catmoves <pbem> <turn>
fixturn <pbem> <turn>
mailturn [-d] <pbem> <turn>
webturn [-q] <pbem> <turn>
doturn <pbem> <turn>
updatepages [-q] <pbem>

allturns.cgi?<user>+<pbem>+<chapter>+<character>
spewturn.cgi?<user>+<pbem>+<turn>+<character>
expand.cgi?<user>+<pbem>+<chapter>+<section>

DESCRIPTION

pbemtools is a suite of programs designed to help a gamemaster run a play-by-email roleplaying game. The tools automate the following functions:
  * Emailing customized Turns to the players, so that each player's
    email contains only things his/her character would see or know.
  * Redistributing PBEM player moves to the players, so that
    each player's copy of someone's move contains only things
    his/her character would see or know.
  * Archiving player moves
  * Reminding players to send moves
  * Putting together all the player moves to make Turn-writing
    easier.
  * Maintaining world-wide-web pages that allow people to read
    player moves or Turns from any character's viewpoint.
pbemtools is written in perl, and requires perl version 5.003 or later.

TERMINOLOGY

pbemtools uses this jargon:

GM  Gamemaster - the person running the PBEM. Probably you.

Player
    Someone who participates in the PBEM and isn't the GM.

Character
    A role in the PBEM taken on by a player.

Non-player character (NPC)
    A continuing character role in the PBEM taken on by the GM.

Turn
    A Turn is written by the GM and sent to the players by email. It describes the events of the PBEM and the actions of the characters. Turns are numbered consecutively, beginning with 1.

Move
    A move is written by a player and sent to the GM by email. It describes the actions that the player's character will take. If there are NPCs, a GM may write a move for an NPC and transmit it just as a player would.

Chapter
    A chapter is a collection of Turns. You can have as many or as few chapters as you like. Chapters are numbered, beginning with 1. Turn numbering does not reset when the chapter number changes. That is, if chapter 1 is turns 1-30, chapter 2 begins with turn 31.

CONFIGURATION FILE

In order to use pbemtools, you must create a configuration file for each pbem that you plan to manage. Configuration files are kept in the .pbemtools subdirectory of your home directory, and are named <pbem>.config, where <pbem> is a one-word name for your PBEM, in lowercase. For example, a PBEM set in the world of Frank Herbert's Dune might use a config file called dune.config.

pbemtools comes with a sample config file, sample.config, that you should copy and edit to create your config file. Lines starting with "#" are treated as comments and ignored; blank likes are also ignored. The sample file is liberally commented, but here's a brief description of the config directives:

fullname <name>
    A long descriptive name for the PBEM, used for producing titles for web documents. Ex: fullname Dune PBEM

subjecttag <string>
    A string to be prepended to the subject line of outgoing PBEM email messages. Ex: subjecttag [Dune]

chapter <number>
    This directive sets the current chapter number. Chapter numbers should start at 1 and be incremented whenever you feel like it. Ex: chapter 1

turndir <directory>
    Where to store or find Turns. A full directory path. Ex: /pbem/turns

webdir <directory>
    Where to find the home page for the pbem. A full directory path, not a URL. Ex: /pbem/public_html

weburl <relative url>
    A relative url that reaches the home page. Don't include http://host, and don't end in a slash. Ex: /~pbem

movedir <directory>
    Where to archive player moves, in html format. If you want to make these available on the web, this should be a directory under webdir. Ex: /pbem/public_html/moves

moveurl <relative url>
    A relative URL to reach the moves directory. Same rules as weburl. Ex: /~pbem/moves

cgiurl <relative url>
    The relative URL for the cgi script directory where the CGI scripts are installed, if they are. Ex: cgiurl /cgi-bin

smtp <address>
    The hostname or ip address of the smtp server to use when sending email.

maillinglist <email>
    The email address of the mailing list your players use to communicate with one another, if any. If you set this, Turns will include a reply-to header pointing to this address (enabling players to comment among themselves about Turns). If you comment it out, Turns will not have a reply-to header. Ex: dune-pbem@pennmush.org

gm <email>
    The address from which you send PBEM email. Ex: gm alansz@pennmush.org

email <character> = <email>
    An email address for a character's player. All player characters must have an email address associated with them. You can set email to 'npc' for non-player characters. Ex: email paul=muaddib@pennmush.org

language <character> = <language>
    A language that a character speaks. You may use multiple language lines to allow a character to speak multiple languages. If the character understands all languages, use 'all' for the language. Ex: language paul=fremen

group <groupname> = <character>,<character>,etc.
    A group of characters who you want to refer to by a group name. pbemtools implicitly creates a group called 'all', consisting of all characters, so don't redefine it. The GM is implicitly added to all groups, so don't add 'gm' to the list of characters. You can also use this feature if there's a character with a very long name and you want a shorter alias - put them in a group of one with whatever group name you like. Ex: group atreides=paul,jessica

TURN LANGUAGE

Both Turns and moves in a PBEM managed by pbemtools should be written in turn language. Turn language is just like writing plain text, except for 3 conventions:

(1) Text in []'s in a move is treated as a public note to the GM. For example, a player might write [ How many bandits do I see? ]. Text in []'s in a Turn is included when the Turn is sent to the players by email, but is stripped out of the Turn when it is read on the web. This makes it handy for personal notes, reminders about specific deadlines, etc. that are not for universal consumption.

(2) Text in {}'s in a move is treated as a public "plan" - a statement of "If this happens, I'll do this". For example, a player might write { If there are more than 3 bandits, I'll call for help }.

(3) A line which consists of <string> (a string within angle brackets) by itself is an instruction to change who will receive text that follows, until the next <string> is encountered. The string is a comma separated list in which which each element is:
  * A language spoken by one or more characters
  * A character name
  * A character group, enclosed in another set of <>'s
  * The word "all".
For example: <french> causes subsequent text to be seen only by French-speaking characters. <sally,bob> causes subsequent text to be seen only by sally and bob. <<riders>> causes subsequent text to be seen only by the 'riders' group. <all> causes subsequent text to be sent to all characters.
If the string begins with an !, its meaning is reversed. That is, <!edward> causes subsequent text to be seen by everyone except Edward.

The goal of Turn language is to enable the GM to write a complete Turn in a single file, which reads as a story in the third person omniscient, but is distributed to the players as a story in the third person with their character's point of view. Here's a brief example:
<all>
As the sun set, the riders made camp. Bob and Sally spoke in
hushed whispers, while the others joked and laughed loudly.
"What do you call a wrangler who leads his horses into a cave?"
Jim asked.
<bob,sally>
"Tomorrow, we'll face Six-Gun Slim and his band of outlaws,"
Bob murmured. "These others can joke, but I'm worried."
"Shucks," Sally replied, "You?"
<sally>
I wonder if I made a mistake bringing him along, Sally thought.
<all>
"A limestone cowboy!" Jim concluded, evoking guffaws
from the weary posse.

MANAGING MOVES

pbemtools includes a number of programs that can help manage player moves. These programs assume that players write their moves in Turn language or plain text, and then them via email to either a mailing list that all players receive, or to the GM alone.

The movepipe program takes an email message as its input and produces a simple html version of the email message which it stores in your Movedir. movepipe is designed to be called from within your email software, like this:
	|movepipe <pbemname> [<character>]
Because movepipe decides which player sent the move based on email address, if a player sends a move from an unusual address, you may have to add the optional character name when you call movepipe. If you know that players always use the same email address, you could put the call to movepipe in the mailing list's definition itself, so that movepipe is automatically called for any message sent to the list. Obviously, if you expect players to send non-move messages as well (questions, discussions, etc.), you might want to have a separate mailing list specifically for moves, and only run movepipe for messages from that list.
If Webdir is defined in your config file, movepipe also adds an entry for the move into the chapter master web page, creating the page if it doesn't exist. See WEB PAGES and CGI SCRIPTS, below, for information on chapter master pages.
movepipe determines the Turn number for a move by checking to see which Turns already exist in the Turn directory. If Turns 1-5 have happened, moves received are assumed to be for Turn 6.

The movefilter program also takes a move email message in Turn language as its input. Rather than archive the message, however, it distributes customized versions of the message to all the players by email. If you're using movefilter, players should not send their moves to a global mailing list, but only to you; when you run the move through movefilter, it will distribute it back to the players, customized. Again, if you have an email address specifically for move submission, you could automatically run movefilter (and movepipe - movefilter does not archive) on moves received by that address, to speed up the process.
movefilter is called as:
	|movefilter <pbemname> [<group>]
If the optional group name is included, only players whose characters are in the given group will receive moves. This is equivalent to causing "<all>" in Turn language to behave like "<<group>>" for that move, and might be useful if you've got two groups of characters operating independently and submitting their moves to different move addresses. movefilter never sends email to a player if there's nothing in the move which their character would see. movefilter adds an X-PBEM-Character and possibly an X-PBEM-Group header to each player's email, indicating their character's name and the relevant <group>, if any. The copy of the move sent back to the GM will have X-PBEM-Character: gm
If you use procmail to filter your email, the following recipe may be helpful to you:
	:0
	* ^Subject: (Something that all your players put in their moves, or
		     some other way you can tell it's a move. If you have
                     an alias for move submission, this can be
                     * ^To:.*movealias
                     instead)
        | $HOME/bin/movefilter gamename
	:0
	* ^X-PBEM-Character:.*gm
        {
		:0c
		| $HOME/bin/movepipe gamename
		:0
		$DEFAULT
	}
The first recipe runs incoming moves through movefilter which will either bounce them back (if they're misformatted and it can't tell which character sent the move) or mail them to everybody, including you (the gm). The second recipe catches these remailed moves and runs them through movepipe. The $DEFAULT clause keeps a copy in your mailbox in case you need it for reference or if movepipe fails for some reason.

Sometimes players forget to send moves. The moveremind program sends a reminder email message to players who haven't sent moves for the current Turn. It's called simple as:
	moveremind <pbem>

PRODUCING AND DISTRIBUTING TURNS

Another important function of pbemtools is the production and distribution of Turns.

The catmoves program finds the moves for the current Turn, archived in Movedir by movepipe, and concatenates them into a file from which you could write a Turn. Although it's not necessary to use catmoves to write a Turn, catmoves simplifies the process by putting all of the moves together in the right order.
catmoves tries to handle cases in which one move quotes a part of an earlier move and "replies" to it, by putting the "reply" paragraphs after the quoted paragraphs in the file it generates. It's not always perfect at this. It surrounds groups of paragraphs by a given speaker with lines like ">>> Name" and "<<< Name" so you can tell which paragraphs came from who.
catmoves is called as:
	catmoves <pbem> <turn>
The turn is specified by number. The output from catmoves is put into your Turndir as <pbem>-<turn>.src (e.g. riders-3.src). This prevents you from accidentally overwriting a real Turn by giving catmoves the wrong turn number. Before you edit it, rename it to <pbem>-<turn> (e.g. riders-3) and the other pbemtools programs will be able to work with it.

The fixturn program edits a Turn file and expands the Turn language tags that refer to character langauges, character groups, or that use "!" into lists of characters who should receive a given Turn. This is important if you're going to make Turns available on the web from each character's point-of-view. If you didn't run fixturn, subsequent changes in group membership or languages known by characters would cause them to see things in earlier moves to which they aren't entitled. fixturn is called as:
	fixturn <pbem> <turn>
The turn is specified by number. The Turn file should be located in the Turndir and named <pbem>-<turn> (e.g. riders-3).

The mailturn program distributes a Turn by email to the players. Each Turn is customized so that players receive only the parts of the Turn that their character would see or know. mailturn is called as:
	mailturn [-d] <pbem> <turn>
The turn is specified by number. The Turn file should be located in the Turndir and named <pbem>-<turn> (e.g. riders-3). If the -d switch is given, mailturn will not send any email; instead, it will produce a set of files showing what would be mailed to each character. The files are named <pbem>-<turn>.<character> (e.g. riders-3.sally, riders-3.bob, riders-3.jim) and located in the Turndir.

The webturn program adds links for the Turn to the chapter master html page, creating it if it doesn't exist. It's only useful (and it only works) if you've got Webdir and Cgiurl defined in your config file. webturn adds a link for the new Turn under the "Story" section of the web page and under each player's point-of-view section. See WEB PAGES and CGI SCRIPTS for information on chapter master pages. webturn is called as:
	webturn [-q] <pbem> <turn>
The turn is specified by number. The Turn file should be located in the Turndir and named <pbem>-<turn> (e.g. riders-3). If the -q switch is given, webturn will not report an error if you haven't defined Cgiurl; it will exit quietly.

The doturn script simply calls fixturn, mailturn, and webturn -q in sequence. You can thus process an entire newly written Turn by calling:
	doturn <pbem> <turn>

The most common sequence for producing and distributing turns is:
1. catmoves <pbem> <turn>
2. cd <Turndir>
3. mv <pbem>-<turn>.src <pbem>-<turn>
4. Edit <pbem>-<turn>
5. doturn <pbem> <turn>

CGI SCRIPTS

pbemtools includes 3 handy CGI scripts.

allturns.cgi produces a concatenation of all the Turns in a given chapter of a given pbem from a given character's (or the GM's) viewpoint. This is handy if you want to print out the entire PBEM story. It's called within a web page as <a href="/<Cgiurl>/allturns.cgi?<user>+<pbem>+<chapter>+<character>"> Link text</a>.
The <user> is the login name of the user who's running the PBEM (this enables allturns.cgi to find the users .pbemtools directory and located config files). The chapter is given as a number. Here's an example: allturns.cgi?alansz+mage+1+edward. To produce a turn from the GM's viewpoint, use 'gm' as the character name.

spewturn.cgi produces a single Turn from a character's (or the GM's) viewpoint. It's called from a web page just like allturns.cgi, but instead of given a chapter number, it should be given a Turn number.

PBEM web pages can get very long if they include a link to each Turn for each character. expand.cgi is a script that provides some cosmetic help by giving the illusion of an expanding outline, like the outline in a word processor. For example, a page might be presented like this:
	Turns from the viewpoint of:
		Sally
		Bob
		Jim
When the user clicks on "Sally", the page is reloaded and now appears like this:
	Turns from the viewpoint of:
		Sally
			Turn 1: The beginning
			Turn 2: Saddle up!
			Turn 3: Campfire
			etc.
		Bob
		Jim
Expanding another character's link contracts Sally's. It's easier to see than to explain. :)
expand.cgi is called from within a web page as: <a name="<section>" href="/<Cgiurl>/expand.cgi?<user>+<pbem>+<chapter>+<section>#<section>" Link text</a>. The user, pbem, and chapter are the same as in allturns.cgi. The section can be any string; I usually use the character name when doing a "Turns from the viewpoint of" section. Don't use "nobody" as a section name, however; the updatepages script discussed below requires that there by no section with that name.

WEB PAGES

The web pages that pbemtools actively manages are the chapter master pages, named ch<#>master.html (e.g. ch1master.html), and the chapter home pages, named ch<#>.html (e.g. ch1.html). Both live in Webdir.

Chapter master pages contain the complete set of links for every Turn for every character (including the GM) and for every move for every Turn. Chapter home pages are produced from the chapter master pages by collapsing sections into outline headings that expand.cgi can expand. The upshot of this is that you can modify the text in the chapter master pages as much as you like, but don't modify the chapter home pages, because they get overwritten when they are regenerated from the master pages.

The updatepages script regenerates the chapter home pages from the chapter master pages. If you modify the master pages, you should run this script. It's called as:
	updatepages [-q] <pbem>
The -q switch causes updatepages to work quietly, rather than reporting the pages it updates.

If Webdir is defined in the config file, a new chapter master page is generated whenever pbemtools needs one and can't find one (i.e., when movepipe or webturn is run and there isn't yet a chapter master for the chapter.) The newly generated chapter master file looks like this (rendered as text with links referenced as [1] - [4]):
                  $Fullname: Chapter $Chapter: $chapter_name

Game Turns
   This presentation of the story includes all the details that any
   character perceives, including thoughts, dreams, languages, etc. If
   you'd like to follow the story from the vantage point of a particular
   character, rather than from an omniscient vantage point, skip on to
   The Story (Player Views).

   Here is a [1]concatenation of all the Turns for convenient printing.

The Story (Player Views)
   You can read the story from the viewpoint of:

     * [2]Sally
          + [3]All Turns to date
     * Bob
          + All Turns to date

Player Moves
   Player moves are archived here in their "omnilingual" form - that is,
   as if the reader understands all languages. If you're a player and
   don't want to read things your character wouldn't know, skip the moves
   and read only Turn postings.
     * [4]For Turn $turn
References
   1. /$Cgiurl/allturns.cgi?$user+pbem+$Chapter+gm
   2. /$Cgiurl/expand.cgi?$user+$pbem+$Chapter+Sally#Sally
   3. /$Cgiurl/allturns.cgi?$user+$pbem+$Chapter+Sally
   4. /$Cgiurl/expand.cgi?$user+$pbem+$Chapter+move$turn#move$turn
Link [1] is a call to allturns.cgi to show a concatenation of the Turns from the GM's (omniscient) point of view. Link [2] is a call to expand.cgi so that we can expand the list of Turns from Sally's point of view. There's a link like this for each character defined in your config file at the time the chapter master is created. Link [3] is a call to allturns.cgi to show all of the Turns from Sally's point of view. As Turns are added to the master by webturn, links to individual Turns will also be listed under each character, along with calls to spewturn.cgi. Finally, Link [4] is a call to expand.cgi to expand the list of moves sent for the first Turn in the chapter.

An examination of the html in a chapter master will also show some comments. Each player's view will have a comment that looks like this:
	<!-- SALLY -->
The current Turn's moves section, near the end of the file, will have a comment that looks like this:
	<!-- INSERT HERE -->
These comments are crucial to the operation of the scripts that update these pages, and should not be touched.

FILES

In addition to the programs described above, there is a library file distributed with pbemtools:

pbemtools.pl
    This file contains the common code used by many of the pbemtools programs.

BUGS
The catmoves program may not do its interpolation of replies quite right, and it adds a lot of junk.

AUTHOR

pbemtools was written by Alan Schwartz. Alan can be reached as: alansz@pennmush.org

Thanks are due to the players in my Riverworld and Mage PBEM games who put up with the bugs in the prerelease versions of pbemtools!

COPYLEFT

Copyright (C) 1998 Alan Schwartz <alansz@pennmush.org>

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., 675 Mass Ave, Cambridge, MA 02139, USA.

VERSION

This is pbemtools version 1.4. The most recent version can always be found at http://www.pennmush.org/~alansz/pbemtools