		  Ataxx: Users' Guide and Reference
          
              Author: Loring Scott Hoag
                    Version-1.00

------------------------------------------------------------------------

Table of Contents
Use your text editor's/viewer's find function to jump to the correct section.

I. Overview

II. Starting the Program

III. How to Play
III.A. Game Objective
III.A.1. Scoring
III.A.2. End-Game Conditions
III.B. Game Board
III.B.1. Empty Spaces
III.B.2. Occupied Spaces
III.B.3. Blocks
III.C. Turn Order and Actions
III.C.1. Valid Moves
III.C.1.a. Extend
III.C.1.b. Jump
III.C.2. Passing
III.D. Converting Opponent's Pieces

IV. Playing Without the GUI
IV.A. Commands
IV.A.1. Anytime Commands
IV.A.1.a. clear
IV.A.1.b. quit
IV.A.1.c. help
IV.A.1.d. dump
IV.A.1.e. load
IV.A.2. Pre-Game Commands
IV.A.2.a. start
IV.A.2.b. color
IV.A.2.c. blocks
IV.A.2.d. auto
IV.A.2.e. seed
IV.A.2.f. host
IV.A.2.g. join
IV.A.3. In-Game Commands
IV.A.4. Post-Game Commands
IV.A.5. Movement Commands

V. Playing With the GUI (BETA)
V.A. Menu Buttons
V.A.1. Start
V.A.2. Pass
V.A.3. Host/Host Game
V.A.4. Join/Join Game
V.A.5. Help
V.A.6. AI/Seed AI
V.A.7. Load/Load File
V.A.8. Reset/Clear
V.A.9. Set Moves/Set Blocks
V.A.10. Auto/Auto-Play
V.A.11. P1 = Red/P1 = Blue
V.A.12. Quit
V.B. Character Buttons
V.C. Making Moves


------------------------------------------------------------------------
------------------------------------------------------------------------

I. Overview

    Ready, set, ATTAX!! The game ATTAX!! is a two-player competitive test of strategy and skill. This manual will teach players how to use the ATTAX! program and how to play the game.
    
------------------------------------------------------------------------
------------------------------------------------------------------------

II. Starting the Program

	Windows: 
	Double-click the ataxx.bat file.

	Others:
	Enter the following on the command line:
    java -jar attax.jar [ --display ]
    
    Running the attax program with the --display option enabled will launch the optional graphical user interface. (GUI) For more information, please see section V.

------------------------------------------------------------------------
------------------------------------------------------------------------

III. How to Play

    ATTAX! is a game that is easy to learn, yet difficult to not get your butt kicked by people that actually know what they're doing. If you want to stand a chance against those math-geniuses that plot out chess patterns in their heads, you should probably start by learning the rules of the game.

------------------------------------------------------------------------

III.A. Game Objective

    Players take turns adding pieces of their color to the game board while simultaneously trying to convert their opponent's pieces to thier own color. The winner is the player with the most pieces of their own color on the board when both players have run out of legal moves.

------------------------------------------------------------------------

III.A.1. Scoring

    Players score one point for every piece of their own color on the board. This includes pieces that a player has placed on the board as well as pieces that have been converted from an opponent's color. The score tally is updated after every move.
    
------------------------------------------------------------------------

III.A.2. End-Game Conditions

    The game is over when both players have run out of legal moves to make. Play continues so long as at least one player has a legal move.
    
    In order to avoid atari - A rare condition where two players enter into a state of infinitely jumping each others' pieces - the game will also end if 45 jumps have been made in a row with no extensions in between.
    
------------------------------------------------------------------------

III.B. Game Board

    The game board takes place on a 7x7 square grid. Each segment of the grid can be either empty or occupied with playing pieces or blocks. Each of these cases is described below.
    
------------------------------------------------------------------------

III.B.1. Empty Spaces

    An empty space is an unoccupied place on the game board. An empty space becomes an occupied space when a player places a piece in it as a result of a valid move.

------------------------------------------------------------------------
    
III.B.2. Occupied Spaces

    An occupied space contains either a red or blue playing piece. Once a space is occupied, it remains occupied until the end of the game. The playing piece that occupies the space can only be removed if the player of matching color "jumps" the piece to a new valid location. The color of the piece may change many times over the course of the game.
    
------------------------------------------------------------------------

III.B.3. Blocks

    Spaces containing blocks are considered to be occupied by a nuetral piece at all times. No playing pieces can be placed over a block, nor can a block be converted into a playing piece.
    
------------------------------------------------------------------------
    
III.C. Turn Order and Actions

    The red player always goes first. Then the game alternates between the blue and red players until both are out of legal moves.

------------------------------------------------------------------------

III.C.1. Valid Moves

    A valid move consists of either an extension of a player's piece already on the table or a jump from one position to a position further away.

------------------------------------------------------------------------

III.C.1.a. Extend

    A player may extend a piece of thier own color to any adjacent empty space horizontally, vertically, or diagonally. Spaces more than one grid space away in one of these directions are not considered adjacent. Extending a piece places a new piece of the player's color in the space extended to. The piece that was extended remains unchanged.

