Multistage User's Guide

Note: You MUST follow these steps prior to running Multistage for the first time.

• To specify log directories and other log details, you must modify the 'conf/log4j.properties' file for server-side and 'clientlog.properties' for client side.
• To specify the server (ip) address of the multistage server, you must modify the 'conf/multistage.properties' file where it says "defaultHost=". (Example: defaultHost = 128.97.190.171)
• To enable testing mode, you must modify the 'conf/multistage.properties' file where it says "defaultMode =". Enter "testing" to enable testing mode, or "normal" for normal mode. Refer to ‘Automated testing’ under Optional Services.

1. Double click the ‘server-multistage.bat’ in the bin directory of your installation directory.
2. Select the number of players by clicking on the ‘Set Number of Players’ button. The number of players must be divisible by all group sizes specified in the parameters file.
3. Load a parameters file by clicking on the ‘Load Parameters File’ button.
4. Set an output file by clicking on the ‘Set Output File’ button. The output will be saved to this file each time the ‘Next Game’ button is pressed.
5. Click on ‘Authenticate Clients’ to begin authentication.
6. When all of the clients are connected, click on ‘Confirm.’ Clients may also be dropped during authentication if they are no longer needed, or if the user specified too many clients.
   Note: Refer to “Using Client Interface” for more info on the Client process
7. All the clients will now be displayed in the Client Monitor section of the interface.
8. Click on ‘Start Game’ to begin the first game of the first match. The clients will now be partnered and color-coded organized by group.
9. When all the players have made their moves, click on ‘Next Game.’
10. Repeat step 8 until the match is finished.
11. When all clients have finished the match, click on ‘Next Match.’ The clients will now be repartnered.
12. Repeat steps 8-10 until the final match is complete.
13. When the final match is complete, the ‘Write Output’ button will appear instead of the ‘Disconnect Server’ button. Press this button to disconnect all the clients and get the final output. Two files will be created: ‘yourOutputFile’ – the data, ‘yourOutputFile.pay’ – the payoff summary.
    Note: See “Output Service” under Optional Services for formatted result files.

Displaying History
At any point during a session the current history of a single client can be viewed by pressing their ‘History’ button in the Client Monitor section. To view ALL histories simultaneously, click the ‘Display History’ button in the Actions section.

Messaging Clients
Clients can be messaged (if they are taking too long to move, etc) by clicking on the target client’s ‘Message’ button in the Client Monitor section. To message multiple clients simultaneously, select the ‘Send Message’ button in the Actions section, then specify the recipients either in the window to the right or by choosing one of the options on the left in the Messaging window.

Reauthenticating Clients
When a client gets disconnected, their status indicator will turn red and say ‘Disconnected’ instead of the green ‘Connected.’ At this point, that client’s ‘Reauth’ button will be enabled. To reauthenticate the client:

1. Click on the client’s ‘Reauth’ button.
• Note that reauthentication can only be done one client at a time.
• The Server will now wait for the client to reconnect.
2. On the client side, start up a new client on any computer.
3. Open the ‘Options’ menu and select the Reauthenticate box in the client Initialization screen. This is important, otherwise the server will not know that the client is trying to reauthenticate.
4. Type in the appropriate host, and type in the clients name EXACTLY as it appears in the Server Reauthentication window (it should be the exact same name they had typed in before).
5. The server Reauthentication screen should switch to ‘Connected’. At this point, click on ‘Confirm.’
6. The client should now be back in the game as normal.

Auto-Advancing Games and Matches
Under the Setup Menu it is possible to set the server to automatically proceed to the next game and/or match by checking those two boxes. This option is useful if the server administrator does not want to repeatedly click on ‘Next Game’ each time the clients are ready.

Logging Options
The Logging monitor provides detailed information about what is going on inside the Server. For the most detailed information (typically only desired by programmers), click on the ‘Debug’ button. To only receive the useful information, click on the ‘Info’ button. To only receive error and warning messages, click on the ‘Warn’ button.
For even more informative logging, click on the logging menu and activate ‘Show Location Info.’ Note that showing location info will decrease logging performance by a factor of 10! When location info is on, you also get the option to filter OUT messages that deal with networking or messages that deal with client-side debugging.

GUI based parameter file manipulation. Features include: error check, modification, creation, logic check, and output.
Currently only supports pldk.

Converts raw output file to more human-readable formats via XML.

Automated Testing allows experimenters to test desired extensions without subjects in a controlled environment. Can also be used to reproduce identical results to troubleshoot experiments prior to actual execution. Testing mode has the following features:
Note: To enable testing mode, you must modify the 'conf/multistage.properties' file where it says "defaultMode =". Enter "testing" to enable testing mode, or "normal" for normal mode.

• defaultSeed= Used for reproducing identical results in testing. Enter a number or '0' for random seed selection.
• naming= Used for auto-generating names apon client side window to increase efficiency of high volume subject testing.
• confirmDelay= Delay time after client clicks confirm.
• moveDelay= Delay time after client makes move.
• gameDelay= Delay time after server advaces games.

After ‘multistage-client.bat’ is executed, if naming is enabled, the client machine will submit itself to the server after 5 seconds. After, the client will automatically make moves according to the specified properties above.

Documentation in progress.

