Multistage Developer's Guide

Information Objects compose the bulk of the communication between the server and the clients. The Information object is wrapped around a hashtable; it is filled by using the add%Type%Info method. All of these methods are outlined in the Information object API documentation, but follow the form:

add%Type%Info(String key, Object ) where %Type% is the store type
get%Type%Info(String key) where %Type% is the return type

An important thing to note is that although a Type is passed in, when the information is stored in the hashtable, it does not retain its type information. Thus, it is crucial to specify compatible types when storing and retrieving information.

Get Methods:

• getInfo
• getBooleanInfo
• getFloatInfo
• getIntInfo
• getStringInfo

Corresponding Set Methods:

• setInfo
• setBooleanInfo
• setFloatInfo
• setIntInfo
• setStringInfo

The Information object is passed to the client side through a number of methods. Specifically, the methods are:

For Synchronous:
askAllPlayers(Information[]) - sends Information[i] to player number i.
askPlayer(Information, int partnerNum) - sends a single Information object to player number parterNum.

For Asynchronous:
Asynchronous has its own section, but the method is called:
askAsynchronous(Information []) - sends Information[i] to player number i as indexed by ServerControl.
Asynchronous games can have a time limit, which is discussed in the Asynchronous section.

These objects are inserted into the GUI of the client (discussed later). Once they are added to the client side, they are accessed through methods on the server side of the form:
addColumnData( int partnerNum, String column, String data [, Color color])
Note: the color parameter is optional.

This will set the header "column" with the value of "data." If a column does not already exist by that name, a new column will be created. This means that in order for data to appear in continuous columns/rows, the headers need to be identical (case sensitive). A common request is to start out with a blank row before a round has occurred. To do this, simply write to the specified columns with an empty String "". The first round will overwrite this and continue correctly.

It is often desirable to send messages to the players to make announcements or give reminders. To do this, use one of the following methods:

• displayMessag - sends a message immediately to a single player
• displayUniversalMessage - sends a message immediately to all players
• displayMessagePostRound - stores the message to be sent after the current round is over for all other ServerControl objects.

Each of these has several method signatures, which correspond to various situations. The decision to use a particular signature of these methods is beyond the scope of this document. Please consult the API Documentation for ServerControl.

Many games require players to be able to communicate amongst themselves to cooperate or compete. Multistage has a built in customizable chat system. The methods used to control the chatting system are:

• activateGroupChatRouting: allows everyone to talk to everyone else
• clearChatRoutingTable: removes all chat routes
• insertChatRoute(int sender, int receiver): allows sender to talk to receiver but does not necessarily allow receiver to talk to sender.
• insertChatRoutingTable( Vector[] ): given an array of Vectors, this will allow player #i to talk to the players corresponding to integers in Vector[i].

Many games need to question subjects to obtain enough information for the experiment to be complete. There are 28 method signatures to choose from for this purpose. For intimate details on each of these wonderful methods, consult the friendly API Documentation. Note that all of these questions automatically record data to the output file (unless testing for correctness). Here is short rundown of the signatures to choose from:

• questionSubject: sends a Vector of questions to a single subject
• questionSubjects: sends a Vector of questions to all subjects
• questionSubjectsPostMatch: stores a Vector of questions to be answered after the current match
• questionSubjectsPostRound: stores a Vector of questions to be answered after the current round

Each method has its own specification, but some features to notice are:

• Timelimit: a timelimit can be set
• Blocking: This specifies if the round/match can continue while the question is being asked. If blocking is set to true, then a game will pause while the question is being asked. If blocking is false, the game will continue.
• Customized Button/Label texts: The labels and buttons are fully customizable with the proper method calls.

The question Vectors are constructed from Question objects. Some question types to investigate are (found in multistage.shared.data):

• SliderQuestion
• TextQuestion
• EssayQuestion
• DegreeQuestion
• ChoiceQuestion

Two methods are used to assign payoffs to players.

1. addPayoff( int partnerNum, float payoff) - gives a single payoff to a player
2. addPayoffs( float[] payoffs) - gives each member of a float array to each player according to partnerNum.

Setting the Number of Rounds (and other configuration file tricks):
This achieved in the configuration file described earlier. The parameters that are important for administration of the experiment are:

        NumOfMatches = number of matches that the experiment will run
        ## Match specific parameters start with Match.%roundNum% ##
        Match.0.groupSize = how many participants are in a group
        Match.0.maxRounds = number of rounds per match
        Match.0.exchangeRate = exchange rate for each round.

Note that these properties can be changed from round to round by specifying the round number like so:

        Match.1.groupSize = 2
        Match.2.groupSize = 4
        ## Et cetera.

The extension writer has little to do with this in staged games, however, there are some issues in the code that will be necessary to make certain that everything aborts correctly. Never catch AbortRoundExceptions. If you wish to catch other Exceptions, use a double catch clause like thus:

        try{
            //code
           }catch(AbortRoundException abort){
               throw abort;}
            catch(Exception e){ do something }

Asynchronous is treated in its own section.

To output data to the output file, use the methods:

• addOutput group specific, round specific output
• addMatchOutput group specific, whole match output

See the API Documentation for specifics on the parameters and the XML output format used by the outputService. Just remember that questions can automatically write to the output file, one only needs to record player interactions.

While most staged games can be restarted and reauthentication is not needed, asynchronous does not have that feature. The default procedure in the case of a failure is to restart the whole round. This can be very bad for games with long rounds or games that don't want to restart. The way to deal with this is to override the reauthenticate method on the client side. The procedure for dealing with a round failure will be different for each game, but generally Information objects are sent back and forth. In order for this custom method to be called, the asyncReauthMode parameter must be set to 'manual'

To end the game before it has reached the number of rounds specified, one can either throw an AbortRoundException, or call abortRound on the server side.

AbortRoundExceptions should not be processed by the extension. Instead they should always be sent to the super class. See the Section "Aborting the Round" under the server section of this document for more information on how to handle this.

Asynchronous games support time limits. The only change that needs to be made is to look for a TIME_ELAPSED_MESSAGE when processing the messages.

Parsing replaces a particular key expression with a corresponding value. The implementation chosen for Multistage is to have the keys in the form of a key-pod. A key-pod is an expression of a key surrounded by '%' For example, %this% is a key-pod.
Further implementation details (these apply to both server and client side):

1. A key-pod will be ignored if it is preceded by a \. For example, this \%key-pod% is ignored. This is intended to be used to write %'s without being interpreted.
2. If a key-pod is not found in any of the resources available, the key-pod will not be replaced.

Parsing can be done on server side using the parseString method. The server-side has two information sources to search: the configuration file and a Hashtable passed in. The default order for searching is to search the Hashtable first, and then resort to the configuration file only if it does not find it in the Hashtable. If no Hashtable is passed into the parseString method, then it defaults to searching the configuration file.

Parsing can also be done on client side using the parseString method. Unlike server-side parsing, the client-side has only one source of information. All keys must be passed in as keys in the Information object sent in the ask* methods. Also, unlike the server-side, there are several key-pods that are reserved for system use (or rather, they take precedence over any user defined keys of the same name). These keys are currently:

1. id: the ClientData ID
2. groupSize: the group size
3. partnerNum: the partner number index

There is no implementation in the parsing software to stop a spinlock. This means that if a key-pod points to itself it will not break from it. For example, don't set the following:

        #conf file or hashtable
        first = %first%

Since the process is iterative, it will not stop parsing. This will not be a problem unless you make it a problem. There is no legitimate use.