------------------------------------------------------------------------

III.C.1.b. Jump

    A player may jump a piece of their own color to an empty space exactly two grid spaces away horizontally, vertically, or diagonally. Jumping moves the piece from its original position to the new position. Thus, the space that the piece originally occupied becomes an empty space.
    
------------------------------------------------------------------------

III.C.2. Passing

    If a player has no valid moves on the table, that player may pass on their turn. A player may not voluntarily pass when legal moves exist.

------------------------------------------------------------------------
    
III.D. Converting Opponent's Pieces

    After extending or jumping, any pieces of the opposing player's color that are touching the extended-to/jumped piece convert to the color of the player. For example, the diagramw below show the outcome of a red player either moving or jumping from the initial starting position in the center of the board.

    
            Extend <<=========== Before =========>> Jump
            
      ===                 ===                 ===
        b b - - - - -       b b - - - - -       b b - - - - -
        b r - - - - -       b b - - - - -       b b - - - - -
        - - r r b - -       - - - b b - -       - - - b b - -
        - - r r b - -       - - b r b - -       - - b - b - -
        - - b b b - -       - - b b b - -       - - r r r - -
        - - b - b - -       - - b - b - -       - - r r r - -
        - - r r b - -       - - r r b - -       - - r r r - -
      ===                 ===                 ===
      
      (For more information on the board layout, please see the dump command.)

------------------------------------------------------------------------
------------------------------------------------------------------------

IV. Playing Without the GUI

    Without the GUI, commands and moves are entered through the command terminal. These commands are described below.
    
------------------------------------------------------------------------

IV.A. Commands

    Commands are used to give the game instructions. Some commands are only valid before the game begins or while the game is in play.

------------------------------------------------------------------------

IV.A.1. Anytime Commands

    These commands can be used at any time during the execution of the program.
    
------------------------------------------------------------------------

IV.A.1.a. clear

    clear

    Abandons the current game if one is in progress, resets the game board, and sets the Player to the human user of the program. The user may then set up the game board and other pre-game variables.
    
------------------------------------------------------------------------

IV.A.1.b. quit

    quit

    Abandons the current game if one is in progress and exits the program immediatly there-after.
    
------------------------------------------------------------------------

IV.A.1.c. help

    help

    Prints out a list of basic commands. Only the most important commands are mentioned by the help command.
    
------------------------------------------------------------------------

IV.A.1.d. dump

    dump

    The dump command prints out the game board in the following format:
    
            ===
              r - - - - - b                  KEY
              - - - - - - -             ---------------
              - - X - X - -             r : Red Piece
              - - - - - - -             b : Blue Piece
              - - X - X - -             X : Block
              - - - - - - -             - : Empty Space
              b - - - - - r             
            ===

------------------------------------------------------------------------

IV.A.1.e. load

    load FILENAME
    
    This substitutes the contents of the file FILENAME for the load command. The commands in the file must all be valid commands to be recognized.

------------------------------------------------------------------------

IV.A.2. Pre-Game Commands

    These commands are only valid before a game has officially begun.

------------------------------------------------------------------------

IV.A.2.a. start

    start
    
    This officially begins the game with the players as their currently set colors and the current configuration of playing pieces and blocks on the table. The red player goes first unless the last piece placed in set-up mode was red in which case the blue player goes first. If the end game conditions are already satisfied when the game begins, the game immediatly ends and declares the winner.

------------------------------------------------------------------------

IV.A.2.b. color

    color C
    
    Sets the Player's color to the color denoted by C and the Opponent to the opposite. I.E: "color red" would set the Player to red and the Opponent to blue.
    
------------------------------------------------------------------------

IV.A.2.c. blocks

    blocks PATTERN
    
    Sets up block patterns for the game board according to the following rules:

           Fig  1.             Fig  2.             Fig  3.
           
        - d e 4 - - -       - d e 4 e d -       - - - - - - -
        a g f 5 - - -       a g f 5 f g a       - X - - - X -
        b c h 6 - - -       b c h 6 h c b       - - X - X - -
        1 2 3 - - - -       1 2 3 - 3 2 1       - - X - X - -
        - - - - - - -       b c h 6 h c b       - - X - X - -
        - - - - - - -       a g f 5 f g a       - X - - - X -
        - - - - - - -       - d e 4 e d -       - - - - - - -

    Figure 1. shows the basic block pattern letters. These pattern symbols are symmetric accross the board according to figure 2. I.E., the command "blocks 3gh" will create the board configuration seen in figure 3.
    
------------------------------------------------------------------------

IV.A.2.d. auto

    auto
    
    This lets an AI bot take over the role of the Player character for the next game. Control of the Player character returns to the user when the clear command is used.

------------------------------------------------------------------------

IV.A.2.e. seed

    seed N
    
    The AI bot uses random numbers to help it determine its moves. Useing the seed command with an integer seeds the random number generator.
    
------------------------------------------------------------------------

IV.A.2.f. host

    host ID
    
    This places the game in host mode with the identifier ID. The game will wait for a client to connect before allowing further input. Once a client connects, control of the game setup is in control of the user whose program is hosting the game.

