API

This document describes Empirica's server, client and shared APIs.
Server
Empirica.onGameStart(callback)
The onGameStart callback is called just before a game starts, when all players are ready, and it must create rounds and stages for the game.
One (and one only) onGameStart callback is required for Empirica to work.
The callback receives one argument, the game object, which gives access to the players and the treatment for this game.
It also offers the addRound() method, which allows to add a round to the game. The returned Round object will implement the addStage(stageArgs) method, which allows to add a Stage to the Round. The stageArgs object to be passed to the stage creation method must contain:
duration: the stage duration, in seconds
Note that the Game has not yet been created when the callback is called, and you do not have access to the other properties of the Game which will be created subsequently.
Example
Empirica.gameInit(game => {
  game.players.forEach((player, i) => {
    player.set("score", 0);
  });
​
  const round1 = game.addRound();
  round1.addStage({
    duration: 120
    name: "Response",
  });
​
  if (game.treatment.playerCount > 1) {
    round1.addStage({
      duration: 120
      name: "Result",
    });
  }
​
  const round2 = game.addRound();
  round1.addStage({
    duration: 300
    name: "Response",
    someotherfield: "mydata"
  });
​
  if (game.treatment.playerCount > 1) {
    round1.addStage({
      duration: 120
      name: "Result",
    });
  }
});
Game Callbacks
Game hooks are optional methods attached to various events throughout the game life cycle to update data on the server-side.
Contrary to client side data updates, sever-side updates are synchronous, there is no risk of conflicting updates, and important calculations can be taken at precise points along the game.
``
Empirica.onRoundStart(callback)
onRoundStart is triggered before each round starts, and before onStageStart. It receives the same options as onGameStart, and the round that is starting.
Example
Empirica.onRoundStart(({ round }) => {
  round.set("scoreToReach", round.game.get("maxScore"));
});
Empirica.onStageStart(callback)
onRoundStart is triggered before each stage starts. It receives the same options as onRoundStart, and the stage that is starting.
Example
Empirica.onStageStart(({ stage }) => {
  stage.set("randomColor", myRandomColorGenerator());
});
Empirica.onStageEnd(callback)
onStageEnd is triggered after each stage. It receives the current game, the current round, and stage that just ended.
Example
Empirica.onStageEnd(({ stage }) => {
  const expectedScore = stage.round.get("expectedScore");
  const group = stage.get("score") > expectedScore ? "great" : "not_great";
  stage.set("scoreGroup", group);
});
Empirica.onRoundEnd(callback)
onRoundEnd is triggered after each round. It receives the current game, and the round that just ended.
Example
Empirica.onRoundEnd(({ round }) => {
  let maxScore = 0;
  round.game.players.forEach((player) => {
    const playerScore = player.round.get("score") || 0;
    if (playerScore > maxScore) {
      maxScore = playerScore;
    }
  });
  round.set("maxScore", maxScore);
});
Empirica.onGameEnd(callback)
onGameEnd is triggered when the game ends. It receives the game that just ended.
Example
Empirica.onGameEnd(({ game }) => {
  let maxScore = 0;
  game.rounds.forEach((round) => {
    const roundMaxScore = round.get("maxScore") || 0;
    if (roundMaxScore > maxScore) {
      maxScore = roundMaxScore;
    }
  });
  game.set("maxScore", maxScore);
});
Client
See the Special Empirica Component page for more info.
Shared
We are currently updating documentation for Empirica v2. This section's information here is incorrect.
Game object
Property
Type
Description
index
Number
An auto-increment number assigned to each Game in order (1, 2, 3...)
treatment
Object (key: String, value: String or Integer)
An object representing the Factors set on this game, e.g. { "playerCount": 12 }.
players
Array of Player objects​
Players participating in this Game.
rounds
Array of Round objects​
On the server side, this will show every round that makes up the game. But on the client side, this will only show the current round.
createdAt
Date
Time at which the game was created which corresponds approximately to the time at which the Game started.
Round object
Property
Type
Description
index
Object
The 0 based position of the current round in the ordered list of rounds in a game.
stages
Array of Stage objects​
Stages composing this Round.
Stage object
Property
Type
Description
index
Object
The 0 based position of the current stage in the ordered list of a all of the game's stages.
name
String
Programmatic name of stage (i.e. to be used in code, e.g if (name === "outcome") ...).
displayName
String
Human name of stage (i.e. to be showed to the Player, e.g "Round Outcome").
duration
Integer
The stage duration, in seconds.
startTimeAt
Date
Time at which the stage started. (only set if stage has already started, i.e. not set in onStageStart).
Player object
Property
Type
Description
index
Number
An auto-increment number assigned to each Player in order (1, 2, 3...)
id
String
The ID the player used to register (e.g. MTurk ID).
urlParams
Object (key/value: String)
Parameters that were set on the URL when the user registered.
bot
String
Name of the bot used for this player, if the player is a bot (e.g. Alice).
readyAt
Date
Time at witch the player became ready (done with intro steps).
exitAt
Date
Time when the player exited the Game (whether the game ended normally or not, see exitStatus).
exitStatus
String
Status of the Player at Game exit.

