TRIPLE TRIAD ASSISTANT
Version 2.0-beta1 (31 January 2013)

Ryan Vogt
vogt@cs.ualberta.ca

Contents:
1. Copyright Notice
2. About Triple Triad Assistant
3. Running Triple Triad Assistant
4. Compiling Triple Triad Assistant
5. Audio Input and Output
6. Processing Card Dumps

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

1. Copyright Notice

Copyright (c) 2010, 2011, 2012, 2013 Ryan Vogt <vogt@cs.ualberta.ca>

Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

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

2. About Triple Triad Assistant

Triple Triad Assistant is designed to help you win against a computer-
controlled opponent in Triple Triad, a mini-game in Final Fantasy VIII.  Triple
Triad Assistant asks you to input the cards that both you and the computer
opponent have in your hands.  Then, it will ask you to input all of the moves
that the computer-controlled opponent makes.  An AI will determine the best
moves for you to make when it is your turn.

Currently, Triple Triad Assistant only supports the most basic rule set played
at the beginning of Final Fantasy VIII (open hands, no combos, no elemental
tiles, etc.).  However, Triple Triad Assistant could be extended to support
additional Triple Triad rule sets.

If someone were to determine the exact implementation of the Same, Plus, and
Elemental rules used in Final Fantasy VIII, I would be happy to add support for
these rules to the Triple Triad Assistant.  While we do not have all the
details, we do know that the implementations of these rules in FF8 is very
buggy (cards that are not supposed to be flipped can get flipped, and cards
that are supposed to be flipped can be left unflipped).

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

3. Running Triple Triad Assistant

If you have the precompiled version of Triple Triad Assistant, all you need to
do to run the program is:

% java -jar triadHelper.jar

You can modify triadHelper.conf to adjust the default settings and starting
hand.  Note that with the precompiled version of Triple Triad Assistant, you
are limited to using the console version of the program (no audio input nor
output), and the programs for analyzing card hands (see Section 6) are not
included.

If you compiled Triple Triad Assistant by yourself (see Section 4), execute
either of the following commands to run it:

% bin/triadHelper
% bin/audioHelper

Note that running audioHelper requires that the program was built with audio
support (see Section 5).  The audio helper can take up to two command line
parameters: -careful tells the program to confirm the most important audio
input that it hears, and -rude tells the program to be insulting to you during
play (essentially, a donation incentive for marathons).

When asked to input card values, they are input in the order of: top value,
right value, bottom value, left value.  The values are to be space-separated or
spoken back-to-back; type or say "10" for a card that displays "A" in-game.

The nine spaces into which cards can be played are referred to by the numbers
one through nine, with one being the top-left, two being the top-centre, etc.
That is, the nine spaces are labelled as such:

   1 2 3
   4 5 6
   7 8 9

The evaluation function value at the alpha-beta leaf node is scored primarily
on the number of cards owned by the leaf player, with ties broken by the sum of
the edges of the unplayed card.

Note that the opponent in Final Fantasy VIII does not always play optimally.
So, while your evaluation may improve as the game progresses, it will not get
worse.

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

4. Compiling Triple Triad Assistant

Triple Triad Assistant is written in Java 6.  To compile it, run:

% cd src/
% ant noaudio

By default, the compilation scripts assume that you want audio input/output
support (i.e., voice recognition and voice synthesis) included in the program.
However, support for audio input and output is limited.  For more details, see
Section 5.  If you want to compile the program with audio support, run:

% cd src/
% ant

If you wish to compile the accompanying Javadoc documentation, e.g., if you are
a developer interested in extending Triple Triad Assistant, run:

% ant javadoc

The Javadoc documentation will be located in the javadoc/ directory.

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

5. Audio Input and Output

In order to have audio input and output (i.e., voice recognition and speech
synthesis), your system needs two components installed:

  - A program called "say" that takes a single command-line argument
    representing the English sentence that should be spoken; and,
  - The Sphinx-4 voice recognition library.

Currently, audio input and output is limited to recent versions of OS X, which
come with the requisite "say" program preinstalled (interested developers could
consider subclassing src/audio/OutputMethod.java to add support for new output
methods).

Because the Sphinx-4 library cannot be shipped with the Triple Triad Assistant
due to licensing reasons, you will need to perform the following steps to get
Sphinx-4 set up to work with the Triple Triad Assistant.

First, check out a recent version of the Sphinx-4 source code:

% svn co https://cmusphinx.svn.sourceforge.net/svnroot/cmusphinx/trunk/sphinx4

Next, set up the JSAPI interfaces that come with Sphinx-4:

% cd sphinx4/lib
% ./jsapi.sh

At this point, scroll to the bottom of the agreement and accept it.  If you see
an error message from sed at this point, it can be ignored; that is a known
issue on OS X that does not cause any harm.

Next, you need to set your environmental variables and run the build:

% cd ..
% export JAVA_HOME=`/usr/libexec/java_home -v1.6`
% export ANT_HOME=/usr/share/ant/
% ant

When the build is complete, you simply need to copy two files:

  - lib/sphinx4.jar
  - lib/WSJ_8gau_13dCep_16k_40mel_130Hz_6800Hz.jar

into the audio/ directory in the Triple Triad Assistant project (you should
already see a few files in that directory, including tripleTriad.gram).

The tripleTriad.gram file contains the complete grammar of audio commands that
you can speak to the program.  The default configuration (e.g., which
microphone to use) is kept in etc/triadHelper.conf.

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

6. Processing Card Dumps

A card dump is a set of hands, listed one per line, representing the hands
played by an opponent in Final Fantasy 8 over a large number of trial games
against them.  Each hand is represented by five numbers, where each number
indicates an index into Final Fantasy 8's in-memory table of all the cards in
the game.  For example, the single line

103 20 15 44 46

represents a hand consisting of a Quistis, Jelleye, Belhelmel, Iron Giant, and
Chimera card.  By collect a large number of hands that a single opponent plays
(see, e.g., the dumpHands.lua script in the scripts/ directory), you can
compute useful statistical information about that opponent.

To read in from a file with a large number of hands saved in it, one per line,
run:

% ./processDump < CardDump.txt