------------------------------------------------------------------------
IV.A.2.g. join

    join ID@HOSTNAME
    
    Attempts to connect to a game being hosted by a program with identifier ID at the address HOSTNAME. If the connection is successful, the game will run in client mode. All game setup is controlled by the host.

------------------------------------------------------------------------
IV.A.3. In-Game Commands

    Other than movement commands, there are only a few valid actions that can be invoked while a game is in session. The list is below. Please see their specific sections for more information on each one individually.
    
    1. Movement coordinates.
    2. clear command
    3. quit command
    4. dump command
    5. load command
    6. help

------------------------------------------------------------------------

IV.A.4. Post-Game Commands

    Below are the list of commands that can be executed after a game has ended and before a new game enters the setup phase. Please see their specific sections for more information on each one individually.
    
    1. clear command
    2. quit command
    3. dump command
    4. load command
    5. help

------------------------------------------------------------------------

IV.A.5. Movement Commands

    To enter a move, the player simply enters the coordinates (Row letter first, followed by collumn number) of the position that they want to extend or jump from and the destination coordinate seperated by a hyphen. Passing is performed by entering a single hyphen. The board below shows the official game coordinate system.
    
            7 - - - - - - -
            6 - - - - - - -
            5 - - - - - - -
            4 - - - - - - -
            3 - - - - - - -
            2 - - - - - - -
            1 - - - - - - -            
              a b c d e f g

    For example, the command "a7-b6" would represent an extension from a piece in 7a to 6b. The command "a1-c1" would represent a jump from a1 to c1. The command "-" would represent a pass.
    
------------------------------------------------------------------------
------------------------------------------------------------------------
    
V. Playing With the GUI (BETA)

    java ataxx --display

    Use the GUI! All the cool kids are using it and you don't want to be left out, do you? The red player's information and character pictures are displayed on the left, while the blue players' are displayed on the right.
    
    NOTE: The GUI is currently in beta form and is thus still being tweaked for optimal performance.

------------------------------------------------------------------------

V.A. Menu Buttons

    Commands are entered through the menu buttons. Simply click a button to activate it. See the previous sections for more detailed descriptions of what the actions do.
    
    NOTE: Since some of the buttons have various messages on them at different times and since the text chages often during the beta, multiple names are listed for some of the buttons below. 

------------------------------------------------------------------------

V.A.1. Start

    Equivalent to "start".

    Starts the game when applicable.

------------------------------------------------------------------------

V.A.2. Pass

    Equivalent to "-".
    
    Attempts to pass.
    
------------------------------------------------------------------------
    
V.A.3. Host/Host Game

    Equivalent to "host ID".
    
    Creates a pop-up window with a text field. Enter an ID into the text field to host a remote game. The window will be frozen until connection is made or canceled.
    
    NOTE: Future updates will contain a cancel connection button to quit out of the client-searching section.

------------------------------------------------------------------------

V.A.4. Join/Join Game

    Equivalent to "join ID@ADDRESS".
    
    Creates a pop-up window with a text field. Enter the full ID@ADDRESS of the game you want to join into the text field to attempt to join a remote game. The window will be frozen until connection is made or canceled.
    
    NOTE: Future updates will contain a cancel connection button to quit out of the host-searching section.
    
------------------------------------------------------------------------
    
V.A.5. Help
    
    Creates a pop-up window with basic information about how to make a move.

------------------------------------------------------------------------

V.A.6. AI/Seed AI

    Equivalent to "stop".
    
    Opens a pop-up box with a text field. Enter a value that is parsable as type long into the field and click OK to seed the AI with that value.
    
------------------------------------------------------------------------

V.A.7. Load/Load File

    Equivalent to "load filename".
    
    Opens a pop-up box with a text field. Enter a filename and click OK to load that particular file's commands.

------------------------------------------------------------------------

V.A.8. Reset/Clear

    Equivalent to "clear".
    
    Clears the board and puts the game in setup state.

------------------------------------------------------------------------

V.A.9. Set Moves/Set Blocks

    Toggles the setup mode from setting initial moves to setting blocks. Click the board buttons to set the blocks/moves at those positions.

------------------------------------------------------------------------

V.A.10. Auto/Auto-Play

    Equivalent to "auto".
    
    Let's the AI play as the user's character.

------------------------------------------------------------------------

V.A.11. P1 = Red/P1 = Blue

    Equivalent to "color c".
    
    Swaps the player's and opponent's colors.

------------------------------------------------------------------------

V.A.12. Quit

    Equivalent to "quit".
    
    Quits the game.
    
------------------------------------------------------------------------

V.B. Character Buttons

    These are displayed above each players' score box. Clicking these changes the characters that are selected for the respective player.
    
    NOTE: Character selection is rather limited in the BETA.

------------------------------------------------------------------------

V.C. Making Moves

    To make a move, click a piece of your own color. Then, click a space to move to. If it is your turn and a valid move, you will make the move. Otherwise, the referee might get mad at you!
    
------------------------------------------------------------------------