To use it, simply execute either the MultistageIntegratedTest file or the TestGUI file (they both do the same thing)
In the GUI that pops up, select a parameter file, an output file, and the number of groups you want to test with, then just watch what happens. You'll see the Server GUI but all the Client GUIs will be suppressed. The show() and setVisible() methods in ClientGUI are disabled for testing.
Look at the message screen and the status indicators to see if anything went wrong. It also verifies the output file to make sure all matches completed intact.
Note that although the ClientGUIs don't show up, they're still tested. But to do a more robust test of the ClientGUI normal testing mode or manual mode are still recommended.
So this should be used after making any changes to core server and extensions, as its really rapid and allows for large groups (and multiple groups) on a single computer.
Final note: The testing system monitors all messages sent through log4j. If an ERROR message is encountered, it registers this as meaning a process has failed. So when using log4j, use ERROR or FATAL when its a serious problem that should cause a test to fail, and use WARN when its just something kind-of bad that the user should know about (WARN will not cause tests to fail)

The following must be specified once within the configuration file

For each match N (from 0 inclusive to numOfMatches exclusive), the following fields must be specified:

For each game M within the match (M from 0 inclusive to numOfGames exclusive) the following paramteres must be defined:

Game Parameters:
For each game, the choices and next parameters must be specified. The following is a detailed explanation of what those parameters mean, and how to specify them.

There are two methods for specifying the choices available to each client in each game. The first is to use the syntax:
match.N.game.M.choices=<a-b,c> <d-e,f> …

This syntax specifies the available choices for each player, starting with player one. For each player in the group, there must be a <a-b,c> entry. The number of players, remember, was defined in the groupSize parameter for the match. Each <a-b,c> entry specifies the choices as follows:

• A player’s choices are all numbers between a and b (inclusive) that are divisible by c.
• So <0-1,1> means the player has choices 0 and 1. <2-10,4> means the player has choices 4 and 8.
• <0-100,30> means the player has choices 0, 30, 60, and 90.

The second method for specifying the choices is with the syntax:
match.N.game.M.choices=<a,b,c,d> <e,f,g,h> …
With this method the choices are specifically inputted into the parameter file, with no divisor. In the syntax example above, player one has choices a, b, c, and d, while player 2 has choices e, f, g, and h.

So <1,2,3> means the player has choices 1, 2, and 3, and <4,8,5,15> means the player has choices 4, 8, 5, and 15.

The first method is best used in games that give the player a wide range of choices, like any sort of bargaining game, while the second method is better for games that have a restricted set of choices, or choices that aren’t numerically near each other (like a Social Networks game).

The next required parameter is the next game parameter, which uses the following syntax:
match.N.game.M.next=<a,b,…,destinationGame>

This syntax specifies what game should be played next. Given the choices each player made, move to the given destination game. Examples are the best way to understand this:

If we have 2 players and the current game is game 0 and we wish to move to game 1 if player 0 chooses 6 and player 1 chooses 7, then we would include the following in the parameter file:

      match.N.game.0.next=<6,7,1>

which means “move to game 7 if player 1 chooses 6 and player 2 chooses 7”

If we have 4 players and the current game is 0 and we wish to move to game 5 regardless of what any player chooses, then the following would be included:

      match.N.game.0.next=<*,*,*,*,5>

Notice the usage of the * wildcard above.

If we have 3 players and the current game is 0 and we wish to move to game 11 if player 1 chooses something between 2 and 6, player 2 chooses anything, and player 3 chooses 52, then we have:

      match.N.game.0.next=<2-6,*,52,11>

Notice the use of the range 2-6 above.

Finally, if we wish to end a game, we specify the destinationGame as -1. For example, if we have two players and want to end the match if player 1 chooses 0 and player 2 chooses 0, then we would write:

      match.N.game.0.next=<0,0,-1>

Matching Parameters
Match-Specific and Game-Specific parameters can be added to any file, and these are documented for each gameType sparately.

In general, match specific parameters are of the form:

      match.N.<parameter>=<value>

And game specific parameters are of the form

      match.N.game.X.<parameter>=<value>

• Each match can have a different gameType, so one can mix entirely different games into a single parameter file / session.
• The two ways of ending a match are:
  1. specifying the maxRounds parameter
  2. specifying a match.N.game.M.next parameter with a -1
• The two game parameters MUST contain player options and player next parameters that are compatible with the chosen match groupSize. For example, if the groupSize is 2, writing match.N.game.0.next=<*,*,*,5> is INVALID.
• Match-Specific parameters are typically used to help with calculating the payoff, and are usually of the form match.N.someParameter=someValue.
  these are documented separately for each game.
• Matches ALWAYS proceed sequentially. Although the games inside a match can proceed in a non-linear order, matches must always be linear. This is because after each match all the players are RE-PARTNERED, so all players must always be in the same match.
• Notice that the groupSize can change between matches.

Here is a sample Parameter file that contains 5 rounds of the Voter game followed by 3 rounds of the Ultimatum game. In the Voter game each player has just 2 options, while in the Ultimatum game many more choices are allowed. Also, note the game-specific parameters for the voter game: wf = winning team payoff, lf = losing team payoff, npf = not participating payoff, m = number of players in the majority group.

        match.0.type=Voter
        match.0.groupSize=4
        match.0.maxRounds=5
        match.0.numOfGames=1
        match.0.game.0=<0-1,1>,<0-1,1>,<0-1,1>,<0-1,1>
        match.0.game.0.next=<*,*,*,*,0>
        match.0.m=3
        match.0.wf=100
        match.0.lf=20
        match.0.tf=60
        match.0.npf=50
        match.1.type=Ultimatum
        match.1.groupSize=2
        match.1.numOfGames=1
        match.1.maxRounds=3
        match.1.game.0=<0-1,1>,<1-150,1>
        match.1.game.0.next=<*,*,0>

Note: Under the ‘metadata’ folder are sample parameter files.