Game Report

The GameReport executable class is one of the main entry points to using TAG. It is used to run several games and collect data from them for analysis. This page attempts to document all the run-time options available. For the most up-to-date summary, you can also look at the code, and/or by executing:

java -jar GameReport.jar --help

The arguments are all specified by command line tags:

Tag Description Default
games= A list of the games to be played. If there is more than one use a pipe-delimited list, for example games=Uno\|ColtExpress\|Pandemic. All games can be run with games=all, or all games except specific ones with games=all\|-Blackjack\|-Poker, all
player= This specifies one agent that will have exactly one copy present in every game. See section below on Players and Opponents for values. (Optional) None
opponent= The agent(s) used as opponent. Detailed options below in Players and Opponents. random only if player is not specified.
nPlayers= The total number of players in each game. all will run the game for every set of valid player counts. A range such as 3-5 can be specified as well as a single integer. If running multiple games a pipe-delimited list can be used, which must then be the same length as the list of games. all
nGames= The number of games to run for each specified game and player count. 1000
gameParam= A json file detailing the game parameters to use (only if running for just one game). See here for details. Game defaults
listener= The full name of an IGameListener implementation or the location of a json file from which a listener can be instantiated. A pipe-delimited list can be provided to gather many types of statistics from the same set of games. See section below on Listeners and Loggers utilities.GameStatisticsListener
logger= The full name of an IStatisticsLogger implementation that will be used with all of the specified listeners. See section below on Listeners and Loggers. This is ignored if a json file is provided for the listener, as then the file will include the required details. utilities.SummaryLogger
logFile= Only used if logger=FileStatsLogger. This is the log file to which the listener will write data. If several listeners are being used, then this should be a pipe-delimited list with a file for each listener in order. GameReport.txt
statsLog= If specified this file will be used to log statistics generated by the agent’s decision making process (e.g. MCTS node count, tree depth etc.) This is only implemented for MCTS, and stats will only be logged for the single agent in each game specified by the player= option. None

Players and Opponents

The value provided for player= can be any of:

  • one of mcts, rmhc, random, osla to use the default implementations, with default parameter. (Useful for random or osla; not recommended for mcts or rmhc, in which case you should define a json-file instead.
  • the full classname of a class that extends AbstractPlayer and has a no-argument constructor
  • the name of a json-format file that details the parameters of an agent to use (see details). The value provided for opponent= can be any of the above, plus:
  • the name of a directory that contains one or more json-format files, each detailing an agent. The opponents in a game will then be sampled from this set of agents.

If player= and opponent= are specified then exactly one agent in each game will use player (at a random position), and the remaining positions will be filled with agents sampled from opponent (which will all be the same if this only specifies one agent). If only one of the two options is specified, then this will be used for all players in the game.

Listeners and Loggers

Anything that implements the IGameListener interface can be used to listen to events generated by a game (such as at the end of a player’s turn, each time a player makes a decision, or at the end of a game; see the separate documentation on IGameListeners for more details on the technical implementation, including on specifying the configuration via a json file.

Three defaults are provided in the framework:

  • utilities.GameStatisticsListener logs generic information on the game, such as the min/max/median/mean action sizes, the length of a game and so on. None of this is game-specific, and sample output is here. This generates one record per game.
  • utilities.ActionListener logs very basic information on each action taken during a game (turn, round, player, the name of the action). This generates one record per decision taken. This can be used as a template for more game-specific listeners (see games.dominion.DominionListener or games.dicemonastery.DMActionListener for examples).
  • utilities.GameResultListener logs information on the result of each game - the score and ordinal position of each player. This generates one record per game.

Generally it is better to use logger=FilerStatsLogger, as this creates a tab-delimited text file that can easily be fed into more detailed data analysis.