Provided by: xletters_1.1.1-5.1build2_amd64 bug

NAME

       xletters - catch falling words

SYNOPSIS

       xletters [ options ]

DESCRIPTION

       X  Letters  is  a  game  under X to improve your typing skill.  It is inspired by the game
       letters(6) by Larry Moss and Brent Nordquist (which itself is inspired by the game  Letter
       Invaders, and ultimately by the famous Space Invaders).

       The goal of the game is to destroy the words that fall down from the top before they reach
       the bottom.  To destroy a word, you must simply type it.

       The game is organized in levels of increasing difficulty.  Each level is divided into  two
       parts:  a  normal  part  and a bonus part.  During the normal part, ordinary english words
       will fall down (found in the system's dictionary, usually  /usr/dict/words).   During  the
       bonus part, the words are randomly generated from printable ascii characters.

       If  a  word  hits  the ground during the normal part, you lose a life (you have five lives
       initially), and the word disappears (but the others keep on falling).  If a word hits  the
       ground  during the bonus part, the bonus part simply ends, with no additional penalty, and
       the game proceeds to the next level.

       The normal part of a level ends when a certain time has elapsed.  The bonus part ends when
       either  a certain time has elapsed or when a word has hit the ground.  The normal duration
       of a half-level is 600 time units, or 45 seconds (whatever the level).

       Typing a word correctly makes the word disappear and scores you one point per letter, plus
       five  more  points,  plus  another extra three points if the word was destroyed in the top
       fifth of the window.  This is the only way of gaining points: partially  typed  words  are
       not  worth  anything,  and  even moving to another level doesn't bring you points (this is
       because even if you don't type anything you will go beyond the first level).

       Short words fall faster than long ones.  Unless otherwise specified at compile time, words
       are not allowed to collide into one another.  Therefore, when a new word appears, the game
       makes sure that all the words below it fall at least as fast as it.  The fall rate of  the
       words  also increases with the level (it is, however, the same between the normal part and
       the bonus part of the same level).  The rate at which words appear is constant on a  given
       level, but it increases with the level.

       A  word  is  considered  typed when the last printable characters that you typed since the
       word appeared are precisely the letters of the word.  This means in particular that it  is
       possible to ``kill two birds with one stone'' if one word ends with the letters with which
       another one begins - in  fact,  if  two  identical  words  appear  (an  unlikely  but  not
       impossible  situation), you need only type one of them.  To say things differently, if you
       type a correct letter it will make your position in the word advance by one letter, and if
       you  type  an  incorrect letter, it will make your position move back to the last place in
       the word that matches the characters you typed.  The current  position  in  each  word  is
       indicated  by putting the already typed letters in a different color (normally red).  Note
       that a different behaviour is selectable at compile time with which a  wrong  letter  will
       cause  all  letters  to  be considered wrong (to make the difference obvious, consider the
       word ``abracadabrx'': if after having typed ``abracadabr'' you press an ``a'', the  normal
       behaviour  will  take  you  back to ``abra'' whereas the alternate behaviour will take you
       back to the beginning).

       The game keeps a high score table.  When the game is over, one way  or  another,  xletters
       will  show, for the user and for the twenty best players, the name, the level reached, the
       final score, and the time during which the game was running.   Normally,  each  player  is
       allowed only one entry in the high score table.  This can be modified at compilation time,
       however.

CONTROLS

       The top of the window shows three buttons.  The Quit button will take you out of the game,
       the  Pause  button will pause the game or resume it if it was already paused, and the Next
       button will move to the next level (normal part).  These  buttons  can  also  be  accessed
       through accelerators: the ``Escape'' key will quit the game, the ``Tab'' key (or ``Pause''
       if you have one) will suspend it or resume it, and the ``Page Down'' key (or  ``Next''  if
       it is so labeled) will advance one level.

       Three  labels  on  the  right  of  the  buttons are used to indicate your lives, score and
       current level.

       Other than that, to play the game you must simply type the words.  In order for the typing
       to  be effective, your mouse cursor must be in the game space (the large square area below
       the buttons and labels).   If  you  start  typing  while  the  game  is  paused,  it  will
       automatically resume.

       Scoring is made much more complicated if you choose to use the Next button to warp through
       levels.  (The point is that it should be used to avoid having to go through all  the  easy
       levels if you already type very fast.  So it should not handicap you excessively by giving
       you no points which you would have gotten if you had worked your way through those levels.
       On  the  other  hand, it should not be an obvious way of gaining arbitrarily many points.)
       Here is the way it works: when you use the Next button to warp to the next level, you gain
       350  ``virtual'' points.  Those points are indicated in parentheses after your real points
       in the score label.  They are not worth anything by themselves.  On the other hand, if you
       have  virtual  points, every time you gain some points, that many virtual points will also
       be converted to real points (until you no longer  have  virtual  points).   Thus,  virtual
       points are worth something only if you prove yourself good enough to make them so.

       There  are  some  restrictions to the use of the Next button.  First, it will only work in
       the bonus part of a level, or if no word has fallen  lower  than  the  top  fifth  of  the
       screen.   This  is  so  you can't use it to get yourself easily out of a tricky situation.
       Second, if you already scored some points on the current level, using the Next button will
       award  you  fewer  than the normal 350 virtual points (see above), in fact precisely twice
       fewer than as many points as you gained on the level (but no less than zero, of course).

TRAINING MODE

       xletters has a training mode, which you can invoke using the -train command  line  option.
       In  training  mode, only one (english) word appears at a time, anywhere on the game space,
       and it does not fall.  A new word appears as soon as you finish typing the  previous  one.
       In training mode, there are no lives, points, levels, or bonus words.

DEATHMATCH AND DUEL

       xletters  also  has  the amazing ``deathmatch'' mode.  To invoke this mode, use the -death
       command line option.  This has the following effects on the behaviour of xletters:  first,
       it  will  read  words  on  the standard input, and make them fall.  Second, you can choose
       between typing falling words, or typing a special word in a special part of  the  display,
       just above the game space.  To switch between both modes, use the Mode button or press the
       ``Backspace'' key.  The special word typed must be an english word: if the letter you type
       makes  the  word  fragment  no  longer  begin  a  word  in  the dictionary, it immediately
       disappears.  When you type a full word, you can then send it by using the Send  button  or
       by pressing the ``Return'' key.  The word sent gets printed on the standard output.

       These features make sense when two copies of xletters are run in deathmatch mode, with the
       standard output of each being sent to the standard input of the other (possibly across the
       network).   Then the player on each game can not only kill his falling words but also send
       words to the other player.

       Even more extreme than the ``deathmatch'' mode is the ``duel'' mode, activated through the
       -duel command switch.  In duel mode, the computer does not send words of its own, and only
       words sent through the standard input will appear.  In this case, there is no Next button,
       and  switching  to the next level can only occur after a certain amount of time.  In fact,
       there are no bonus parts of levels, so levels change twice more  rapidly  than  in  normal
       play.   Moreover,  a  level  change  does not erase all the current words contrary to what
       happens in normal (or deathmatch) mode.

       The X Letters distribution includes a shell script named xletters-duel  which  uses  Avian
       Research's  netcat  program  (nc)  to open a socket, run xletters in duel mode, and try to
       connect to the same socket on a  given  computer.   Thus,  two  people  on  two  different
       computers  can  play  a  duel  by  each running xletters-duel with the name of the other's
       computer as parameter.  (Both copies must be run within five seconds of the other.)

OPTIONS

       X Letters recognizes all the standard X Toolkit command  line  options,  among  which  the
       following:

       -bg color
              Specifies the background color to use.

       -fg color
              Specifies the foreground color to use for the labels and buttons.

       -fn font
              Specifies the font to use for displaying the labels and buttons.

       -name name
              Specifies  the  application  name  under which resources are to be obtained, rather
              than under the default executable file name.  name  should  not  contain  ``.''  or
              ``*'' characters.

       -title string
              Specifies the window title string.

       -geometry geometry
              Specifies  the  preferred  position  of  the  window.   Specifying  a  size  is not
              recommended.

       -display display
              Specifies the X server to use.

       -xrm resourcestring
              Explicitely give a resource string.

       The following additional options are recognized by xletters:

       -wfn font
              Specifies the font to use for the falling words.  (Sets the wordFont resource.)

       -wc color
              Specifies which color to use for the words.  (Sets the wordColor resource.)

       -tc color
              Specifies which color to use for the correctly typed part of the words.  (Sets  the
              typedColor resource.)

       -gbg color
              Specifies  which  color  to  use  for  the background of the game space.  (Sets the
              gameSpace.background resource.)

       -notrain
              Do not go in training mode (this is the default).  (Sets the trainingMode  resource
              to ``False''.)

       -train Run  the  game  in training mode (see TRAINING MODE above).  (Sets the trainingMode
              resource to ``True''.)

       -nodeath
              Do not run in deathmatch or duel mode (this is the default).  (Sets  the  deathMode
              resource to ``normal''.)

       -death Run  in  deathmatch  mode  (see  DEATHMATCH  AND  DUEL above).  (Sets the deathMode
              resource to ``death''.)

       -duel  Run in duel mode (see DEATHMATCH AND DUEL above).  (Sets the deathMode resource  to
              ``duel''.)

       In addition, xletters recognizes -help and -version options.

WIDGETS

       groundBox (class Box, parent (toplevel))
              This is the main application box that supports all the other widgets.

       label (class Label, parent groundBox)
              The xletters label.  The text of this label cannot be changed.

       quitButton (class Command, parent groundBox)
              The Quit button.

       pauseButton (class Toggle, parent groundBox)
              The Pause button.

       livesLabel (class Label, parent groundBox)
              The lives label.

       scoreLabel (class Label, parent groundBox)
              The score label.

       levelLabel (class Label, parent groundBox)
              The level label.

       gameSpace (class Core, parent groundBox)
              The  game space in which the words fall.  Key presses and Expose events are handled
              through event handlers and not the ordinary translation/action mechanism.

RESOURCES

       In addition to the resources of the  various  widgets,  the  xletters  application  itself
       recognizes some resources.  These are:

       wordFont (class Font, type FontStruct)
              The font in which the falling words are written.

       wordColor (class Foreground, type Pixel)
              The color in which the (untyped part of the) falling words are written.

       typedColor (class HighlightColor, type Pixel)
              The color in which the typed part of the falling words are written.

       deathMode (class DeathMode, type String)
              Either  normal,  death  or  duel  according  as  the  game should be run in normal,
              deathmatch or duel mode (see DEATHMATCH AND DUEL above).

       trainingMode (class TrainingMode, type Boolean)
              Whether the game should be run in training mode (this overrides any  value  of  the
              deathMode resource (see TRAINING MODE above).

FILES

       (If not overriden at compile time)

       /usr/share/dict/words
              The dictionary of words.

       /var/games/xletters/scores
              The high score table.

CONFIGURATION SUGGESTION

       xletters     -wfn    '-bitstream-terminal-medium-r-normal--18-*-*-*-c-*-iso8859-1'    -gbg
       'MidnightBlue' -wc 'PaleGoldenrod' -tc 'Orchid'

BUGS

       None known.  Surely a very temporary situation :-)

       This is one of the ugliest programs I ever wrote.  I would not be  surprized  to  discover
       plenty  of  bugs  in  it.   Version 1.0.0 was ugly enough.  Version 1.1.0 gave a whole new
       meaning to the word ``uglyfication''.

SECURITY

       xletters wants to access a high score table.  If this score table is to be shared  between
       several  users, xletters will probably be made sgid games or some such thing.  Beware that
       it is probably very easy to fool (or even brake to pieces).  I have no doubt that  running
       it  against  a  fake  X  server  (and probably other similar things) can give not-too-hard
       access to whatever permissions it has been given.  Consequently, it should  not  be  given
       any critical permissions.

AUTHORS

       Peter  Horvai (peter.horvai@ens.fr) wrote the deathmatch feature and implemented mmap()ing
       the dictionary file.

       David Madore (david.madore@ens.fr) wrote version 1.0.0, all the X  Windows  parts  of  the
       game, and this man page.

COPYING

       GNU public license.  See the file COPYING for more information.

SEE ALSO

       letters(6), xtetris(6)

                                           05 NOV 1998                                XLETTERS(6)