This user's guide assumes that the Multistage framework is installed on the computers on which it will be used. Please follow the Install Guide for more details on this process.
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 = 184.108.40.206)
- To specify where the clients store persistence information for reauthentication, you must modify the 'conf/mult-client.properties' file to set the 'serializePath' parameter value to a directory where the client has permission to write.
The Server Interface
Starting and Running a Session
- Execute 'server-multistage.bat' in the bin subdirectory of your installation.
- 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.
- Load a parameters file by clicking on the 'Load Parameters File' button.
- Set an output file by clicking on the 'Set Output File' button. The output will be saved to this location each time the 'Next Game' button is pressed.
- Click on 'Authenticate Clients' to begin authentication. When all of the clients are connected, click on 'Confirm.' All the clients will now be displayed in the Client Monitor section of the interface. Note: Refer to "Using Client Interface" for more info on the Client process
- 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.
- Proceed through all specified rounds and matches, clicking the "Next Round" and "Next Match" buttons to continue to the next round or match when applicable.
- When the final match is complete, the 'Write Output' button will appear in place of the 'Disconnect Server' button. Press this button to disconnect all the clients and get the final output. Output will be written to the file specified in step 4, including a file with a .pay extension, which specifies payments owed each player.
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.
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. This only applies if the clientMessages object is added to the game's GUI.
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:
- 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.
- On the client side, start up a new client on any computer.
- 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.
- 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).
- The server Reauthentication screen should switch to 'Connected'. At this point, click on 'Confirm.'
- 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 round and/or match by checking the "Auto Advance Rounds" and "Auto Advance Matches" boxes. This option is useful if the server administrator does not want to repeatedly click on "Next Round" and "Next Match" button each time the clients are ready.
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.
The Client Interface
Connecting To The Server
- Double click the 'client-multistage.bat' in the bin directory of your installation directory.
- Enter a subject name and host address, then click the 'Submit' button. The host address will usually by provided by the program.
Subject interaction varies with each extension. Refer to extension documentation for more details.
GUI based parameter file manipulation. Features include: error check, modification, creation, logic check, and output. This is an optional service that must be programmed specifically for each game plugin in order to be used.
The format of the raw output file created by multistage is similar in structure to the parameter files used for input, using parameter names and values separated by an equals sign. The output service converts this raw output into several other formats, for the convenience of the user.
- .html - viewable in a web browser, this format contains tables with each line in the table representing one subject in one round.
- .csv - a comma-separated-variable file, viewable in excel or other spreadsheet file. Contains the same table format as the .html file.
- .xml - XML is a generalized format which is convenient to use to read data into other computer software.
The software also outputs a .pay file which specifies the earnings of each subject throughout the experiment.
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 "manual" 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 on client side window to increase efficiency of high volume subject testing.
- confirmDelay - Delay time after client clicks confirm (in milliseconds).
- moveDelay - Delay time after client makes move.
- gameDelay - Delay time after server advances games.
After 'multistage-client.bat' is executed, if automatic naming is enabled, the client machine will submit itself to the server after 5 seconds. After the game starts, the client will automatically make moves according to the specified properties above.
Without authentication, subjects are allowed to type any name they choose into the "Name" field of the multistage Client Startup window, and this name is included on the payment sheet. With authentication enabled, experimenters are able to restrict the names with which subjects can log in. There are currently two types of authentication available:
- Database Authentication - subjects' names are checked against entries in a database. Please see Database Authentication for more details.
- File Authentication - subjects' names are checked against entries in a file. Please see File Authentication for more details.
Every parameters file represents an entire experimental session. Every experimental session is divided into a number of matches, defined by the numOfMatches parameter. Each match is further divided into rounds, specified by the match.N.maxRounds parameter.
Each round in a match is primarily intended to be an exact duplication of each other, and groups are not re-matched between rounds. Thus, the platform does not natively provide a way to change parameter values between rounds in a match. Each match can have a different value for each game parameter.
Common Syntax and Parameters
The following must be specified once within the configuration file
|Field||Value Type||Required||Default Value||Purpose||Example|
|exp.id||integer||Yes||None||This is the number by which the lab will refer to this experiment.||exp.id=5|
|numOfMatches||integer||Yes||None||Indicates how many matches are contained within this parameter file.||numOfMatches=7|
For each match N (from 0 inclusive to numOfMatches exclusive), the following fields must be specified:
|Field||Value Type||Required||Default Value||Purpose||Example|
|match.N.type||string||Yes||None||The Game String Identifier is a word that is recognized by the program. This identifier is important because it directs the Server and Clients to load the right interfaces.||match.2.gameType=Pldk|
|match.N.groupSize||integer||Yes||None||groupSize specifies how big each group of players is. A group is defined as in independent set of players playing the game specified by gameType. Players in different groups have no interaction with one another. For 2 player games, the groupSize would be 2. For larger games, such as Voter, the groupSize can vary largely. It is important to note that the number of players in the game must be divisible by all group sizes.||match.1.groupSize=4|
|match.N.maxRounds||integer||No||None||maxRounds will force the end of a match after a certain number of rounds have transpired.||match.2.maxRounds=10|
|match.N.practice||true/false||No||false||If practice is set to true, then this match will be designated as a practice match. Practice matches act exactly the same as real matches, except they are never counted in the total payoff amount (not in the output and not in the history windows).||match.3.practice=false|
|match.N.matching||matching algorithm||No||random /continue||Sets the matching algorithm. Matching algorithms are discussed in the Matching Service section.||match.2.matching=random|
|match.N.exchangeRate||float||No||1.0||Sets the exchange rate. The exchange rate is multiplied by the final payoff amount to get the actual cash amount that will be given to the clients for their participation.||match.2.exchangeRate = 0.40|
|match.N.repetitions||integer||No||0||The number of times this match will be repeated. If match 0 is has repetitions set to 5, then matches 0 through 4 will be equivalent to match 0. Described further in the [Special Parameters] section.||match.5.repetitions=2|
|match.N.clone||integer||No||None||Indicates a match to clone. In the example to the right, match 2 becomes an exact clone of match 5. Described further in the Special Parameters section.||match.2.clone=5|
Match-specific parameters can be added to any file, and these are documented for each game plugin separately, often in the parameter file itself.
In general, match specific parameters are of the form:
- Each match can have a different gameType, so one can mix entirely different games into a single parameter file / session.
- Match-Specific parameters are typically used to help with calculating the payoff, and are usually of the form match.N.someParameter=someValue.<br> these are documented separately for each game.
- The groupSize can change between matches.
Sample Parameter Files
Sample parameter files can be found in the metadata subdirectory of the multistage installation.