Skip to main content

adapter-multiplayer-jatos

The JATOS adapter runs your experiment as a JATOS group study. JATOS puts participants into groups, and the adapter shares data among the members of each group through JATOS's group session. Use it to collect data on a JATOS server your lab runs or has access to.

The experiment must run inside JATOS. Creating the adapter anywhere else throws an error. To build and test without a server, use adapter-multiplayer-local, then swap in this adapter. See Choosing a backend.

jatos.onLoad(async () => {
const jsPsych = initJsPsych({
on_finish: () => jatos.endStudy(jsPsych.data.get().json()),
});
await jsPsych.multiplayer.connect(new jsPsychAdapterMultiplayerJatos());
await jsPsych.run(timeline);
});
Package@jspsych-multiplayer/adapter-multiplayer-jatos
Browser globaljsPsychAdapterMultiplayerJatos
Use it forData collection on a JATOS server.

Options​

Pass these to the constructor, for example new jsPsychAdapterMultiplayerJatos({ sealWhenFull: false }). All are optional.

OptionTypeDefaultDescription
sealWhenFullbooleantrueFix the JATOS group (jatos.setGroupFixed()) once it has the batch's Max active members, so nobody new can join it. Set false to decide when yourself, with jsPsych.multiplayer.sealGroup(). See Forming groups.

How long to wait for the group connection to open, and when to give up on a connection that stays down, are options of jsPsych.multiplayer.connect() itself:

await jsPsych.multiplayer.connect(new jsPsychAdapterMultiplayerJatos(), {
connectTimeout: 10000, // default 20000
reconnectTimeout: 5 * 60000, // default: never give up
});

Options that changed in 1.0 are listed in Upgrading from 0.x. The adapter warns about, and ignores, the timeout options it used to have.

Each participant's ID is their JATOS study result ID, as a string. Once connect() resolves, it is in jsPsych.multiplayer.participantId.

Setup​

In your experiment's HTML​

  1. Load jatos.js first. JATOS provides this file itself; you do not copy it anywhere. Add <script src="jatos.js"></script> to the page's <head>, before the other scripts.
  2. Start inside jatos.onLoad(). Put the whole experiment, including initJsPsych() and connect(), in the function you pass to jatos.onLoad(), as in the snippet above.
  3. Save the data with jatos.endStudy(). Call it from initJsPsych's on_finish with jsPsych.data.get().json(). The adapter shares data among the group but does not save your trial data.

In JATOS​

  1. Create the study and add the files. Put your HTML file and every script it loads in the study's assets folder, and make the HTML file the study's component. JATOS serves only what is in that folder, so download the jsPsych and multiplayer scripts rather than loading them from a CDN if your participants' network might block one.

  2. Turn on "Group study" in the study's properties.

  3. Set the group size in the batch properties (under Study Links). JATOS puts each arriving participant into a group in that batch that still has room, and starts a new group when none does:

    • Max active members is how many participants a group can hold at once. Set it to your group size, for example 2 for a two-player game, to get separate groups of that size.
    • Max total members is how many participants can ever join a group, counting those who left. You can usually leave it empty: once a group is full, the adapter fixes it, so nobody takes over a departed player's place (see Forming groups).

    With no limits, everyone in the batch joins one group. That is useful when the experiment itself decides who plays, for example with the overflow role of multiplayer-role.

To test, open the study link in two different browsers, or in a normal window and a private window, so that each run is a separate participant.

Trying the ultimatum example​

The repository builds its ultimatum game example into a file JATOS can import. From a copy of the repository, run npm install, npm run build, then npm run build:jatos:ultimatum. Import the resulting dist/ultimatum-jatos.jzip with JATOS's Import Study button. It is already marked as a group study, and its batch has no group-size limits.

How much data fits​

The whole group's data is stored together in one JATOS group session, and every write sends it. Its size limit is set in the JATOS server's configuration, so ask your JATOS administrator. See How much data you can share.

Session ID​

The adapter reports the JATOS group result ID as the session ID. Every member of a JATOS group shares it, so each group gets its own shared random values.

Forming groups​

Everyone opens the same study link, and JATOS puts each arriving participant into a group that still has room. The Forming groups guide explains the idea; this section covers what is specific to JATOS. connect() resolves as soon as the participant has a group, which is usually before the group is full, so start the experiment with a waiting room:

await jsPsych.multiplayer.connect(new jsPsychAdapterMultiplayerJatos());

const waitingRoom = {
type: jsPsychCallFunction,
async: true,
func: (done) => {
jsPsych.getDisplayElement().innerHTML = "<p>Waiting for the other players to arrive...</p>";
jsPsych.multiplayer
.waitForGroup({ timeout: 5 * 60000 })
.then((group) => done({ group_members: group.members }))
.catch(() => {
// The group didn't fill in time
jatos.endStudy(jsPsych.data.get().json(), false, "group did not fill");
});
},
};

