Setup: Experiment Control Files

Updated 2024-03-06

To run experiments (i.e. let people play according to the rules you have set up, with s), you need a set of experiment control files for each experiment you want to be played.

For some background on how experiment plans describe an experiment, see "Experiment plans and trial lists" in The main concepts, and Read-only data: experiment control files in the Data guide. More practical details are found in Standard Operating Procedures: Preparing and running an experiment with the Rule Game Server, and in other documents in the "Designing an experiment" section of our documentation library.

"Borrowing" UWM's set of experiment control files

A complete set of control files for an experiment can be created from scratch, as per the SOP instructions. However, as you can see from the documentation above, the system of control files needed for a non-trivial experiment may be fairly complex. Therefore, in order to get accustomed to different types of experiment plans, and to different ways in which experiment plans can be designed, it may be convenient for you to start with taking wholesale the entire set of our experiment plans, and then work off that base.

Our team at UWM has experiment control files at two different GitHub repositories. All the data used by the team are the repository RuleGame/Rule-Game-game-data. Additionally, researchers from outside the Lupyan Lab can download the content of the public repository Rule-Game-server instead. This repository contains a sampling of experiment control files as well, in the directory game-data.

You can download the files from the public repository, and install the data in your desired data directory, as follows. (We assume that you use subdirectory w2020 under your home directory as a temporary staging area, and that the location of the experiemnt file directory is set in your master config file with

	FILES_GAME_DATA = "/opt/w2020/game-data";

  cd
  mkdir w2020
  cd w2020
  mkdir game-data
  cd game-data
  git init
  git remote add origin https://github.com/RuleGame/Rule-Game-game-data.git
  git pull origin master
  sudo cp -pa game-data /opt/w2020

Note: if you use MacOS, it does not have the "cp -a" command with this functionality. Look up the command ditto instead.

Once the experiment control files have been installed, you may try to play some games based on them. You can start a game session from the main launch page, whose URL is like http://rulegame.wisc.edu/w2020/front-end-form.jsp, but of course with your own host name and port name (if not 80) instead of ours.

Later on, as we add more control files to the repository, you can update your local copy of these files as follows:

  cd ~/w2020/game
  git pull origin master
  sudo cp -pa game-data /opt/w2020

After you have done that, you will have the experiment control files under /opt/w2020/game-data

Skipping the staging directory

It may be easier to skip creating the staging directory on your server, and to check out the control files from the GitHub repository directly to the experiment control file directory of your sever.

Here we assume that this directory is /opt/w2020/game-data, and that it's owned by user tomcat (because that's the user who runs the Tomcat process, and therefore needs to read those files):

  sudo -u tomcat mkdir /opt/w2020/game-data/
  cd /opt/w2020/game-data/
  sudo -u tomcat git init
  sudo -u tomcat git remote add origin https://github.com/RuleGame/Rule-Game-game-data.git
  sudo -u tomcat git pull origin master
  

Creating your own experiment control files

Once you have understood, with the help of the Data guide and the Rule Syntax Guide, some of the examples supplied via our GitHub repository, you may want to start creating your own experiment plans.

The simplest way to do that is by creating the necessary files (typically, this means creating at least one trial list file and at least one rule set file), and manually placing them in appropriate subdirectory under your FILES_GAME_DATA directory). While this is fine for a small project, we will suggest that if you plan to do a substantial amount of experiment plan development, you should invest in creating your own repository on GitHub (or with some other version-control system) for storing your experiment control files.

Manual deployment with GitHub

If the entirety of your development work will take place on the same computer that runs your Game Server, then, in principle, you can simply treat your FILES_GAME_DATA directory as the local directory associated with the GitHub repository, and edit the files right there. If your project has a more complicated organization (various people editing files on their personal computers; some others prefer doing editing via the GitHub web interface), then you may consider creating a framework similar to what we do at UW. You can arrange for either manual or automatic updates. For manual updates, you can establish a standard operating procedure whereby a team member who checks some updates to your data repository will need to login (ssh) to your server, check out the data to his local directory, and then copy them over to the FILES_GAME_DATA directory. (Or, of course, as it's been already mentioned above, he can save a step and check the data out directly to the FILES_GAME_DATA directory.) As an example, see our Standard Operating Procedures: Preparing and running an experiment with the Rule Game Server.

Automatic deployment with GitHub Actions

[Back to Setup]