Using the controller

Introduction

The controller allows for experiment session to be run in a quicker, more streamlined and controlled fashion. It resides within the server and its purpose lies in automatically pairing groups (dyads, triads, etc.) of subjects, firing up games and checking for client connectivity throughout the experiment.

How to use the controller

To use the controller, you need to locate a class residing under edu.harvard.eecs.airg.coloredtrails.controller. This class is named ExperimentController in our current distribution, but may have a different name in previous distributions of Colored Trails. If in doubt, search for a class that contains a main method. As it contains main, the controller class creates its own Java application. This application receives command line arguments and should be fired from the command prompt. These arguments include:

• a configuration file,
• a file containing a game pool (optional),
• the minimum number of games to be run per match (optional), and
• the maximum number of games to be run per match (optional).

To run this application, from the main ct folder, you need to type

Some comments are due:

• The configuration file, the application's only required argument, refers to the name of the configuration file (without extension), residing under gameconfigs.
• The game pool refers to a file containing the settings of pre-recorded games. This is helpful when an experiment spans multiple sessions (e.g., three sessions of 20 people each). If deemed important that all sessions are "indentical," then exposing their subjects to the same games (and not allowing randomness to play a role) is facilitated by using this game pool.
• The minimum number of games refers to how many games every pair of subjects has to play before their session is consider ended.
• Similarly, the maximum number of games refers to how many times each pair of subjects may be allowed to play together throughout the entire session.

Also, keep in mind that you must fire the controller after the server has been started and all clients have connected to it. In a sense, the controller is the final step in starting an experiment.

Remarks

The controller checks for client connectivity throughout an experimental session. However, you need to keep two things in mind:

• In a client disconnects during a game, that game will end (by the server). The controller will not use the disconnected client again, if it wants to re-pair subjects. However, if the number of subjects has now become odd (and pairings are in dyads), the controller will not do anything for the client who will remain unpaired. Keep this in mind when running your experiments.
• The controller implements a handshake mechanism to check for an end game event. After a game ends, the server uses a special message asking the client if it has "finished up." If a client fails to respond, indicating its status, the server tries to ask it again. However, after a number of attempts the client is considered disconnected and the controller is notified automatically.