Configuration

There are many configuration parameters you can use to modify the runtime behavior of the foraging experiment. This is an area that could use a lot of improvement so if you'd like to contribute, please let us know.

Configuration files found in the src/main/resources/configuration directory are the active configuration used by the foraging software when deployed. You should ensure that the src/main/resources/configuration directory contains server.xml and round*.xml files. Existing configurations from experiments run at Arizona State University, Indiana University, and the Stockholm Resilience Centre are stored in the asu, iu, and stockholm directories in src/main/resources/configuration - feel free to modify these or use them as a template.

If you're interested in creating a new experiment configuration, we typically perform the following workflow:

1. Create a subdirectory in src/main/resources/configuration to store your new configuration files, e.g., src/main/resources/configuration/example-configuration. If you plan on having multiple treatments, we will create one directory per treatment, where each directory contains all the configuration files for a specific treatment, e.g., example-configuration/t1, example-configuration/t2, example-configuration/t3, example-configuration/t4.
2. Either copy over a set of configuration files from a similar experiment treatment to bootstrap the process and then edit the files.
3. Run ant deploy from the top-level foraging directory where the build.xml file resides - see [Foraging Deployment] for more information about deployment.

Server Configuration Parameters

Notes:

• all text/html types should be wrapped in a <![CDATA[...]]> block and will be displayed in a JEditorPane which only supports basic HTML 3.2 (see javax.swing.text.html.HTMLEditorKit for more details).
• most configuration parameters have defaults

Server Parameter Key	Type	Allowed Values	Description
number-of-rounds	positive integer	1 - N	number of round configuration file keys to look for in the given treatment (round0..roundN).
round0..N	string filename	round configuration filename for the given round	round0 is the first round, round1 is the second round, etc. This is used in combination with the number-of-rounds parameter. For example, if number-of-rounds is 6 and there are round0 to round8 keys mapped, only round0, round1, round2, round3, round4, and round5 keys would be looked up before the experiment ends.
welcome-instructions	cdata	templated text/html	shown at the start of the experiment as participants are sitting down to their stations
general-instructions	cdata	templated text/html	first page of instructions shown after facilitator sends a Show instructions request to the server
client-debriefing	cdata	templated text/html	debriefing text shown to each participant after each round
facilitator-debriefing	cdata	templated text/html	debriefing shown to facilitator keeping track of client data including current tokens, income, earnings, and total income. (be careful if modifying)
same-as-previous-round-instructions	cdata	templated text/html	canned text to be shown when an upcoming round has the same configuration as the previous round (for repeated rounds)
chat-instructions	cdata	templated text/html	instructions to be shown during a communication round (and for in-round chat)
trust-game-instructions	text	templated text/html	instructions to be shown during a trust game
show-up-payment	currency decimal	0 to N	the base amount to pay a participant for showing up. default show up payment is $5.00
quiz-correct-answer-reward	currency	0 to N	amount of money to pay for a correct quiz answer. default is $0.50
dollars-per-token	currency	0 to N	exchange rate to convert between tokens to cash. default is $0.02
survey-id-enabled	boolean	true/false	enables/disables the prompt for a survey ID to be used when displaying external Qualtrics surveys

Round Configuration Parameters

Most round configuration parameters not found in the round configuration file will be looked up in the server configuration file.

Round Parameter Key	Type	Allowed Values	Description
duration	positive integer	0 - N	Duration of this round, in seconds.
chat-enabled	boolean	true / false	Enables or disables communication for the given round. If in round chat is enabled, this means that communication will be allowed during the round, otherwise it enables a dedicated chat round at the beginning of this round.
regrowth-rate	floating point number	0 < R <= 1.0	Scaling factor applied to the probability of regrowth for every given empty cell in the resource environment. Regrowth depends on the resource-generator being used - by default the resource-generator is set to "density-dependent", and the probability of regrowth in any given cell is given as regrowth-rate * (number of neighboring cells with tokens / total number of neighboring cells).
chat-duration	positive integer	0 - N	Duration of the communication round, in seconds. If in round chat is enabled, this parameter is unused.
chat-instructions	cdata	templated text/html	Rudimentary HTML or text to be displayed during chat rounds.
practice-round	boolean	true / false	Marks the given round as a practice round. Specialized practice round instructions will be shown. Participants are able to reset the resource distribution but do not receive any income from the tokens they collect.
private-property	boolean	true / false	Marks the given round as a private property round, with no groups
randomize-group	boolean	true / false	If true, all participants are re-shuffled into new groups at the start of the round
external-survey-enabled	boolean	true / false	enables / disables external survey support
survey-url	cdata	templated text URL	survey urls should be wrapped in a and can contain a templated {self.surveyId} variable to refer to the specific participant survey id entered on the participant interface at the start of the experiment.
survey-instructions	cdata	templated text/html	instructions to be shown above the external survey url link
resource-width	positive integer	1 - N	Number of horizontal grid cells to display, default is 28
resource-depth	positive integer	1 - N	Number of vertical grid cells to display, default is 28
initial-distribution	floating point	0 < D <= 1.0	Decimal between 0 and 1 that determines the number of cells in the grid that should be randomly initialized (resource-width * resource-depth * initial-distribution = initial-number-of-resources)
starting-tokens	positive integer	1 - N	if specified, this overrides initial-distribution and will randomly place a flat number of initial tokens in the resource grid using in a uniform distribution
clients-per-group	positive integer	1 - N	max group size