While the group is forming, a participant who leaves frees their place, and JATOS can give it to the next arrival. Once the group has Max active members, the adapter asks JATOS to fix it (jatos.setGroupFixed()). From then on nobody new can join, jsPsych.multiplayer.group() reports the final roster, and a member who leaves counts as a dropout.

  • Size. group().size is the batch's Max active members, or null if it has none. With no limit the group is never fixed automatically.
  • Starting early. To start with fewer players, for example when the waiting room times out with enough people present, call jsPsych.multiplayer.sealGroup(). It fixes the group with the members it has. If the page's jatos.js is too old to fix groups, sealGroup() fails with an unsupported error.
  • Every member learns of the seal. JATOS confirms a fix only to the member who asked for it. So that member writes the final roster into the group session, and every other member reads it from there and reports the group as sealed. Members who drop out after the seal stay on the roster. The roster is stored under the key $sealed, which getAll() leaves out.
  • Checking the roster. Before believing a roster, each member checks that it is consistent with what JATOS reports: the writer and the reader are on it, and so is everyone JATOS lists as a member right now. A roster that fails these checks is ignored with a warning in the console. The checks catch mistakes, not deliberate forgery: JATOS lets any member write anywhere in the group session, so a participant who modifies the experiment's code could also overwrite others' data.

Presence and dropouts​

The adapter counts a participant as connected while their JATOS group connection is open.

  • Another participant closes the tab or leaves the study. JATOS tells the rest of the group as soon as the connection closes. That participant becomes away, then left after the dropout timeout (10 seconds by default, set in connect()).
  • Another participant loses their network. They become away once the JATOS server notices their connection is gone, then left after the dropout timeout.
  • This participant loses their network. jatos.js keeps trying to reconnect, and the connection status is reconnecting. This participant's reads keep returning the last data they saw, and their latest data is sent when the connection returns. The adapter keeps waiting for as long as it takes, so a participant who comes back before the others' dropout timeout rejoins: the others see them as connected again. One who comes back later stays left for the others, because left is final. To give up instead, pass reconnectTimeout to connect(): once the connection has been down that long, it counts as lost, and waiting trials end with multiplayer_outcome: "connection_lost". Set it also if your JATOS server may close a participant's group channel for good, because jatos.js does not reopen a channel the server closed.
  • A participant reloads the study page. Their experiment started over, so they can't rejoin. The others count them as left, and on the reloaded page jsPsych.multiplayer.restarted is true (see Rejoining).
  • jsPsych.multiplayer.disconnect() leaves the JATOS group. The others see this participant become away, then left. Calling connect() again on the same page joins a group again, but JATOS chooses which one, so it may not be the same group.

A participant's data stays in the group session after they leave. See Handling dropouts for what each plugin records.

Only one connection per page is possible. connect() fails if another is already open. After disconnect(), a new connect() waits for the old connection to finish leaving the group.

Example​

The top of the ultimatum game, which runs as a JATOS group study. The lobby waits for two connected players, then multiplayer-role assigns proposer and responder. The ultimatum game guide builds the rest.

<!DOCTYPE html>
<html>
<head>
<script src="jatos.js"></script>
<!-- a jsPsych build with jsPsych.multiplayer; see Getting started -->
<script src="jspsych.js"></script>
<script src="plugin-html-keyboard-response.js"></script>
<script src="adapter-multiplayer-jatos.js"></script>
<script src="plugin-multiplayer-role.js"></script>
<script src="plugin-multiplayer-sync.js"></script>
<link rel="stylesheet" href="jspsych.css" />
</head>
<body></body>
<script>
jatos.onLoad(async () => {
const jsPsych = initJsPsych({
on_finish: () => jatos.endStudy(jsPsych.data.get().json()),
});

await jsPsych.multiplayer.connect(new jsPsychAdapterMultiplayerJatos());

const lobby = {
type: jsPsychMultiplayerSync,
participants: [],
wait_for: (group, presence) => {
// Count the participants who are currently connected
let connected = 0;
for (const id in presence) {
if (presence[id] === "connected") {
connected++;
}
}
return connected >= 2;
},
message: "<p>Waiting for another player to join...</p>",
};

const assignRoles = {
type: jsPsychMultiplayerRole,
roles: ["proposer", "responder"],
strategy: "join_order",
overflow_role: "spectator",
message: "<p>Assigning roles...</p>",
};

const showRole = {
type: jsPsychHtmlKeyboardResponse,
stimulus: () => `<p>You are the <strong>${jsPsychMultiplayerRole.getMyRole()}</strong>.</p>`,
choices: [" "],
};

await jsPsych.run([lobby, assignRoles, showRole]);
});
</script>
</html>