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.currentGame.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.onStageEnded(callback)

onStageEnded is triggered after each stage. It receives the current game, the current round, and stage that just ended.

Example

Empirica.onStageEnded(({ stage }) => {
  const expectedScore = stage.round.get("expectedScore");
  const group = stage.get("score") > expectedScore ? "great" : "not_great";
  stage.set("scoreGroup", group);
});

Empirica.onRoundEnded(callback)

onRoundEnded is triggered after each round. It receives the current game, and the round that just ended.

Example

Empirica.onRoundEnded(({ round }) => {
  let maxScore = 0;
  round.currentGame.players.forEach((player) => {
    const playerScore = player.round.get("score") || 0;
    if (playerScore > maxScore) {
      maxScore = playerScore;
    }
  });
  round.set("maxScore", maxScore);
});

Empirica.onGameEnded(callback)

onGameEnded is triggered when the game ends. It receives the game that just ended.

Example

Empirica.onGameEnded(({ game }) => {
  let maxScore = 0;
  game.rounds.forEach((round) => {
    const roundMaxScore = round.get("maxScore") || 0;
    if (roundMaxScore > maxScore) {
      maxScore = roundMaxScore;
    }
  });
  game.set("maxScore", maxScore);
});

Empirica.on(model, callback)

on(model, callback) listens to the creation of new mode objects. Model objects are the "game", "round", "stage", "player" and "batch". The callback receives a ctx object, and the model object listened to. In the example below, we're listening to new games, so we receive the game as argument.

Empirica.on("game", (ctx, { game }) => {
  if (game.get("initCalc")) return;
  
  game.set("initCalc", initCalcs());
});

Beware, Empirica.on(model, callback)is called on new objects and when the server restarts (when you run empirica or the server restarts after a code change in development mode). You should add a check such as the one in the example above, where we check if initCalc was already set at the top of the callback.

Empirica.on(model, attributeName, callback)

on(model, attributeName, callback) listens on changes to the attribute of attributeName on model. Model objects are the "game", "round", "stage", "player" and "batch". The callback receives a ctx object, the model object, and the attribute value. In the example below, we're listening on changes to choice on the player model.

Empirica.on("player", "choice", (ctx, { player, choice }) => {
  if (choice === "yes") {
    // ...
  }
});

We recommend using the value of the attribute given on the callback argument instead of doing .get(attributeName) on the model object as the value could have changed changed asynchronously.

Server Objects

Game object

Property	Type	Description
players	Array of Player objects	Players participating in this Game.
rounds	Array of Round objects	This will return every round that makes up the game.
stages	Array of Stage objects	This will return every stage that makes up the game.
currentRound	Round object	The current Round.
currentStage	Stage object	The current Stage.

Round object

Property	Type	Description
stages	Array of Stage objects	Stages composing this Round.
currentGame	Game object	Game this round is a part of.

Stage object

Property	Type	Description
round	Round object	Round this stage is a part of.
currentGame	Game object	Game this stage is a part of.

Player object

Property	Type	Description
id	String	The ID the player used to register (e.g. MTurk ID).
currentRound	Round object	Round the player is currently in.
currentStage	Stage object	Stage the player is currently in.
currentGame	Game object	Game the player is currently in.

Client

See the Special Empirica Component page for more info.