Page Comparison

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:

...

process of creating a human or computer agent in Colored Trails is very simple. For human agents, one can directly use the graphical user interface (GUI) classes available in CT. Unless customization is needed, the researcher is freed of having to code separate agents. But even when the experiment requires custom UI elements, adding them to the existing GUI class structure is easy (see below Customizing the GUI). For computer agents, one needs to implement a class handling the specific actions or moves required by that agent. CT provides a message-handling infrastructure for the low-level message-passing, reordering and guaranteed delivery. The developer only needs to specify, in game terms (e.g., board movements, chipset exchanges) what the agent is supposed to do, i.e., implement the agent's static or adaptive strategy.

Running a GUI agent

To run a GUI agent, without customization, just type from your main CT directory:

Customizing the GUI

Sometimes it is required for the GUI to be customized, to provide functionality that is not included in the standard CT distribution. This is accomplished by tweaking the following:

• In class ctgui.original.BoardWindow there is a responserequired method that handles special messages sent by the server. The command argument distinguishes the different types of messages. In the body of the method, the developer can implement custom functionality in BoardWindow or other UI classes (like TaskBar, BoardPanel, etc.).
• In the OnMessage method of ColoredTrailsClientImpl, you can call responserequired. The OnMessage method is for handling messages received by the client. If you want a particular UI operation after handling a message of a certain type, just add an appropriate call to responserequired at the end of reception.
• On the server side, you can use class ClientCommands to send messages. Making a call to sentChangeMessage sends a message of that type to the client. Just add a method in ClientCommands that calls sentChangeMessage.
• Finally, from the configuration file, call the method you created to communicate a message with your custom-made parameters to the client.

Handling messages from the client to the server follows a similar path.

Building a computer agent

The easiest way to build a computer agent is to inherit from class SimplePlayer, under edu.harvard.eecs.airg.coloredtrails.agent. Then you overload the following methods:

• phaseAdvanced to handle what the client needs to do when a phase begins (e.g., calculate the best path and move along it).
• onReceipt to handle discourse messages, like responding to a received offer (optional).

You can also add your own methods. Under edu.harvard.eecs.airg.coloredtrails.agent you can find many examples of proposer and responder types of agents that will help you understand how to build computer agents in CT.