


PBEMTOOLS(1)                                         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.




                          February 2001                         1





PBEMTOOLS(1)                                         PBEMTOOLS(1)


       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 pro-
              ducing 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  incre-
              mented whenever you feel like it.  Ex: chapter 1

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





                          February 2001                         2





PBEMTOOLS(1)                                         PBEMTOOLS(1)


       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/pub-
              lic_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 com-
              ment 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  asso-
              ciated  with  them.  You can set email to 'npc' for
              non-player characters.  Ex: email paul=muaddib@pen-
              nmush.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 under-
              stands all languages, use 'all' for  the  language.
              Ex: language paul=fremen



                          February 2001                         3





PBEMTOOLS(1)                                         PBEMTOOLS(1)


       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 char-
              acters.  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 atrei-
              des=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 ban-
       dits 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 dead-
       lines, 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 exam-
       ple, a player might write { If there are more than 3  ban-
       dits, 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. <<rid-
       ers>> causes subsequent text to be seen only by the  'rid-
       ers' 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 charac-
       ter's point of view.  Here's a brief example:



                          February 2001                         4





PBEMTOOLS(1)                                         PBEMTOOLS(1)


       <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 man-
       age 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.



                          February 2001                         5





PBEMTOOLS(1)                                         PBEMTOOLS(1)


       The  movefilter program also takes a move email message in
       Turn language as its input. Rather than archive  the  mes-
       sage,  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  indepen-
       dently  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  misformat-
       ted  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  mail-
       box in case you need it for reference or if movepipe fails
       for some reason.




                          February 2001                         6





PBEMTOOLS(1)                                         PBEMTOOLS(1)


       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  sim-
       ple 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, cat-
       moves 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.  rid-
       ers-3.src).  This prevents you from accidentally overwrit-
       ing a real Turn by giving catmoves the wrong turn  number.
       Before  you edit it, rename it to <pbem>-<turn> (e.g. rid-
       ers-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 charac-
       ter's point-of-view. If you didn't run fixturn, subsequent
       changes  in group membership or languages known by charac-
       ters 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.  rid-
       ers-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.



                          February 2001                         7





PBEMTOOLS(1)                                         PBEMTOOLS(1)


       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.  rid-
       ers-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 web-
       turn -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>/all-
       turns.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 .pbem-
       tools directory and located config files). The chapter  is
       given    as   a   number.    Here's   an   example:   all-
       turns.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



                          February 2001                         8





PBEMTOOLS(1)                                         PBEMTOOLS(1)


       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>+<sec-
       tion>#<section>" Link text</a>.  The user, pbem, and chap-
       ter 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 dis-
       cussed 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.




                          February 2001                         9





PBEMTOOLS(1)                                         PBEMTOOLS(1)


       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 (ren-
       dered 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



                          February 2001                        10





PBEMTOOLS(1)                                         PBEMTOOLS(1)


       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 web-
       turn, 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 ver-
       sions 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



                          February 2001                        11





PBEMTOOLS(1)                                         PBEMTOOLS(1)


       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.penn-
       mush.org/~alansz/pbemtools












































                          February 2001                        12


