Concepts
A Game is a single run of the experiment. It is also used to describe the experiment that was developed. One or more Players participate in a Game. A Game is divided in three main parts: Intro steps, Game, and Exit Steps.
The Intro Steps are when Players arrive in the game. They can read instructions, answer quizzes, etc. before arriving to the Lobby. The Intro Steps are asynchronous (each player completes these steps at their own pace). Once all the Players have reached the Lobby stage, the Game initialises. The Game part of the Game is composed of Rounds, which are themselves divided into Stages. Players must complete every stage of a Round before moving on to the next Round. The Game is synchronous (every player has to finish a stage before the can all move on to the next stage). Once every Round is complete, the Players will reach the Exit Steps where they can read a debrief, answer questionnaires, etc. The Exit Steps are asynchronous.
Players are users participating in a Game. A game must have a least 1 Player. Each Player entry in the database will contain information such as their last login, their unique ID, the ID of the Game they are participating in, which steps they have accomplished, and any other data you additionally assign to Players (e.g., an avatar to represent the 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: simple and complete. 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 programmatic reference that can later be used in the UI code to differentiate stages. The displayName 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
durationInSeconds 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.
The Rounds and Stages are synchronous (every player has to finish a stage before the can all move on to the next stage). The timer allows you to avoid one Player not responding and stopping the other Players from continuing because a new stage starts when the timer ends.
Factors are essentially variables that will affect how a game will play. One Factor Type is mandatory for any Empirica game, the
playerCount number.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
name, a description, a type and a required marker.- The
namemust be a code-friendly name, such aplayerCount, which does notcontain spaces or odd characters and is written in - The
descriptionis a human readable description used in the admin UI to helpother 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 inall treatments.
The Factors can then be accessed as a property of the Game. This can be used to represent different conditions. For example, say you want some Games to show information from the other Players' answers to each other and some Games not to. You can have a "socialInformation" factor set to "yes" and "no", and only show the information from other Players if
game.socialInformation == "yes" .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 two 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.
We are currently updating documentation for Empirica v2. This section's information here is incorrect. Lobby timeouts are not yet available in v2.
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. Such as whether it should try again or cancel the game once the timer runs out.
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: instructions, a quiz, forms, etc.
The set of steps can be altered depending on the treatment assigned to the current player or the treatments.
The Intro Steps are asynchronous (each player completes these steps at their own pace).
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, quiz, thank you note...
The steps shown may be altered depending on any parameter of the player or the game (treatment, results, etc.).
The Exit Steps are asynchronous (each player completes these steps at their own pace).