Skip to main content

multiplayer-reference-game

A reference game trial is one round of the repeated reference game ("tangrams") of Hawkins, Frank & Goodman (2020). Two players, a director and a matcher, see the same set of objects, each in a different arrangement, so they can't refer to objects by position. Only the director sees which objects are the targets. The players talk in a chat panel, the matcher picks out the targets, and both see how they did. Run it over many rounds and you can measure how partners come to agree on short names for hard-to-describe objects.

The number of targets sets the task. With one target, the matcher clicks one object (the "sequential" condition of the original study). With every object a target, the matcher puts the whole board in the director's order (the "unconstrained" condition). Any number in between also works.

What the participant sees: your prompt, "You are the Director." or "You are the Matcher.", a grid of objects, a line of instructions, and the chat panel. The director's targets are outlined, and numbered when there is more than one. With more than one target, the matcher sees a row of numbered slots: they click a slot, then the object for it, and click Submit when every slot is filled. With one target, a click is the answer. After the matcher answers, both players see the targets, the matcher's choices marked right or wrong, and the score, for three seconds.

timeline.push({
type: jsPsychMultiplayerReferenceGame,
stimuli: SHAPES, // [{ id: "a", src: "img/a.png" }, …]
targets: ["c"],
role: () => jsPsychMultiplayerRole.getMyRole(),
round: 0,
round_timeout: 60000,
});
Package@jspsych-multiplayer/plugin-multiplayer-reference-game
Browser globaljsPsychMultiplayerReferenceGame
Trial typemultiplayer-reference-game
Requiresa connected session (see Getting started) and a role for each player, usually from multiplayer-role

Parameters​

stimuli, targets, role, and round are required. The trial throws an error if one is missing, if two stimuli share an id, or if a target isn't one of the stimuli.

In the tables below, k is the number of targets.

Objects and layout​

ParameterTypeDefaultDescription
stimuliobject[]requiredThe objects, as { id, src?, html?, label? }. Each id must be unique. src is an image URL; html is inline HTML, such as an SVG; otherwise label (or the id) is shown as text. Every object is on screen.
columnsnumber6How many columns the grid has. Ignored when rows is set.
rowsnumber | nullnullHow many rows the grid has. The number of columns is then worked out from it. null uses columns.
cell_sizenumber | nullnullThe width of each grid column, in pixels. null lets each be between 3 and 6 em wide.
scramble_modestring"independent"How the two players' arrangements relate: "independent" (different random arrangements), "disjoint" (different, and no object is in the same place for both, as in the original study; needs at least 2 objects), "shared" (the same arrangement for both), or "matcher_only" (the director sees stimuli in the order given; the matcher's is shuffled).
seedstring | nullnullPicks different arrangements within the session. Randomness is seeded by the session ID (or the randomSeed connect option), so each group gets its own arrangements.
show_labelsbooleanfalseShow each object's label (or id) under it.

Targets and scoring​

ParameterTypeDefaultDescription
targetsstring[]requiredThe ids of the target objects, in order.
orderedboolean | nullnullWhether the matcher must put the targets in the right slots (true) or only pick the right objects (false). null means true when k > 1.
scoringstring | function"per_slot"How n_correct is counted: "per_slot" (one per correct slot), "all_or_nothing" (k if every slot is right, else 0), or your own (assignment, targets) => number, whose result is rounded and kept between 0 and k.

Roles​

ParameterTypeDefaultDescription
rolestringrequiredThis participant's role: "director" or "matcher". Usually () => jsPsychMultiplayerRole.getMyRole().
role_labelsobject{ director: "Director", matcher: "Matcher" }The names used for the two roles on screen.
director_can_selectbooleanfalseLet the director click objects to highlight them for themselves. The highlight is not sent or scored.
reveal_target_tostring"director"Who sees the targets outlined before the answer: "director", "matcher", "both", or "none".

Chat​

