Skip to main content

multiplayer-draw

A draw trial gives the group one canvas to draw on together. Each stroke appears on everyone's screen while it is being drawn, and each participant's data gets every stroke as a list of points. Use it for collaborative sketching, drawing-based communication games, or any task where you want to record how people build a picture together.

Like multiplayer-chat, the trial stays open until one of the end conditions you set is met: a time limit (duration), a button (end_button_label), or a condition over the group's shared data (end_when). Set at least one; with none, the trial cannot end and the plugin logs a warning.

What the participant sees: your prompt, a toolbar, and the canvas. The toolbar has a row of color swatches, a set of brush sizes, and Pen, Eraser, Undo, and Redo buttons. Picking a color switches back to the pen. Undo and Redo only ever affect this participant's own strokes. If you set end_button_label, a button with that label sits below the canvas.

timeline.push({
type: jsPsychMultiplayerDraw,
prompt: "<p>Sketch a plan of the room together.</p>",
duration: 120000,
end_button_label: "I'm done",
});
Package@jspsych-multiplayer/plugin-multiplayer-draw
Browser globaljsPsychMultiplayerDraw
Trial typemultiplayer-draw
Requiresa connected session (see Getting started)

Parameters​

ParameterTypeDefaultDescription
promptHTML string""Shown above the toolbar.
aspect_rationumber4/3The canvas's width divided by its height. The canvas is as large as the page allows at this shape, so it has the same shape on every participant's screen.
colorsstring[]5 colors (see below)The color swatches, as CSS colors. The first is selected at the start.
brush_sizesnumber[][0.004, 0.01, 0.02]The brush widths to offer, as a fraction of the canvas width. The middle one is selected at the start.
min_point_distancenumber0.004How far the pointer must move, as a fraction of the canvas width, before another point is recorded. Larger values give fewer points and smaller data.
push_interval_msnumber60How often, in ms, a stroke in progress is sent to the others while it is being drawn. Lower values look smoother to the others; higher values send less.
durationnumber | nullnullEnd the trial after this many ms. null, 0, or a negative number means no time limit. Each participant's timer starts when they reach the trial.
end_button_labelstring | nullnullShow a button with this label that ends the trial for the participant who clicks it. null or "" shows no button.
end_when(group, presence) => booleannullA condition checked at the start and after every change to the trial's shared data or presence. The trial ends as soon as it returns true.
show_rosterbooleanfalseShow a "Participants:" line listing everyone in the group, with "(away)" after anyone whose connection has dropped and "(left)" after anyone who has left.
roster_label(participantId, group, presence) => stringnullThe name shown for each participant in the roster. By default, their participant ID. Only used when show_roster is true.
store_full_strokesbooleantrueSave every stroke, with its points, in strokes. Set false to save only the counts.
end_on_participant_leftbooleantrueEnd the trial when another participant it depends on leaves (see When someone leaves). Set false to keep drawing with whoever remains.

The default colors are near-black #1a1a1a, red #e03131, green #2f9e44, blue #1971c2, and orange #f08c00.

group is the trial's shared data (see Drawing across trials) and presence is everyone's connection status. Both are frozen, so read them but don't modify them. To show names written in an earlier trial, read them from the session scope, for example roster_label: (id) => jsPsych.multiplayer.get(id, { scope: "session" })?.name ?? id.

Data​

FieldTypeDescription
strokesobject[]Every stroke on the canvas when this participant's trial ended, in the order they were started (see Stroke format). Not saved when store_full_strokes is false.
stroke_countnumberHow many strokes were on the canvas, from all participants.
strokes_drawnnumberHow many of them this participant drew, not counting strokes they undid.
draw_timenumberMilliseconds from the start of the trial to its end.
multiplayer_outcomestringHow the trial ended: "completed" (by duration, the end button, or end_when), "participant_left", "connection_lost", or "cancelled" (the experiment called jsPsych.multiplayer.disconnect() during the trial).
left_participantstring | nullThe ID of the participant whose departure ended the trial, when multiplayer_outcome is "participant_left".
ended_bystring | nullWhich end condition completed the trial: "duration", "button", or "condition" (end_when). null when multiplayer_outcome isn't "completed".

