API
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.
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 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.
``
onRoundStart is triggered before each round starts, and before onStageStart. It receives the same options as onGameStart, and the round that is starting.Empirica.onRoundStart(({ round }) => {
round.set("scoreToReach", round.game.get("maxScore"));
});
onRoundStart is triggered before each stage starts. It receives the same options as onRoundStart, and the stage that is starting.Empirica.onStageStart(({ stage }) => {
stage.set("randomColor", myRandomColorGenerator());
});
Empirica.onStageEnd(({ stage }) => {
const expectedScore = stage.round.get("expectedScore");
const group = stage.get("score") > expectedScore ? "great" : "not_great";
stage.set("scoreGroup", group);
});
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);
});
onGameEnd is triggered when the game ends. It receives the game that just ended.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);
});
Property | Type | Description |
|---|---|---|
players | Players participating in this Game. | |
rounds | This will return every round that makes up the game. | |
stages | This will return every stage that makes up the game. | |
currentRound | The current Round. | |
currentStage | The current Stage. |
Property | Type | Description |
|---|---|---|
stages | Stages composing this Round. | |
currentGame | Game this round is a part of. |
Property | Type | Description | Select |
|---|---|---|---|
round | Round this stage is a part of. | ||
currentGame | Game this stage is a part of. |
Property | Type | Description |
|---|---|---|
id | String | The ID the player used to register (e.g. MTurk ID). |
currentRound | Round the player is currently in. | |
currentStage | Stage the player is currently in. |
Last modified 6d ago