Hearts (version 0.0.10)

System Requirements

What's included in this distribution

/README.html This file
/bin Executable programs (including executable JAR files) included with Hearts
/classes Default directory where Hearts will look for compiled players
/data Directory into which players can store data
/doc Documentation
/doc/api Javadoc-generated Hearts API documentation (Browse). Contains documentation for the classes Hearts agents will need to use.
/etc Configuration files that can be used to run Hearts
/lib Classes necessary for running Hearts
/lib/hearts.jar Classes necessary for developing Hearts players
/players Compiled sample players to test against
/src Source code for sample players in the players directory
/tmp Temporary directory used by Hearts for various tasks

Getting Started

Running a Test Game

Unzip the distribution into some directory, which will be referred to as [hearts]. A test game can be executed with the following command: 

    java -jar [hearts]/bin/launcher.jar game.xml
If everything is set up correctly, a stream of log messages (describing a game in progress) should scroll across the screen for a while. When they stop scrolling, the game is over. The game will be played between Random (a player which plays entirely randomly) and the three example players included with this distribution. The log messages are also written to [hearts]/logs/game.log.

The Launcher

The launcher [hearts]/bin/launcher.jar takes one command-line argument -- an XML file which describes what Hearts should do when executed. (The XML file can be a relative path -- in which case it is interpreted relative to [hearts]/etc -- or an absolute path.) In "Running a Test Game," we used game.xml, in the [hearts]/etc directory. Take a look at that file now.

The file describes the settings for a particular game of Hearts. For a full description of the launcher file format, see The Launcher File Format.

Developing Players

The source code for the sample players is available in the [hearts]/src directory, in the example.hearts.ai package. Examining the source code for those players is a good start.

The next stop would probably be the API documentation. Hearts includes a library built on top of the Hearts application core to make it easier to build players. This library is in the inonit.domain.game.card.hearts.ai package. This package should give an idea of what facilities are open to agent designers.

The lower-level interface between Hearts and agents is in the inonit.domain.game.card.hearts package.