Setting up the Rule Game Server and Client

Updated 2024-03-06

This document descibes the process for setting up the Rule Game (a.k.a. Game of Hidden Rules - GOHR) software on your own web site, so that your team could design experiments and process experimental results independently of the University of Wisconsin - Madison team.

For an overview of the main concepts of the Game Server, see Main Rule Game server concepts.

Rule Game software components

The Rule Game project at University of Wisconsin - Madison has developed two products:

• The Captive Game Server (CGS) is a computer program which can be installed on a researchers computer so that his Machine Learning software can "play" with it. (A human can play with the CGS as well, but this is not particularly convenient, as you'd have to use a simple command-line interface). For the complete instructions on how to install and use the CGS, see the Captive Game Server page.
• The Rule Game web application, which allows human players to play the Game of Hidden Rules using a graphical user interface (GUI), while the researchers operating the application server can define new games and analyze the players' records. The rest of this document describes the process for installing and configuring the Rule Game web application server at your site.

The two applications described above can be installed and used completely independently from each other, even though the share much of their code base. (This means, in particular, that if you want to build both applications from source, you need to download the source code from our GitHub repository only once).

The Rule Game web application system used by the players and researchers consists of the following components:

• The Rule Game GUI Client. This an application written in TypeScript (a language built on top of JavaScript), which runs in a player's web browser (such as Chrome or Firefox). The GUI client is loaded into the player's web browser when the player goes to a certain URL on your server. Depending on your team's needs, you can install the GUI client code on your server as a WAR file precompiled by us at UWM; or you can choose to compile it from source. In the latter case, you can have the GUI client code customized as needed, beyond the customization that's already provided via the configurable pregame and postgame experiences. (For example, you may decide to change the appearance of some screens during the game).
• The Rule Game Server is a server-side web application. The GUI client continuously "talks" to the Game Server dring a game. We run a Game Server instance on our host at UWM; your team will need to set up its own instance of the Game Server at your own host, so that you can easily create and modify experiment plans and process collected data. Typically, to install the Rule Game Server, you need to install an Apache Tomcat Web Server, and to place a WAR file with the Rule Game web app code into the web app directory of the Tomcat server. You can use the WAR file we provide (in which case, you will have an exact copy of a recent version of our Rule Game Server code), or you can download our source code, modify it as desired, and build the WAR file from source.
• The SQL database. To run your instance of Rule Game Server, you need to have it "talk" to a relational database server (such as a MySQL server), which will contain a database named game. In that database the Game Server will store some types of information that it needs to continiually create, read, and modify, such as the record of the progress of a player through a series of episodes. (For details, see "Read-and-write data" in the Game Server Data Guide). You probably will want to run the SQL server on the same host as your Rule Game Server.
• The experiment control files. To define the set of experiments (games) that the players can play, you need to place an appropriate set of experiment control files to a specified directory on your server host. (From the Rule Game Server's point of view, Those files are "read-only file", because it is you, the experiment manager, who create and modify them, while the game server only reads them. This is how they are referred to in the Data Guide).
• Server output files. You need to designate some directory on your server hosts for the files that the Game Server will write, recording the players' game transcripts etc. Those are the game server's "write-only files" (as per the Data Guide terminology). You may later analyze those files with the tools supplied with the server, or with your own tools.

Necessary third-party software

Client side

To play games, a player need a computer with a modern web browser, such as Chrome or Firefox.

Server side

We are running the Rule Game web application server on a Linux machine (the OS version is Ubuntu 18.04), but if you like challenge, you probably can set it up on a MacOS or MS Windows machine as well. (We have tested a MacOS installation successfully on MacOS Catalina 10.15.7, but not a MS Windows one so far).

The necessary third-party software includes the following.

Mandatory (sufficient if you want to install the pre-built WAR file):

• Java virtual machine (JRE). (Type which java on your console to see if you have one already).
• Apache Tomcat web server (or any other web server that supports WAR format)
• A relational database server, such as MySQL server.

Optional (needed if you want to build the server from source, i.e. go for Option B or C):

• Java compiler (JDK). (Type which javac on your console to see if you have one already).
• A Github client, to conveniently get source code from the GitHub server. (Type which git on your console to see if you need one).
• Apache Ant, to control the build process.
• A number of third-party libraries, as documented elsewhere.

Setup Option A: server and client binary install.

There are several ways to set up your Rule Game software. Option A is the simplest one. If you follow this option, you will install on your server host two WAR files (Web application Archive file) pre-built by our team at UWM, and for the server and one for the client. Here are the step-by-step instructions.

1. The SQL database. You need to install a relational database server, if you don't have one already. Our team uses a freely available MySQL server, but if you're running something else (such as the Microsoft, Sybase, or Oracle SQL server), it probably will do fine as well. At the server, create the datbase named game, and the user account named game as well. For more detailed instructions, see SQL database setup guide.
2. The master configuration file. This file will, among other things, tell your Rule Game Server how to connect to the database server. See config file setup for details.
3. Tomcat. Assuming that you have chosen the Apache Tomcat as your web server, install it (if you don't have it yet) and configure it for running the Game Server web app on it. For the instructions (which also ask you to install an additional library), see Tomcat setup guide. Once Tomcat is running, you should be able to verify that it's running by going to the appropriate URL, such as http://MY_HOST:MY_PORT/ . (Put your host name and port number instead of MY_HOST and MY_PORT in the URL; if you are sitting at your server's console, and are using the default port number 8080, that would be http://localhost:8080/ )
4. Rule Game Server WAR file. Download a recent version of our server application WAR file from our server's Download Area. Look for a recent file with a name such as w2020.war or w2020-5.002-2022-06-01.war, rename it to w2020.war if needed, and put that file into the web apps directory of your Tomcat (/opt/tomcat/webapps, if you followed our defaults). You can do it by simply copying the downloaded WAR file to that directory, or you can use Tomcat's management web interace for loading applications ( http://localhost:8080/manager/html , if you are sitting in front of your server).
5. Rule Game GUI Client WAR file. In this option, you will simply download a recent version of our client application WAR file our server's Download Area (look for a recent file with a name such as ruele-game.war), and put that file into the web apps directory of your Tomcat (/opt/tomcat/webapps, if you followed our defaults). You can do it by simply copying the downloaded WAR file to that directory, or you can use Tomcat's management web interace for loading applications ( http://localhost:8080/manager/html , if you are sitting in front of your server).
6. Experiment control files. To be able to run experiments, you need to populate the experiment control file directory (/opt/w2020/game-data, if you followed our defaults) with control files for some experments. See the experiment control file setup guide.
7. Testing! Now that everything is in place, you can test some components of the software system you have just set up, to see if it actually works. See the testing guide to get started.

Setup Option B: server source code install + client binary

Instead of downloading the WAR file, you may choose to download the Game Server source code and the necessary third-party libraries, and carry out the build process yourself, compiling the source code and building the WAR file. This approach is appropriate if:

• ... you want to continuously update your Game Server instance as we check in source code updates to the GitHub repository, without having to download a huge WAR file every time.
• ... you want to customize the Game Server source code (e.g. because you want to create your own extension of the rule syntax).
• ... you want to use off-line data analysis tools (scripts for processing transcript files etc), the source code for which comes as part of the Game Sersver code base.

In this case, the setup process is as follows:

1. Set up the SQL database, exactly as in step 1 of Option A.
2. Set up the master configuration file, exactly as in step 2 of Option A.
3. Set up Tomcat, exactly as in step 3 of Option A.
4. Download the necessary third-party libraries, as well as the tools necessary for compilation. (You would not need to do that with Option A, because those libraries are already included into the WAR file). See the list here.
5. Download the source code of the Rule Game Server from our Github repository: Rule-Game-server, compile it, and build a WAR file. For instructions, see the Rule Game Server build Guide. You can also make any code changes here, if desired.
6. Download and install the GUI client WAR files, as per Step 5 in Option A.
7. Work on your control files, as per Step 6 in Option A.
8. Proceed with testing, as per Step 5 in Option A.

Setup Option C: server source code install + client source code install

You can choose to compile the GUI client from the source code, instead of downloading the WAR file. This is appropriate if you want to customize the client in some way.

The steps are the same as in Option B, except that in step 6, instead of just downloading the client app WAR file, you download and compile the source code. See client setup for details.