Tux, of Math Command

ReadMe:
"Tux, of Math Command"
An educational math tutorial game starring Tux, the Linux Penguin
-----------------------------------------------------------------


October 29, 2007

For tuxmath-1.6.1

Objective
---------
  In "Tux, of Math Command," you play the part of Commander Tux, as he
  defends his friends from an attack of math equations.

  Comets are crashing towards the friendly penguins in their igloos,
  and you must destroy the comets by solving their equations.



Installation
------------
  For instructions on installing the game on your system,
  please read the "INSTALL.txt" file.


Configuration
-------------
  If all players are using a single account (e.g., a home computer
  that is always logged in, or a school setting in which all students
  have a single username), you may want to do some additional
  configuration---see below under "Configuring multiple users."


Running The Program
-------------------
  Linux/Unix
  ----------
    Simply type the command "tuxmath" at a command prompt (eg, in an xterm).

    Depending on your graphical interface or window manager, you can
    probably also create a clickable icon which will launch the game.
    See your interface's documentation or help screens for details.

  Windows
  -------
    Just double-click the "TuxMath.exe" icon or select "Tuxmath" in the Start
    Menu.  The current installer creates menu items to run tuxmath either in
    Fullscreen mode or within a 640 x 480 window.
    To be prompted for command line options, run tuxmath from the "Run" dialog
    or the "C:> Command Prompt" console. Type "TuxMath.exe" followed by any 
    desired options (see below). If it does not run, make sure the full path
    to the program (e.g. C:\Program Files\TuxMath\TuxMath.exe) is known to 
    Windows, either through Control Panel settings or by changing to the
    directory containing TuxMath.exe before issuing the command.

  MacOS
  -----
    [ UNDER CONSTRUCTION ]  Just double-click the "tuxmath" icon. ???
    To be prompted for command line options (see below), hold the [OPTION] key
    as you double-click the icon.


  Command Line Options
  --------------------
    NOTE: Tuxmath now has many pre-packaged "missions" (lessons), as  well
    as four arcade-style open-ended games of progressive difficulty, so
    there is much less need to change settings.  If desired, editing the
    config file is a much better way to control the behavior of Tuxmath
    than the command-line options, for the most part.  However, many
    options are still supported.

    The following command-line options can be sent to the program:
     --optionfile filename - play game based on settings in the named file (see
                         below for more on tuxmath config files). Tuxmath will
                         look for a valid config file with a matching name in
                         the following locations:
                         	1. current working directory
				2. as an absolute pathname
				3. in the missions directory with tuxmath's 
                                   other data files.
				4. in the user's tuxmath options directory
                                   (e.g. /home/laura/.tuxmath/filename
                                5. in the user's home directory.

     --playthroughlist - Game consists of working through a list of questions
      -r                 generated based on the selected options (or defaults).
                         If a comet strikes a city without being shot down by
                         the player, the question is reinserted into the list
                         in a random location. If the player answers all
questions
                         correctly before the cities are destroyed, he/she wins.
                         If all cities get destroyed, the game ends in defeat.

     --answersfirst   -  to ask questions in format: ? + num2 = num3 instead of 
                         default format: num1 + num2 = ?.

     --answersmiddle  -  to ask questions in format: num1 + ? = num3 instead of
                         default format: num1 + num2 = ?.

     --fullscreen     -  Run the game in full screen, instead of in a window,
      -f                 if possible.

     --windowed       -  Run the game in a 640 x 480 window.
      -w

     --nosound        -  Do not play any sounds or music.
      -s
     --quiet
      -q

     --nobackground   -  Do not display photographic backgrounds in game.
      -b                 (Useful on slower systems.)

     --keypad         -  Display an on-screen numeric keypad.  (Useful
      -k                 for touch screens or in place of a physical keyboard.)

     --operator OP    -  Add an operator to the game (will cause the program
      -o OP              to ignore saved option screen settings).  You can
                         use this switch multiple times to run the game
                         with multiple operators.

                         Valid values for "OP" are:

                           add
                           subtract
                           multiply
                           divide

     --demo           -  Demo mode.  The game will cycle back and forth
      -d                 between the title and the game, and it will
                         auto-play the game.  The only user interaction
                         can be for quitting or pausing.

     --allownegatives    Allows subtraction answers to be less than zero.
      -n                 When selected, the led numbers at the top of the
                         screen will include a fourth digit for the '-' sign.
                         Also, if --keypad is selected, the '-' and '+' may
                         be grayed-out depending if negatives are allowed.


    These command-line options display useful information, but the program
    does not attempt to start up in interactive mode.

     --help           -  Display a short help message, explaining how to
      -h                 play the game.

     --usage          -  Display the available command-line options.
      -u

     --version        -  Display the version of "tuxmath" you're running.
      -v

     --copyright      -  Display copyright information
      -c



Program Navigation
------------------
  Title Screen
  ------------
    Math Command Training Academy: choose this to go to a list of over fifty
    prepared lessons, starting with simple typing of single digit numbers, and
    progressing to multiplication and division involving negatives and 
    "missing number" questions (e.g. "-17 x ? = 119").  The player wins if the
    question list is completed successfully. Successfully completed lessons are
    indicated with a flashing gold star. 

    Play Arcade Game: use this to select from one of four open-ended, "Arcade 
    Style" games, meaning the game play gets faster and faster as long as the
    player can keep up, with the goal being to get the highest score possible.
    The options include:
      Space Cadet - simple addition.
      Scout -       addition and subtraction to ten.
      Ranger -      addition, subtraction, multiplication, and division to ten.
      Ace -         all four operations with operands to 20, including negative
                    numbers and "missing number" type questions.
    If you make one of the top ten scores for the difficulty level, you get to
    enter your name in the TuxMath Hall of Fame!

    Play Custom Game: use this to play a game based on the config file in the 
    player's home directory (see below). At some point, the options will be 
    settable from within the game.

    More Options - this will be developed into the menus to set options not 
    directly related to math questions, such as toggling the music on and off,
    playing fullscreen vs. windowed, using cities vs. igloos, and the like.
    Now it just has the "Demo" mode, as well as credits and project information.

    Use the [UP] and [DOWN] arrow keys to select what you wish to do,
    and then press [ENTER / RETURN / SPACEBAR].  Or, use the mouse to click the
    menu item.

    Pressing [ESCAPE] will quit the program.




How To Play
-----------
  Destroying Comets
  -----------------
    As the comets fall towards your friends, you must solve the equations.

    To destroy it:
    --------------
      First, figure out the answer to the equation.
      For example, "3 x 4 = ?" would be "12"

      Second, type in the answer.  As you type numbers on the keyboard, they
      will appear in the "LED"-style display on Tux's flat-panel monitor.
      If negative answers are enabled, there will be a fourth place in the
      LED display for the minus sign.  The '-' and '+' keys will toggle the
      minus sign on and off, respectively.

      Finally, press [ENTER / RETURN].


    The comet that has the number you entered as its answer will
    be shot down by Tux!

    Note: Sometimes more than one comet will have the same answer.
          In this case, the lowest comet will be destroyed.

    Note: After typing [ENTER / RETURN], the "LED"-style display will
          automatically reset to "000" for you, so you can answer the
          next equation!


  Correcting Your Answer
  ----------------------
    If you made a mistake as you typed in your answer, you can press
    [BACKSPACE / DELETE] and the "LED"-style display at the top center
    of the screen will reset to "000".


  Using the On-Screen Keypad
  --------------------------
    If you launched the program with the "--keypad" (or "-k") option,
    the game screen will also have a numeric keypad on the
    center of the screen.  (It has a similar layout to most keyboard
    number pads and calculators.)

    Using the mouse pointer to click on the on-screen buttons acts
    just like typing numbers on the keyboard.

    This feature could be useful for computers with touchscreens,
    or for players who cannot use a keyboard.


  Losing An Igloo or City
  -----------------------
    The default setting is to play with igloo-dwelling penguins.
    If a comet reaches the igloo, the igloo is partially melted.
    A second hit melts the igloo the rest of the way, and the 
    saddened penguin trudges off the screen.

    If cities are used (by placing "use_igloos = 0" in the config
    file and selecting "Play Custom Game"), game play is the same.
    The first comet strike deactivates the city's shields, and the
    second hit destroys the city. If this seems too scary or violent,
    please use the penguin/igloo theme! 

  Regaining Igloos/Cities
  -----------------------
    When a question is answered correctly, the player earns progress toward
    a bonus comet that allows an igloo or city to be rebuilt.  Progress is
    indicated with a green bar in the upper left corner of the screen. The
    bonus comet is red and moves faster than regular comets.  If the player
    shoots down the bonus comet, a "snowstorm" image appears in place of the
    bonus progress bar, and one of the igloos/cities will be rebuilt after 
    the current wave.

  Ending The Game
  ---------------

    The default mode is now to play through a defined list of questions. This
    mode is used in the "Training Academy" games.  For "Custom" games, it can 
    be selected by setting the config file 'play_through_list' parameter
    to 1 ('yes' or 'true'), or via the "--playthroughlist" command line
argument. 
    The list is generated by TuxMath based on a series of selectable parameters
    (selected math operations, number ranges, etc). By default, the questions
    are asked in a random order.  If answered correctly, they are removed.
    A question that is not answered correctly (allowing the comet to destroy
    its target) will reappear in random order.  If all questions are
successfully
    answered before the igloos or cities have been destroyed, the player wins
    and a "victory" screen is displayed.

    The older arcade-style mode is also supported, in which the game continues
    until you lose all of your igloos or cities.  A GAME OVER screen is then
    displayed. For the "Custom" games, you can select this mode by setting
    'play_through_list' to '0' ('no', 'false', 'off').

    By pressing Esc or clicking on the red circle in the upper right corner, you
    can quit the game.

    Shortcut Keys
    -------------
    The following shortcuts are supported during game play:

      'F10':        switches between windowed and full-screen display mode.
      'P' or 'Tab': pauses the game, if allowed. The included "Math Command
                    Training Academy" lessons allow pausing, while the "Arcade"
                    games do not.
      Up Arrow:     increase speed by 20%, if allowed.
      Down Arrow:   decrease speed by 20%, if allowed.  Speed changes are
allowed
                    when pausing is enabled.
      'Esc':        leave current game and display the menu.

  Advancing Waves
  ---------------



Setting Game Options
--------------------
  The "Options" system remains in need of an overhaul. For now, you can
  play the pre-packaged "Lesson" or "Arcade" games, or edit the options file
  to create a "Custom" game.  At some point the "Custom" settings will be
  modifiable from within TuxMath.

  1. The program reads and writes the settings to disk in a human-readable
  fashion, where they can be modified with a text editor. The file is created
  in the user's home directory within a directory called ".tuxmath" and is 
  simply called "options". As an example, a user "laura" on a Unix/Linux system
  would find this at /home/laura/.tuxmath/options.  The file contains
  extensive comments describing all settings. By editing and saving this file,
  very extensive control over the program is supported, particularly with
  respect to generation of math questions. There really is no need to use
  command-line options any more.

  On a Windows XP or Windows 2000 system, the config file is called
"options.txt"
  and is located at C:\Documents And Settings\USER\Application
Data\TuxMath\options.txt,
  where USER is the login of the current user. Note that 'Application Data' is
  hidden by default by the operating system.

  2. Many command-line options are supported (see above).