Installation

Server Setup

In order to run our Java-based experiment software you'll need to:

1. Install the latest Java JDK
2. Install Ant, and optionally Maven to use the built-in Jetty webserver
3. Download the foraging codebase or clone the git repository onto your experiment server. The experiment server can run on any OS with Java.
4. Configure the experiment you'd like to run by copying your configuration files (server.xml and round*.xml files) into src/main/resources/configuration and setting the appropriate server/URL properties in build.properties.
5. Deploy the experiment and start the experiment server, facilitator, and all client application.

Running the software

After a successful deployment, there are three components to the foraging software that need to be run, in order (assuming you are using Java WebStart).

1. Start the experiment server via java -jar -server server.jar or ant server on your server machine.
2. Start one facilitator (you can do this locally on your server via ant fac or java -jar facilitator.jar) or via Java WebStart by opening http://example.com/foraging/facilitator.jnlp in a browser, where http://example.com should be replaced with your server machine's URL. The facilitator application is used by the person running the experiment to monitor and drive the experiment, transitioning from one round to the next, deciding when to show instructions and other tasks.
3. Start the foraging client on each machine that will be participating in the experiment. Our foraging experiments run with 10+ participants, partitioned into groups of 5, so we always start the experiment on 10 clients, and start up 5 more clients at a time as more participants trickle in.

Client applications can be started with Java WebStart by opening a browser to http://example.com/foraging/ or by opening the saved client.jnlp file if you have already downloaded one from a previous run.

After the client has started you should see a general instructions / waiting room type message on the screen. If the client fails to start, enable the Java console and examine the errors there or check the server logs. If all else fails, feel free to send us a note.

After all clients and the facilitator have successfully connected to the server, return to the facilitator interface and click on the Round -> Show Instructions menu item to send the first round's instructions to each client interface. You should see every connected client's interface change to display the instructions for the practice round. If the images in those instructions don't display properly, there is a problem with the webserver / deployment configuration - see troubleshooting deployment.

The experiment won't begin even if you click on Experiment -> Start or Round -> Start as the server is waiting for all clients to submit the introductory quizzes. To skip this step you can enter 'skip-quiz' in the terminal window where you are running the experiment server. Now clicking on Round -> Start will begin the round and transition every client to the actual game round.

When a round ends, each client interface is automatically switched to a debriefing page that typically displays that participant's current earnings and that of their group as well as any additional instructions, debriefing, or survey instruments as needed. After the participants have had enough time to read their debriefing, click on Round -> Show Instructions to display the next round's instructions to each client. If the treatment calls for dedicated communication rounds you can select Round -> Chat, or just continue with the Round -> Start, Show Instructions sequence. To end an experiment round prematurely you can use Round -> Stop.

The explicitness of experiment transitions is designed to let experiment facilitators address any questions or disruptions that may occur in between rounds.

Experiment Data

For more details on how to interpret and process foraging experiment data, please see Experiment Data