ParameterTypeDefaultDescription
chat_enabledbooleantrueShow the chat panel.
chat_rolestring"both"Who can send messages: "director", "matcher", or "both". Both can always read.
max_messagesnumber | nullnullThe most messages this participant can send in the round. null means no limit.
max_lengthnumber | nullnullThe longest a message can be, in characters. Longer messages are cut when sent. null means no limit.
require_message_before_responsebooleanfalseIgnore the matcher's clicks until the director has sent a message this round, as in the original study's Experiment 2. Ignored clicks are shown a hint and recorded as gated_click in interaction_history. Has no effect when chat_enabled is false.
placeholderstring"Type a message…"Placeholder text in the empty text box.
chat_persistsbooleanfalseKeep one conversation across rounds: the log is kept in the session scope and shared by every reference-game trial with chat_persists on. false starts each round with an empty chat.
chat_positionstring"below"Where the chat panel goes: "below" or "beside" the grid.
typing_indicatorbooleanfalseShow "Matcher is typing…" (or "Director is typing…") while the partner types. It is only a hint: it never holds up the trial, and it is hidden while the partner is away or has left.
typing_ttlnumber2500How long the typing hint stays up after the partner's last keystroke, in ms.
typing_throttlenumber800While typing, send at most one update per this many ms.
typing_labelstring | nullnullThe typing hint's text. null uses the partner's role label, e.g. "Matcher is typing…".

Answering​

ParameterTypeDefaultDescription
response_modestring | nullnull"click" (one click is the answer) or "assign_slots" (numbered slots). null means "click" when k = 1 and "assign_slots" otherwise.
auto_submitboolean | nullnullSend the answer as soon as every slot is filled, without a Submit button. null means true when k = 1.
submit_labelstring"Submit"The label of the Submit button.
allow_changebooleantrueLet the matcher change a choice before submitting.
selection_timeoutnumber | nullnullThe matcher's time limit, in ms. When it runs out, whatever they have chosen so far is submitted and scored, and the round ends with multiplayer_outcome: "timeout". It keeps running while the matcher waits for a message under require_message_before_response.

Feedback​

ParameterTypeDefaultDescription
feedbackbooleantrueShow feedback after the matcher answers. false ends the trial as soon as the answer arrives.
feedback_contentobject{ reveal_target: true, show_score: true, show_partner_choice: true }What feedback shows: the targets, the score, and the matcher's choices. To show the two players different things, key it by role: { director: {…}, matcher: {…} }. Missing entries are true.
feedback_tostring"both"Who sees feedback: "director", "matcher", or "both".
feedback_durationnumber | null3000How long feedback stays up, in ms. null shows a Continue button instead.
show_running_scorebooleanfalseAdd a running total to the score line: this round's n_correct plus the n_correct of this participant's earlier reference-game trials in the jsPsych data.

Rounds, timing, and data​

ParameterTypeDefaultDescription
promptHTML string or (role) => string""Shown above the board. A function receives this participant's role, so the two players can get different instructions.
roundnumberrequiredThe round number. Must be different for every round in the experiment (see Rounds). Usually jsPsych.timelineVariable("round").
partner_idstring | nullnullThe partner's participant ID. null finds the one other participant: the other member of a sealed group, or else the other connected participant. Set it when the session can hold more than two people.
round_timeoutnumber | nullnullThe longest the round can last before feedback, in ms. When it runs out, the round ends with multiplayer_outcome: "timeout" and no answer. If neither this nor selection_timeout is set, a warning is logged: a partner who stays connected but never acts would leave the trial waiting forever.
end_on_participant_leftbooleantrueEnd the round, with no answer, if the partner leaves before feedback.
save_ordersbooleantrueSave both players' arrangements in my_order and partner_order.
save_transcriptbooleantrueSave the chat in chat_transcript.
save_interaction_historybooleanfalseSave every choice the matcher made before submitting in interaction_history.
save_groupbooleanfalseSave this round's shared data, as it was at the end of the trial, in group.

Data​

Both players get a row for each round. Fields about the answer are null if the round ended without one.

