Hearts README

The Launcher File Format

A basic understanding of XML is assumed in this description.

The interface between the launcher and the inonit.domain.game.card.hearts package is still being developed actively. As such, this file format is subject to change and little effort will be made to make future formats compatible with this one.

Element: hearts

Attributes: (None)
Contains: (game | tournament), players
The game or tournament element describes a game or tournament to be played. The players element describes the participants in that game or tournament.

Element: game

Attributes: (None)
Contains: rules, log
The rules element describes the rules of the game. The log element describes destinations to which messages will be written.

Element: rules

Currently, only the "Omnibus" (Jack of Diamonds is minus 10 points) version of Hearts is supported. The variant implemented in Hearts requires the JD to be taken for a take-all, as well. There are API methods to retrieve all of this information (e.g., in the Intelligence.Game.Rules class), so it does not need to be hard-coded. Additional variants are built into Hearts, but the launcher does not currently interface with them.
Attributes: scoreLimit handLimit
Name Type Required? Description
scoreLimit integer default (100) When one of the players exceeds the indicated score, a game ends.
handLimit integer default (24) Even if no player has reached the score limit, a game is over after the given number of hands.
Contains: EMPTY

Element: tournament

Attributes: games
Name Type Required? Description
games integer REQUIRED Number of games to be played in the tournament
Contains: game, log
The game element acts as a description for each game in the tournament. The log element describes destinations to which log messages should be written.

Element: players

Attributes: handTimeLimit
Name Type Required? Description
handTimeLimit integer REQUIRED Number of seconds to be allowed per player per hand.
Contains: (object | jar | process | directory | random)*
Child elements are used to describe each agent participating in the competition. In a tournament, an implied random element named "Random" is always inserted in addition to elements listed.

Element: object

A Java class which implements the Intelligence interface.
Attributes: name class
Name Type Required? Description
name string REQUIRED The name which Hearts will use to identify the player (in log messages).
class class REQUIRED The fully-qualified Java class name of the implementation.
Contains: classpath?
If a classpath is specified, it is searched for player classes. Otherwise, the player must be in the classes directory under the Hearts install.

Element: classpath

Attributes: (None)
Contains: EMPTY

Element: directory

Attributes: path
Name Type Required? Description
path file REQUIRED The path to the directory. Relative paths are interpreted relative to the Hearts installation root.
Contains: EMPTY

Element: jar

Attributes: path
Name Type Required? Description
path file REQUIRED The path to the JAR file. Relative paths are interpreted relative to the Hearts installation root.
Contains: EMPTY

Element: jar

A JAR file containing classes which contain an Intelligence implementation. JAR files must be packaged with the class name prepended to the ".jar" suffix (as the examples in the players directory do).
Attributes: name path
Name Type Required? Description
name string REQUIRED The name which Hearts will use to identify the player (in log messages).
path file REQUIRED The path to the JAR file. Relative paths will be interpreted relative to the players directory under the Hearts install.
Contains: EMPTY

Element: process

A player which will be launched from a JAR file in a separate native process (i.e., a separate Java virtual machine). Launching a player in a subprocess involves substantial overhead; the option is provided for "fairness" reasons, since otherwise players cannot be fully isolated from one another (although this may be possible in the future). Problems with CPU contention and memory contention are difficult to solve, but the performance reduction subprocesses entail may cause this option to be removed in future versions.
Attributes: name jar
Name Type Required? Description
name string REQUIRED The name which Hearts will use to identify the player (in log messages).
jar string REQUIRED The path to the JAR file. Relative paths will be interpreted relative to the players directory under the Hearts install.
Contains: EMPTY

Element: directory

Causes a set of players to be added to the competition. The set is the set of JAR files in the given directory.
Attributes: type path
Name Type Required? Description
type string jar | process Indicates whether to instantiate each JAR in its own subprocess or to instantiate them within the parent process.
path file REQUIRED The path to the directory containing the JAR files. Relative paths are interpreted relative to the Hearts installation root directory.
Contains: EMPTY

Element: random

A player which plays randomly. An implied random named "Random" is added to all tournaments.
Attributes: name
Name Type Required? Description
name string REQUIRED The name which Hearts will use to identify the player (in log messages).
Contains: EMPTY

Element: log

Attributes: (None)
Contains: console?, file*
A console element indicates that log messages should be written to the console. A file element indicates that they should be written to a file. If neither is indicated, no log will be written. Multiple elements may be listed (i.e., logging may go to the console and a file).

Element: console

Attributes: (None)
Contains: EMPTY

Element: file

Attributes: path
Name Type Required? Description
path file REQUIRED Path name of file to which log output will be written. Relative paths are interpreted relative to the logs subdirectory of the Hearts install.
Contains: EMPTY