This document goes over the main concepts of Empirica.
A Game is a single run of the experiment. It is also used to describe the experiment that was developed.
Players are users participating in a Game. A game must have a least 1 Player.
A Batch is a set of 1 or more games that run in parallel. Batches allow to create different assignment methods (for player distribution). Batches are ran one at a time, in order of creation time. If you start multiple batches at once in the admin, only the first will accept players. Once full the next batch will automatically start receiving players.
A Game is made up of 1 or more ordered Rounds. A round contains 1 or more stages. Rounds are usually composed of the same stages and repeats over the course of the game.
E.g. For the guess the correlation experiment, on each round, we ask the player to guess the correlation between a graph and a numerical value. In the first stage of each round, it's the guess, the second stage the reveal of the result, and in the third stage we show what other players have guessed; all in the same round; and in the next round, we repeat those stages.
It is not required for all Round to contain the same stages or even the same number of stages.
Rounds do not have a name, they have an order number (1, 2, 3...)
A round may contain 1 or more stages. A stage has a duration, a name and a display name.
The name is the programatic reference that can later be used in the UI code to differentiate stages. The display name on the other hand is used in the UI, and it a clean human readable name. For example, a stage name might be "guess", while the display name might be "Guess A Number".
The stage duration is set in seconds, with a minimum of 5 seconds, and no maximum. You can also allow players to submit a stage, which marks it as done for the given player. When all players have submitted, the stage is considered done. If the stage timer runs out the stage is also considered done, whichever happens first.
If you do not want to have a timer and want to wait until players submit, you can set the timer to an unreasonable value (e.g. 30000000 ~= a year), and hide the timer in the UI.
Factors are essentially variables that will affect how a game will play. One
Factor Type is mandatory for any Empirica game, the
Factors are assembled into treatments, which are themselves assigned to games.
To create Factor Values, you must first create Factor Types. A Factor Type
describes the Factor. A _Factor Type) has a
type and a
namemust be a code-friendly name, such a
playerCount, which does not contain spaces or odd characters and is written in camelCase.
descriptionis a human readable description used in the admin UI to help other admins understand what this factor does.
- Finally, the
typeis a computing type (integer, string, ...) to limit what _Factor Values* can be created for this _Factor Type*.
- Factor Types can also be marked as
required, meaning they are required in all treatments.
A Treatment is a named set of Factors. Each factor can appear at most once in a treatment and required Factors must be present. The set of Factors in a treatment must be unique, no 2 treatment with the exact same set of factors can be created.
A Game Lobby is where the players wait for other players to arrive, and until the game starts.
The Game Lobby is configured by lobby configs for common scenarios. It contains a timer duration for the lobby, and handles the behavior of the app in case of timeouts.
The intro steps are pages shows to the user after registering and before the game or game lobby. These steps can be configured by the game designer to contain whatever is needed: intructions, a quizz, forms, etc.
The set of steps can be altered depending on the treatment assigned to the current player.
the exit steps are pages shown to the user after the game. They are configured by the experiment designer and may contain: results, reward instructions, quizz, thank you note...
The steps shown may be altered depending on any parameter of the player or the game (treatment, results, etc.)