Can be: "gameFull", "gameCancelled", "gameLobbyTimedOut", "playerEndedLobbyWait", "playerLobbyTimedOut", "finished". "finished" represent the normal exit.
online
Boolean
True if the player is currently online.
idle
Boolean
True if the player is currently online but idle. Idleness is defined as either the page not being active (on another tab/window) or not detecting any activity (mouse/keyboard) for more than 60s.
lastActivityAt
Date
Time when the player was last seen online and active (not idle). Server only (this is not accessible on the client at the moment).
lastLogin.at
Date
Time the player last come online (registered, reopened page and auto-login kicked in or re-entered player ID – if they were forgotten).
lastLogin.ip
String
​IP address of player on last connection.
lastLogin.userAgent
String
​User-Agent of player on last connection.
GameLobby object
Property
Type
Description
treatment
Object (key: String, value: String or Integer)
An object representing the Factors set on this game, e.g. { "playerCount": 12 }.
queuedCount
Integer
Total number of players queued for this game, including ready players and players currently going through the intro steps.

N.B.: There could be more players in queuedCount than specified by the playerCount Factor, as Empirica can sometimes overbook Games to shorten wait times.
Use gameLobby.treatment.playerCount to get the expected number of players.
readyCount
Integer
Number of players ready to play. They have completed the intro steps, and they are on the lobby page.

Property	Type	Description
`index`	Number	An auto-increment number assigned to each Game in order (1, 2, 3...)
`treatment`	Object (key: String, value: String or Integer)	An object representing the Factors set on this game, e.g. `{ "playerCount": 12 }`.
`players`	Array of Player objects	Players participating in this Game.
`rounds`	Array of Round objects	On the server side, this will show every round that makes up the game. But on the client side, this will only show the current round.
`createdAt`	Date	Time at which the game was created which corresponds approximately to the time at which the Game started.

Property	Type	Description
`index`	Object	The 0 based position of the current round in the ordered list of rounds in a game.
`stages`	Array of Stage objects	Stages composing this Round.

Property	Type	Description
`index`	Object	The 0 based position of the current stage in the ordered list of a all of the game's stages.
`name`	String	Programmatic name of stage (i.e. to be used in code, e.g `if (name === "outcome") ...`).
`displayName`	String	Human name of stage (i.e. to be showed to the Player, e.g "Round Outcome").
`duration`	Integer	The stage duration, in seconds.
`startTimeAt`	Date	Time at which the stage started. (only set if stage has already started, i.e. not set in `onStageStart`).

Property	Type	Description
`index`	Number	An auto-increment number assigned to each Player in order (1, 2, 3...)
`id`	String	The ID the player used to register (e.g. MTurk ID).
`urlParams`	Object (key/value: String)	Parameters that were set on the URL when the user registered.
`bot`	String	Name of the bot used for this player, if the player is a bot (e.g. `Alice`).
`readyAt`	Date	Time at witch the player became ready (done with intro steps).
`exitAt`	Date	Time when the player exited the Game (whether the game ended normally or not, see exitStatus).
`exitStatus`	String	Status of the Player at Game exit. Can be: "gameFull", "gameCancelled", "gameLobbyTimedOut", "playerEndedLobbyWait", "playerLobbyTimedOut", "finished". "finished" represent the normal exit.
`online`	Boolean	True if the player is currently online.
`idle`	Boolean	True if the player is currently online but idle. Idleness is defined as either the page not being active (on another tab/window) or not detecting any activity (mouse/keyboard) for more than 60s.
`lastActivityAt`	Date	Time when the player was last seen online and active (not idle). Server only (this is not accessible on the client at the moment).
`lastLogin.at`	Date	Time the player last come online (registered, reopened page and auto-login kicked in or re-entered player ID – if they were forgotten).
`lastLogin.ip`	String	IP address of player on last connection.
`lastLogin.userAgent`	String	User-Agent of player on last connection.

Property	Type	Description
`treatment`	Object (key: String, value: String or Integer)	An object representing the Factors set on this game, e.g. `{ "playerCount": 12 }`.
`queuedCount`	Integer	Total number of players queued for this game, including ready players and players currently going through the intro steps. N.B.: There could be more players in queuedCount than specified by the `playerCount` Factor, as Empirica can sometimes overbook Games to shorten wait times. Use `gameLobby.treatment.playerCount` to get the expected number of players.
`readyCount`	Integer	Number of players ready to play. They have completed the intro steps, and they are on the lobby page.

Last modified 2mo ago

API

Server

`Empirica.onGameStart(callback)`

Example

Game Callbacks

`Empirica.onRoundStart(callback)`

Example

`Empirica.onStageStart(callback)`

Example

`Empirica.onStageEnd(callback)`

Example

`Empirica.onRoundEnd(callback)`

Example

`Empirica.onGameEnd(callback)`

Example

Client

Shared

`Game` object

`Round` object

`Stage` object

`Player` object

`GameLobby` object