Handling dropouts explains multiplayer_outcome and left_participant, and how to branch on them. As with the chat, the saved strokes are what this participant's canvas showed when their trial ended, so a stroke finished in the last moment may be in one participant's data and not another's.

When someone leaves​

By default the trial ends as soon as a participant it depends on reaches left, with multiplayer_outcome: "participant_left" and their ID in left_participant. In a sealed group, it depends on every other member who hasn't left; otherwise, on the participants who were connected when the trial started. A participant who is only away does not end it, and a departed participant's strokes stay on the canvas and in the data.

If this participant's own connection is lost for good, the trial ends with multiplayer_outcome: "connection_lost", keeping the strokes drawn up to that point. A write that fails is retried automatically, and every write carries the participant's complete list of strokes, so nothing is lost.

Drawing across trials​

Strokes are kept in the trial's own part of the shared data (its trial scope), so every draw trial starts with a blank canvas, even when the same trial runs again in a loop. To keep drawing on one canvas across several trials, give those trials the same multiplayer_scope:

const sketch = {
type: jsPsychMultiplayerDraw,
multiplayer_scope: "shared-sketch",
duration: 60000,
};

// The second sketch continues the first
timeline.push(sketch, discussion, sketch);

Everything else in those trials that uses the trial scope shares it too, so give each canvas you want kept apart its own name.

Every write sends the participant's whole list of strokes, so the data grows with the total ink drawn. For long, detailed drawings, raise min_point_distance, and keep in mind that each backend limits how much data a participant can share (see Choosing a backend).

Stroke format​

Each stroke is one continuous press-drag-release:

FieldDescription
id"<authorId>#<seq>", unique within the trial.
authorIdThe participant ID of whoever drew it.
seqCounts that participant's strokes from 0.
pointsThe path, as { x, y } points.
tool"pen" or "eraser".
colorThe CSS color. Meaningless for eraser strokes.
widthThe brush width, as a fraction of the canvas width.
donefalse if the stroke was still being drawn when the trial ended.
tsWhen the stroke was started, in milliseconds since 1970, by the author's clock. Strokes are ordered by this.

Both x and y are fractions of the canvas width, so they are the same on every screen. x runs from 0 (left) to 1 (right); y runs from 0 (top) to 1 / aspect_ratio (bottom), which is 0.75 with the default 4:3 canvas. To draw the picture again, multiply both by the width you want.

The eraser removes whatever was drawn before it, whoever drew it. Redo puts a stroke back with a new ts, so it is drawn on top of anything added since it was undone.

Example​

A five-minute shared canvas that closes for everyone once every participant has clicked I'm done. Clicking the button ends the trial only for the participant who clicked it, so here each participant's click is written to the group first and end_when closes the canvas when everyone has done so:

const draw = {
type: jsPsychMultiplayerDraw,
prompt: "<p>Draw a house together. Click <strong>I'm done</strong> when you are finished.</p>",
duration: 300000,
aspect_ratio: 16 / 9,
colors: ["#000000", "#d9480f", "#1971c2", "#2f9e44"],
show_roster: true,
end_on_participant_left: false, // keep drawing if someone leaves
roster_label: (id, group) => {
// Add a check mark once a participant has clicked "I'm done"
if (group[id] !== undefined && group[id].draw_done) {
return `${id} ✓`;
}
return id;
},
end_when: (group, presence) => {
// End once every participant has either clicked "I'm done" or left
for (const id in group) {
if (!group[id].draw_done && presence[id] !== "left") {
return false;
}
}
return true;
},
on_load: () => {
const done = document.createElement("button");
done.textContent = "I'm done";
done.addEventListener("click", () => {
done.disabled = true;
jsPsych.multiplayer.update({ draw_done: true });
});
document.querySelector(".jspsych-multiplayer-draw").append(done);
},
};

With end_on_participant_left: false, the others keep drawing if someone leaves. A participant who has left can't click the button, so the condition counts them as done.