FieldTypeDescription
rolestring"director" or "matcher".
roundnumberThe round number.
targetsstring[]The target ids, in order.
assignmentstring | object | nullThe matcher's answer. With one target, the id they clicked. With more, an object from slot number (starting at 1) to id, e.g. { "1": "c", "2": "a" }.
n_correctnumber | nullThe score, counted as scoring says.
n_targetsnumberk, the number of targets.
accuracynumber | nulln_correct / n_targets.
correctboolean | nulltrue if every slot was right, whatever scoring says.
rtnumber | nullFor the matcher, ms from the start of the trial to the answer. null for the director.
chat_transcriptobject[]The round's chat, as { id, senderId, seq, text, ts, round } messages. Only when save_transcript is true.
message_countnumberHow many messages are in the chat.
messages_sentnumberHow many of them this participant sent.
my_orderstring[]The ids in the order this participant saw them, row by row. Only when save_orders is true.
partner_orderstring[] | nullThe same for the partner. null if the partner was never found. Only when save_orders is true.
interaction_historyobject[]The matcher's choices before submitting, as { t, action, slot, object_id }. t is ms from the start of the trial; action is "assign", "reassign", "clear", or "gated_click". Only for the matcher, and only when save_interaction_history is true.
multiplayer_outcomestringHow the round ended: "completed" (the matcher answered), "timeout" (see below), "participant_left" (the partner left the study), "connection_lost" (this participant's connection was lost for good), or "cancelled" (the experiment called jsPsych.multiplayer.disconnect() during the round).
left_participantstring | nullThe partner's ID, when multiplayer_outcome is "participant_left".
groupobjectEvery participant's shared data for this round. Only when save_group is true.

multiplayer_outcome: "timeout" has two cases. If selection_timeout ran out, the matcher's partial answer was scored and feedback was shown, so assignment and n_correct are filled in. If round_timeout ran out, there is no answer.

Handling dropouts explains multiplayer_outcome and left_participant, and how to branch on them.

Rounds​

Put one trial per round in a timeline with timeline_variables, and give each round its own round number. The round number picks the arrangements, is recorded in the data, and is stamped on chat messages.

Each round's shared data (the matcher's answer, the chat, and the typing indicator) lives in the round's own trial scope, so rounds never see each other's answers, even when the same trial runs again through timeline_variables. Don't give rounds a shared multiplayer_scope: the trial throws an error if its scope already holds this participant's answer. With chat_persists, the chat is kept in the session scope instead, so it carries across rounds; the round stamped on each message tells this round's messages from earlier ones.

Arrangements are shuffled again every round. They depend only on the session ID (or the randomSeed connect option), seed, the round number, and the two participant IDs, so each group gets its own arrangements and each player's data can record the partner's arrangement too.

With the default feedback settings, both players' trials end together: when the matcher answers, the director's screen shows the feedback at the same moment, and both end feedback_duration later.

When the partner leaves or goes quiet​

If the partner leaves before feedback, the round ends for this participant with multiplayer_outcome: "participant_left", their ID in left_participant, and no answer. An answer that arrived before they left is still scored. Once feedback is showing, a departure changes nothing. Set end_on_participant_left: false to rely on round_timeout instead.

If this participant's own connection is lost for good, the round ends with multiplayer_outcome: "connection_lost".

A partner who stays connected but stops responding does not end the round. Set round_timeout so the round can't wait forever, and skip the remaining rounds once a partner is gone, as in the example below.

Example​

A six-round game with one target per round. A multiplayer-role trial assigns the roles, and the remaining rounds are skipped if the partner leaves:

let partnerId;
let partnerGone = false;

const roleTrial = {
type: jsPsychMultiplayerRole,
roles: ["director", "matcher"],
group_size: 2,
on_finish: () => {
// Your partner holds the other role
let partnerRole = "director";
if (jsPsychMultiplayerRole.getMyRole() === "director") {
partnerRole = "matcher";
}
// participantsByRole() maps each role to a list of IDs; a role nobody got has no list
const byRole = jsPsychMultiplayerRole.participantsByRole();
if (byRole[partnerRole] !== undefined) {
partnerId = byRole[partnerRole][0];
}
},
};

const gameRound = {
type: jsPsychMultiplayerReferenceGame,
stimuli: SHAPES, // [{ id: "poly3", html: "<svg>…</svg>" }, …]
targets: jsPsych.timelineVariable("targets"),
round: jsPsych.timelineVariable("round"),
role: () => jsPsychMultiplayerRole.getMyRole(),
partner_id: () => partnerId,
scramble_mode: "disjoint",
require_message_before_response: true,
show_running_score: true,
round_timeout: 90000,
prompt: (role) =>
role === "director"
? "<p>Describe the outlined shape so your partner can find it.</p>"
: "<p>Click the shape your partner describes.</p>",
on_finish: (data) => {
if (
data.multiplayer_outcome === "participant_left" ||
data.multiplayer_outcome === "connection_lost"
) {
partnerGone = true;
}
},
};

const game = {
timeline: [{ timeline: [gameRound], conditional_function: () => !partnerGone }],
timeline_variables: [
{ round: 0, targets: ["star5"] },
{ round: 1, targets: ["poly3"] },
{ round: 2, targets: ["star5"] },
{ round: 3, targets: ["poly7"] },
{ round: 4, targets: ["star8"] },
{ round: 5, targets: ["poly3"] },
],
};

timeline.push(roleTrial, game);

For the full-board version, give every round all the object ids as targets, in a different order each round. The matcher then fills one slot per object and clicks Submit, and the score is out of the number of objects.