Skip to main content

multiplayer-countdown

A countdown trial shows a clock that runs from the moment the first participant in the group reached it. Everyone sees the same time remaining, even if they arrived a few seconds apart, and each participant's trial ends when the group's time runs out. A participant who reaches the trial late joins the clock at the time the group actually has left.

Use it for a timed phase that the whole group shares: "you have one minute to think", a break between rounds, or a deadline shown on its own screen. It can also count up instead of down.

What the participant sees: your stimulus, a large M:SS clock, and your prompt below it. There is nothing to click. The trial ends when the clock reaches 0:00 (or, counting up, the full duration). For screen-reader users, the last five seconds are announced aloud.

timeline.push({
type: jsPsychMultiplayerCountdown,
duration: 60000,
stimulus: "<p>Time left to think:</p>",
});
Package@jspsych-multiplayer/plugin-multiplayer-countdown
Browser globaljsPsychMultiplayerCountdown
Trial typemultiplayer-countdown
Requiresa connected session (see Getting started)

Parameters​

ParameterTypeDefaultDescription
durationnumberrequiredHow long the timer runs, in ms. Must be more than 0.
modestring"countdown""countdown" shows the time remaining; "countup" shows the time elapsed, like a stopwatch. Both end at duration.
stimulusHTML stringnullShown above the clock, e.g. "Time left:". null shows nothing.
promptHTML stringnullShown below the clock. null shows nothing.
format(ms) => stringnullTurns the time, in ms, into the text shown. null shows M:SS, rounding up when counting down (so 0:01 stays up for the last partial second) and down when counting up.
save_groupbooleanfalseSave the trial's shared data, as it was at the end of the trial, in the group data field.

The trial throws an error if duration is missing or not a positive number.

Data​

FieldTypeDescription
started_atnumberWhen the group's countdown started (the earliest start time any participant wrote), in milliseconds since 1970.
own_started_atnumberWhen this participant reached the trial, by their own clock. The gap from started_at is roughly how much later they arrived than the first participant.
displayed_durationnumberHow long this participant saw the timer, in ms. Less than duration for anyone who arrived after the first participant.
modestring"countdown" or "countup".
multiplayer_outcomestring"completed", or "connection_lost" if this participant's connection was lost for good during the countdown. The timer still runs to the end, from the start time it already had.
left_participantnullAlways null: the countdown doesn't depend on any other participant. It is recorded so every multiplayer trial has the same columns.
groupobjectThe trial's shared data at the end of the trial, keyed by participant ID. Only saved when save_group is true.

How the group agrees on a start time​

When a participant reaches the trial, it writes the current time to its part of the trial's shared data. Every participant's clock is then based on the earliest of those times. As later participants' times arrive, the earliest one does not change, so everyone converges on the same start. If a participant sees an earlier time arrive after their clock is already running, their clock jumps down to match.

This makes the countdown a shared deadline, not a waiting point. Participants finish within a fraction of a second of each other, but not at exactly the same moment, and the countdown does not wait for anyone who is late or has left. To make everyone start together, put a multiplayer-ready or multiplayer-sync trial before it. To be sure everyone has finished before the next trial, put one after it.

Each participant's clock uses their own computer's time. If one computer's clock is badly wrong (running behind by several seconds, say), the group's countdown can end early for everyone else. With normally set clocks, the difference is a few milliseconds.

Each countdown starts a fresh clock​

The start times live in the trial's own part of the shared data (its trial scope), so every countdown trial starts a new clock, including each repetition inside a loop. You don't need to name anything.

To run one clock across several trials, give them the same multiplayer_scope (a parameter every trial accepts). A participant who already has a start time in that scope keeps it, so the second trial picks up where the first left off and ends at its own duration, measured from the shared start. Here the group has 60 seconds in total: 20 to read, and whatever is left of the minute to answer:

const readPhase = {
type: jsPsychMultiplayerCountdown,
multiplayer_scope: "round_clock",
duration: 20000,
stimulus: "<p>Time left to read:</p>",
};
const answerPhase = {
type: jsPsychMultiplayerCountdown,
multiplayer_scope: "round_clock",
duration: 60000, // measured from the start of readPhase
stimulus: "<p>Time left to answer:</p>",
};

Inside a loop, build the name from something that changes each round, such as a timeline variable (multiplayer_scope: () => `round_${jsPsych.evaluateTimelineVariable("round")}`), so a new round doesn't pick up the previous round's expired clock.

Example​

A 30-second planning phase before each of five rounds, with a ready trial to line everyone up first:

const roundTrials = {
timeline: [
{
type: jsPsychMultiplayerReady,
expected_players: 4,
stimulus: () =>
`<p>Round ${jsPsych.evaluateTimelineVariable("round")} is about to start.</p>`,
},
{
type: jsPsychMultiplayerCountdown,
duration: 30000,
stimulus: () => `<p>Round ${jsPsych.evaluateTimelineVariable("round")}: plan your move.</p>`,
prompt: "<p>The round starts when the timer reaches zero.</p>",
},
// … the round itself …
],
timeline_variables: [{ round: 1 }, { round: 2 }, { round: 3 }, { round: 4 }, { round: 5 }],
};

Showing the clock during another trial​

The clock's building blocks are also available as functions on jsPsychMultiplayerCountdown, so you can show the group's time during another trial (for example, next to a multiplayer-draw canvas). startedAtKey(name) gives a field name that keeps the clock apart from the trial's other data, resolveStartedAt(group, key) finds the group's start time, computeRemaining(startedAt, duration, now) and computeElapsed(startedAt, duration, now) do the arithmetic, and formatTime(ms) gives M:SS.

The trial showing the clock writes its own start time and reads everyone's, both in its own scope:

const key = jsPsychMultiplayerCountdown.startedAtKey("draw_phase");
jsPsych.multiplayer.update({ [key]: Date.now() }); // once, when the trial starts

// Then, on a timer:
const startedAt = jsPsychMultiplayerCountdown.resolveStartedAt(jsPsych.multiplayer.getAll(), key);
const remaining = jsPsychMultiplayerCountdown.computeRemaining(startedAt, 60000, Date.now());
clockElement.textContent = jsPsychMultiplayerCountdown.formatTime(remaining);