=====================================
= GENERAL GAME PLAYING BASE PACKAGE =
=====================================
 
Application Suite for the General Game Playing Project;
 - A GUI-based GameKiosk        (for playing human-vs-computer matches)
 - A GUI-based GamePlayer       (for running computer players)
 - A GUI-based GameServer       (for hosting matches)
 - A GUI-based GDLValidator     (for validating game rulesheets)
 
Support code for the above.

                            == QUICK START GUIDE ===

    Getting started is as simple as writing a new player that inherits from the
StateMachineGamer class. StateMachineGamer is based on the state machine view
of general game playing, in which playing a game is represented as proceeding
through a state machine. The underlying state machine, which you can access via
getStateMachine() when inheriting from StateMachineGamer, provides methods that
you can use to investigate the game being player:

	* Each game has a starting state.
		getInitialState() is the starting state.
	
	* Each state has legal moves for every player.
		getLegalMoves(state, role) are the legal moves for <role> in <state>.
	
	* Some states are terminal, and in those states "goal" values are defined
      for every player, indicating whether they won or lost.
      	isTerminal(state) indicates whether a state is terminal.
      	getGoal(state, role) is the goal value for <role> in <state>.
      	
    * Given a legal move for each player, you can transition from one state to
      the next state, after the players make their respective moves.
      	getNextState(state, moves) is the result of making <moves> at <state>.

    A simple Prover-based state machine implementation is included in GGP Base,
so you don't need to worry about the details of converting a game description
into a state machine. To write a gamer based on StateMachineGamer, derive your
class from players.gamer.statemachine.StateMachineGamer. Applications like the
PlayerPanel should automatically recognize your new class and it should appear
in their lists of available players right away.

    For examples of simple players, see src/player/gamer/statemachine/reflex,
where two extremely simple "reflex-based" players are included: LegalGamer and
RandomGamer. LegalGamer always chooses the first legal move available, and the
RandomGamer always chooses a random legal move.

                              === MISC NOTES ===
 
* This is the 4/1/2010 release of GGP code for CS227B, compiled and maintained
  by Sam Schreiber with help and support from Ethan Dreyfuss, Eric Schkufza,
  Keith Schwarz, Steven Bills, and Mike Mintz.
 
* This project is licensed under the New BSD License. Licensing information for
  the project can be found in the licenses/LICENSE file. Licensing information
  for the included external libraries can be found in the licenses/ directory.

                              === BUILD NOTES ===

You will need to have Maven installed.  It can be found at:

http://maven.apache.org/index.html

If you are running Linux, you may choose to install a package.

Next we need to install the jythonconsole into your local Maven repository.

1) Download the jythonconsole from https://code.google.com/p/jythonconsole/downloads/list

2) Unfortunately, the zip file entries have a directory specified with the version number "jythonconsole-0.0.7", so we need
to unpack it and rezip it from that directory, so that the directory entry is no longer in the archive.

3) We then install the newly created archive into our local repo with the following command:

mvn install:install-file -Dfile=jythonconsole-0.0.7.zip -DgroupId=com.google.code -DartifactId=jythonconsole -Dversion=0.0.7 -Dpackaging=zip

At this point you can perform the normal maven build command to build the artifacts and install them in your local repo.

mvn clean install

To generate an aggregate Javadoc for all the modules, you can use either of the following commands:

mvn javadoc:aggregate

or to build and generate the javadoc:

mvn clean install javadoc:aggregate

The index page of your javadoc will be ./ggp/target/site/apidocs/index.html


                       === MAVEN COMMANDS FOR APPS ===

Invoking the different applications:

Server:
cd apps
mvn -X exec:java -Pserver

Clojure Console:
cd apps
mvn -X exec:java -Pclojure-console

Python Console:
cd apps
mvn -X exec:java -Ppython-console

Kiosk:
cd kiosk
mvn -X exec:java

                       === MAVEN ARCHETYPE FOR RUNNING GAMERS ===

This new approach allows separating your new Gamers and their code from the rest of the GGP project and libraries.  This
will reduce build time as only your classes are being compiled.  Since the GGP modules are bundled up as separate .jars,
only those that are needed, have to be deployed.

mvn archetype:generate -DarchetypeGroupId=org.ggp.base -DarchetypeArtifactId=ggp-player-archetype -DarchetypeVersion=1.0-SNAPSHOT  -DgroupId=com.yourcompany.ggp -DartifactId=ggp-clojure -Dversion=1.0-SNAPSHOT

Once you have generated your new project, you can add code to your gamer project and run it, even passing parameters,
as described below.  These are the same as available from the DOS batch file and Unix shell script.

mvn clean install exec:java -Dexec.args="-p 9149"

You can even build a zip archive with all the dependent jars using the command:

mvn clean install package

Scripts are also included to run the gamer player.  The player and the shell scripts can optionally take two parameters
-p (or --port) for port and -n for the name of the game to be played.  If only one game is defined in the gamerMap in
the spring configuration file, then the name of the game can be omitted and it will default to that game.  You can also
ask for "--help" to see these options.  For example, to run the gamer on port 9149, you would type:

run-gamer -p 9149


                           === HISTORY ===

This repository was cloned from Sam Schreiber project at https://code.google.com/p/ggp-base/

The licenses were copied from that site into the LICENSE file.

Since the source files locations were radically changed, the Eclipse project files were removed.  Maven has instructions
for using Eclipse with an existing Maven project: http://maven.apache.org/guides/mini/guide-ide-eclipse.html