Changes between Version 2 and Version 3 of UserGuide


Ignore:
Timestamp:
Aug 25, 2015 4:55:54 PM (2 years ago)
Author:
crabbe
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • UserGuide

    v2 v3  
    77 * ''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.''
    88 *  ''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)''
    9  *  ''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. Refer to 'Automated testing' under Optional Services.''
     9 *  ''To specify where the clients store persistence information for reauthentication, you must modify the 'conf/[wiki:mult-client.properties]' file to set the 'serializePath' parameter value to a directory where the client has permission to write.''
    1010
    1111== The Server Interface ==
    12 [[Image(Client.monitor.jpg, 500px, align=right)]]
    13 
    1412=== Starting and Running a Session ===
    1513 1. Execute 'server-multistage.bat' in the bin subdirectory of your installation.
     
    2826
    2927==== Messaging Clients ====
    30 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.
     28Clients 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.
    3129
    3230==== Reauthenticating Clients ====
     
    5048
    5149== The Client Interface ==
    52 [[Image(mult-client.png, align=right)]]
    53 
    5450=== Connecting To The Server ===
    5551
     
    6359
    6460=== Parameter Service ===
    65 GUI based parameter file manipulation. Features include: error check, modification, creation, logic check, and output.<br>Currently only supports pldk.
     61GUI 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.
    6662
    6763=== Output Service ===
     
    7268 * ''.xml'' -  XML is a generalized format which is convenient to use to read data into other computer software.
    7369
     70The software also outputs a .pay file which specifies the earnings of each subject throughout the experiment.
     71
    7472=== Automated Testing ===
    75 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:<br>
    76 '''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.
     73Automated 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:
     74
     75'''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.
    7776
    7877 * '''defaultSeed''' - Used for reproducing identical results in testing. Enter a number or '0' for random seed selection.
    79  * '''naming''' - Used for auto-generating names apon client side window to increase efficiency of high volume subject testing.
     78 * '''naming''' - Used for auto-generating names on client side window to increase efficiency of high volume subject testing.
    8079 * '''confirmDelay''' - Delay time after client clicks confirm (in milliseconds).
    8180 * '''moveDelay''' - Delay time after client makes move.
    82  * '''gameDelay''' - Delay time after server advaces games.
    83 
    84 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 client will automatically make moves according to the specified properties above.
     81 * '''gameDelay''' - Delay time after server advances games.
     82
     83After '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.
    8584
    8685=== Authentication Service ===
    8786Without 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:
    8887
    89  * [wiki:DatabaseAuthentication Database Authentication] - subjects' names are checked against entries in a database.  Please click [wiki:DatabaseAuthentication Database Authentication] for more details.
    90  * [wiki:FileAuthentication File Authentication] - subjects' names are checked against entries in a file.  Please click [wiki:FileAuthentication File Authentication] for more details.
     88 * [wiki:DatabaseAuthentication Database Authentication] - subjects' names are checked against entries in a database.  Please see [wiki:DatabaseAuthentication Database Authentication] for more details.
     89 * [wiki:FileAuthentication File Authentication] - subjects' names are checked against entries in a file.  Please see [wiki:FileAuthentication File Authentication] for more details.
    9190
    9291{{{
     
    108107
    109108== Parameters File ==
     109
     110Every 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.
     111
     112Each 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.
     113
    110114=== Common Syntax and Parameters ===
    111115''The following must be specified once within the configuration file''
     
    122126||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||
    123127||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||
    124 ||match.N.numOfGames||integer||Yes||None||Tells the framework how many games exist in this match. Each game must be defined in the parameter file.||match.1.numOfGames=8||
    125128||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||
    126129||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||
    127130||match.N.matching||matching algorithm||No||random /continue||Sets the matching algorithm. Matching algorithms are discussed in the [wiki:MatchingService Matching Service] section.||match.2.matching=random||
    128 ||match.N.exchangeRate||float||No||1.0||Sets the exchangeRate. 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||
     131||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||
    129132||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||
    130133||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||
     
    200203
    201204=== Match Parameters ===
    202 Match-specific parameters can be added to any file, and these are documented for each extension separately, often in the parameter file itself.
     205Match-specific parameters can be added to any file, and these are documented for each game plugin separately, often in the parameter file itself.
    203206
    204207In general, match specific parameters are of the form: