Updated for Ver 4.002, 2021-11-19
In this document we discuss the main concepts of the Rule Game server: repeat users, players, experiment plans, trial lists, series, episodes.
The concept of repeat user was introduced in GS 4.*. A repeat user represents the information about a human user who starts his games from one of Game server's launch pages that require (or at least suggest) user identification (such as the MLC launch page or the APP launch page, or from the Android app.
For every repeat user we have an entry in the User table, with a unique integer ID as a primary identifier. A repeat user may be "named" or "unnamed". A named repeat user may be also identified by an email address and/or a self-selected nickname. An unnamed repeat user does not have those; it is simply an object that is used to link together all game rounds started by an anonymous user from the same web browser. (Internally, these rounds are linked together using browser cookies).
A player, identified by a playerId, represents the interaction of a human being with the game server within the scope of a single experiment plan. Every player is permanently associated with a single experiment plan. At the beginning of the player's interaction with the system, the player is pseudo-randomly assigned to one of the trial lists of that experiment plan. The player then experiences everything that the trial list prescribes to be experienced; that is, he plays a round (several series) of episodes, and at the end of this experience, is issued a completion code. After that, no user-system interaction involvingh that playerId is supposed to take place. (If tried, the system will tell the player that he has played everything he was to play).
For each player, an entry exists in the SQL table PlayerInfo. The server also maintains two output files for each player, one to contain the initial board positions of all episodes played by the player, the other for the episodes' transcripts (a record of all attempted moves, successful and unsuccessful).
A player entry may or may not be associated with a repeat user. (This is reflected in the PlayerInfo table). Specifically:
An experiment plan is described by a set of trial lists. (It may, contain just one trial list, or several). Each trial list describes the sequence of experiences (or a "treatment") in which a certain group of players will participatye. Whenever a player starts participating in an experiment (is about to start playing), he is automatically assigned to one of the trial lists; this is association is permanent, i.e. all experiences of this player will follow that trial list.
A trial list is a detailed "road map" to what a player associated with that trial list may experience. A trial list (in the original "static" variety of experiment plans) is described by a CSV files consisting of several lines of data. Each line specifies a parameter set; the parameters in the parameter set determine what kind of game will be played (by referring to a specific rule set file), what the initial boards may look like, how many episodes may be played, how rewards will be assigned, etc. The player will progress through the lines of the trial list in the sequence in which they appear in the trial list file, i.e. once you complete a certain number of episodes pursuant by one parameter set (a series of episodes), you will be able to (or you will have to) switch to the next parameter set; there is no going back. The series of episodes played in accordance with a given parameter set may be divided into the main subseries and the bonus subseries. For details, see the document on Control flow.
The Rule Game server provides several ways for the experiment designer to describe an experiment plan. The types of experiment plans that has been supported since the original GS 1.* is now called "static experiment plans". Additionally, in GS 4.* the so-called "dynamic experiment plans" were introduced. Those come in two varieties, the "P:" type and "R:" type.
This arrangmenet, originally developed by Gary, works as follows. For each static experiment plan, an appropriately named directory exists under the control file directory. In that directory, one or several CSV files (known as trial list files) are placed, each one describing a (static) trial list. Each line of each of those trial list files must contain all parameters needed to run a series of episodes.
A static experiment plan is identified by the name of the plan's directory, relative to the main experiment plan directory in the control file data tree. For example, the directory for the plan named APP/foo will be in /opt/tomcat/game-data/trial-lists/APP/foo
Sometimes an experiment designer may want to carry out an experiment which is very similar to one that is already described by an existing static experiment plan, but with a few differences from that. For example, suppose we like plan named foo, but we want to change the number of game pieces on the initial board, and the feedback mode used in each episode. To do that, we need to first create a so-called modifier file. Let's suppose we call the modifer bar, which means that the modifier file needs to be in an appropriately named file under the modifier directory, namely /opt/tomcat/game-data/modifiers/bar.csv. Since we only want to modifiy 2 parameters of the original static plan, the modifier file needs to contain 2 columns. The file will have a header line (with the names of the two parameters), followed by a data line with the values of those parameters.
After that, one can refer to the modifed plan under the name P:APP/foo:bar. When encountering this plan name, the Game Server will create, in the server memory, a plan consisting of the same number of trial lists as the original plan APP/foo did, but each of those trial lists will have new values in the 2 columns you wanted to modify; those values will, of course, be taken from the modifier file.
In another use case, an experiment designer may want create a single template trial list which will define all the parameters needed for running games (the number of pieces, colors and shapes, the number of episodes to play, reward rates, etc) except for the name of the rules, and then offer to players a number of plans based on this template trial list, but with different rule sets. This can be accomplished by placing that template file into the modifier directory (e.g. the file in /opt/tomcat/game-data/modifiers/my-template.csv. will define the template trial list named my-template). After that, to create a dynamic experiment plan that uses the rule set named my-rule (thus, defined by the rule set file in /opt/tomcat/game-data/rules/my-rule.csv) plus the parameters from the template file, one can refer to the dynamic plan by the name R:my-rule:my-template. The Game Server, again, will take the parameters from the modifier file and will put the rule name my-rule into the rule ID column of the trial list.
Since one only specifies a single rule in an R:-type plan, the template trial list should have only one data line (preceded, of course, by the header line), and the dynamic plan will have just one trial list, with a single parameter set in that list.
When you refer to dynamic plans, of either P: or R: variety, the server does not create new experiment plan directories; instead, the plan definitions only exist in the server's memory, created when you first refer to the plan. This is why we call such plans "dynamic".
A rule set defines in which way pieces can be moved from the board by the player. A rule set is described by a rule set file. To learn to read and write rule set files, see the rule set files syntax guide, and syntax of rule set files: GS5 extension.
When speaking precisely, we use the word game to refer to the combination of a rule set (which defines in which way pieces can be moved from the board) and an initial board. This is similar to how the word "game" may be used in other domains. For example, the expression "game of chess" means "a game which starts with a certain initial position (16 white and 16 black game pieces of certain kinds, arranged in a certain order in 4 rows of the board), and in which the players can move the game pieces according to certain specified rules". In our Rule Game, we can say "players A and B were given identical game to play", meaning that A and B were given the same initial boards and had to follow the same rules for removing pieces.
When the Game Server is given a parameter set (coming e.g. from a particular line of a trial list file), the Game Server internally creates a so-called "game generator": a machine which will create a series of games which will have various (randomly generated or predefined) initial boards and a certain rule set (the same for all games in the series).
A series consists of episodes. An episode is one instance of playing a game, from setting up an initial board to clearing it. In a given series, all episodes involve games with the same rule sets but, generally, different initial boards. An episode, therefore, can be represented by the initial board and the sequence of moves, together with a reference to the set of rule under which the episode was played.
See also Paul's document, _0.Terminology.
Normally, when a player is registered (which happens when an M-Turker follows a link from the M-Turk side, or when somebody uses a launch page), the name of the experiment plan is an explicit part of the start URL.
For historical purposes, we mention here a deprecated Game server feature that has remained since GS 1.*, and should not be used anymore. Namely, there is a procedure to assign a player to an experiment plan even if the plan name is not provided in the URL. It works as follows:
As stated above, player IDs normally don't have a connection with the experiment plan name, and, generally, can be picked freely if one comes from a non-registration launch page. However, certain conventions exist which allow one to guess, with a high probability, the origin of a particular player. In particular: