Skip to main content

multiplayer-choice

A choice trial is a simultaneous decision. Every participant picks one of the same options without seeing anyone else's pick; once the whole group has chosen, the trial shows the outcome. Use it for simultaneous-move games (prisoner's dilemma, coordination, public goods with a few contribution levels) and for group votes.

The outcome screen either lists who chose what, or shows only the count for each option and the winner, as an anonymous poll. An optional payoff function scores the round for each participant.

What the participant sees: your prompt and one button per option. After a click, the buttons dim and "Waiting for the other players to choose…" appears until the group has chosen. Then the outcome screen, with a Continue button.

timeline.push({
type: jsPsychMultiplayerChoice,
choices: ["Cooperate", "Defect"],
expected_players: 2,
});
Package@jspsych-multiplayer/plugin-multiplayer-choice
Browser globaljsPsychMultiplayerChoice
Trial typemultiplayer-choice
Requiresa connected session (see Getting started)

Parameters​

ParameterTypeDefaultDescription
choicesstring[]requiredThe options, one button each. HTML is allowed. The option's index (from 0) is what is shared with the group.
promptHTML stringnullShown above the buttons.
button_html(choice, index) => stringnullReturns the HTML for each option, as in html-button-response. null uses a plain jspsych-btn button.
expected_playersnumber | nullnullHow many participants, including this one, must choose before the outcome is shown. Can be a function that returns the number. null means everyone in a sealed group who hasn't left; if the group isn't sealed when the trial starts, you must set it.
waiting_messageHTML string"<p>Waiting for the other players to choose…</p>"Shown after this participant chooses, while the rest of the group finishes.
timeoutnumber | nullnullThe longest time to wait for the others after choosing, in ms. When it runs out, the trial goes on with whoever has chosen, with multiplayer_outcome: "timeout", and on_timeout is called. null, 0, or a negative number waits indefinitely. It does not limit how long this participant takes to choose.
on_timeoutfunction | nullnullCalled with the timeout error if timeout runs out first.
participantsstring[] | nullnullThe participants this choice depends on. If one of them leaves before the group has chosen, the trial goes on with whoever has chosen, with multiplayer_outcome: "participant_left". null means the other members of a sealed group who haven't left, or, without a sealed group, every other participant who is connected when this participant chooses. [] ignores departures.
revealbooleantrueShow the outcome screen. false ends the trial as soon as the group has chosen.
reveal_mode"players" | "tally""players""players" lists each participant's choice by name. "tally" shows only the count for each option and the winner (or a tie), never who chose what.
reveal_promptHTML stringnullA heading above the outcome.
continue_labelstring | null"Continue"The label of the button that ends the outcome screen. null hides the button; then set reveal_duration, or the screen can't end.
reveal_durationnumber | nullnullEnd the outcome screen automatically after this many ms. With a button as well, whichever comes first ends it.
player_label(participantId) => stringnullThe name to show for each participant in "players" mode. null shows participant IDs.
payoff(choices, me) => numbernullComputes this participant's payoff. choices is { participantId: { index, label } } and me is this participant's ID. The result is saved as my_payoff and shown on the outcome screen.
record_choices_by_playerbooleantrueSave everyone's choice as choices_by_player. Set false for an anonymous poll; see Anonymous polls.

Data​

FieldTypeDescription
choicestringThe label of this participant's choice.
choice_indexnumberThe index of this participant's choice, from 0.
rtnumberMilliseconds from the buttons appearing to this participant's click.
wait_timenumberMilliseconds from the click until the group had chosen (or the wait ended early). Does not include the outcome screen.
choices_by_playerobject | nullEveryone's choice, { participantId: { index, label } }. null when record_choices_by_player is false.
n_playersnumberHow many choices were counted.
tallyobject[]One { index, label, count } per option, in choices order.
winnerobject | nullThe option with the most picks, { index, label, count }. null on a tie or if no one chose.
is_tiebooleantrue if two or more options shared the most picks.
tied_optionsobject[]The options that tied, in choices order. Empty if there was no tie.
my_payoffnumber | nullThe value payoff returned. null without a payoff function, or if it threw or didn't return a finite number.
multiplayer_outcomestringHow the wait ended: "completed" (everyone chose), "timeout", "participant_left" (a participant in participants left), or "connection_lost" (this participant's own connection was lost for good). On any outcome but "completed", the trial goes on with whoever chose so far.
left_participantstring | nullThe ID of the participant who left, when multiplayer_outcome is "participant_left".

When the wait ends early, the trial still shows and records the outcome among those who did choose. Check multiplayer_outcome in on_finish; Handling dropouts has patterns for that. The counts include a choice from a participant who chose and then left. If the experiment ends or is aborted while the trial is waiting, it stops quietly: on_timeout isn't called and no data is recorded.

Each trial has its own shared data​

When a participant chooses, the plugin merges { choice: { index, label } } into their part of the trial's shared data. The trial counts participants who have a valid choice there and have not left the session.

Each trial has its own part of the shared data, so a choice made in an earlier trial can never count toward a later one. Participants running the same timeline share each trial's data, because it is named by the trial's position in the timeline (see How it works). To use a round's result later, read it from the trial's jsPsych data (choices_by_player, winner, …).

Set the trial's multiplayer_scope parameter when several sub-groups choose separately in one session. Give each sub-group its own name and set expected_players to the sub-group's size; multiplayer-match shows this for pairs. The name is used exactly as written, so a trial that repeats needs a name that changes with each repetition.

Anonymous polls​

With reveal_mode: "tally", the outcome screen shows a bar for each option with its count, the winner or the tie, and "(you)" next to this participant's own pick. Add record_choices_by_player: false to leave the per-participant choices out of the data as well; the data then holds the tally, the winner, and this participant's own choice.

This hides choices on screen and in your data, not in the session. Each participant's pick is still in their part of the trial's shared data, and a participant who inspects the page's network traffic can see it.

Example​

A one-shot prisoner's dilemma with payoffs, followed by an anonymous vote:

const PAYOFFS = [
[3, 0], // I cooperate: they cooperate, they defect
[5, 1], // I defect: they cooperate, they defect
];

const dilemma = {
type: jsPsychMultiplayerChoice,
prompt: "<p>You and your partner choose at the same time.</p>",
choices: ["Cooperate", "Defect"],
expected_players: 2,
timeout: 60000,
reveal_prompt: "<h3>Both players have chosen</h3>",
player_label: (id) => (id === jsPsych.multiplayer.participantId ? "You" : "Your partner"),
payoff: (choices, me) => {
// Find the other player's ID
let other;
for (const id in choices) {
if (id !== me) {
other = id;
break;
}
}
return PAYOFFS[choices[me].index][choices[other].index];
},
};

const vote = {
type: jsPsychMultiplayerChoice,
prompt: "<p>Which game should the group play next?</p>",
choices: ["Trust", "Ultimatum", "Public goods"],
expected_players: 4,
reveal_mode: "tally",
record_choices_by_player: false,
reveal_prompt: "<h3>The votes are in</h3>",
on_finish: (data) => {
nextGame = data.winner ? data.winner.label : "Public goods"; // winner is null on a tie
},
};

If the partner times out, choices[other] is missing, payoff throws, and my_payoff is recorded as null.