multiplayer-test-experiments

Standalone, faithful replication builds of published reference-game studies, built on jspsych-multiplayer plugins. Ported out of that repo's examples/ (which is meant for lightweight teaching demos, not study artifacts) so these can live, version, and be piloted independently.

Files

• reference-game-hawkins.html — replicates Hawkins, Frank & Goodman (2020), Cognitive Science 44, e12845. Sequential condition: single target per trial, one click. Currently the paid-pilot build: 18 trials, after a walkthrough of the game screen and two paired practice rounds, with Prolific exits, dropout handling and data saving. Runs on the local adapter or as a JATOS group study.
• hawkins.js — the Hawkins build's session logic (main and practice schedules, the pair barriers, round classification, exit routing, and JATOS saving), kept out of the page so tests/ can load it.
• hawkins-onboarding.js — the seven-step, role-specific walkthrough of the game screen shown after the role recap. Practice rounds use targets outside the dyad's main schedule and are saved with phase: "practice"; see WALKTHROUGH-PRACTICE.md.
• hawkins-ui.js — the Hawkins round display: separate trial, number-correct and time-remaining panels, a warning in each round's last 10 seconds, a "Correct!", "Incorrect." or "Time's up!" result line, and labels for the chat. Presentation only; see GAMEPLAY-CLARITY.md.
• presence-check.js — a jsPsych extension on each Hawkins round: after 30s with no mouse, keyboard, wheel or touch input from the participant (script-dispatched events and the chat log's own scrolling don't count) it asks "Are you still with us?" and waits 15s for a button click. It stays out of feedback. A reminder only: missed prompts and clicks on its backdrop are recorded (presence_* fields) but never end the round or the game.
• scripts/vendor.mjs — fills the gitignored vendor/ with every script the Hawkins page loads, at pinned versions. scripts/make-jzip.mjs packages the page as a JATOS study archive.
• reference-game-cwg.html — replicates Clark & Wilkes-Gibbs (1986), Cognition 22:1–39. Full-board condition: all 12 tangrams as an ordered target, 6 trials.
• tangrams.js — shared canonical 12-tangram stimulus set and deterministic trial schedule builders (sequentialSchedule, fullBoardSchedule), seeded from the session id so each dyad gets its own order while both partners agree on it.
• assets/tangrams/ — the 12 tangram PNGs, the exact set from hawkrobe/tangrams (Hawkins, Frank & Goodman 2020), themselves reproduced from Clark & Wilkes-Gibbs (1986).

	reference-game-hawkins.html	reference-game-cwg.html
Replicates	Hawkins, Frank & Goodman (2020)	Clark & Wilkes-Gibbs (1986)
Condition	Sequential — single target, one click	Full-board — all 12 tangrams as an ordered target
Schedule	72 trials in the original; 18 trials (3 blocks × 6 assigned targets) in the paid pilot	6 trials, fresh full-board order each
Fidelity note	Near-exact, including Exp. 2's matcher-click gate (require_message_before_response: true)	Text chat substitutes for the original spoken dialogue — the one deliberate deviation, noted in-file

Both fix director/matcher for the whole game, reveal the target to the director only, and use unrestricted two-way chat — faithful to both papers and load-bearing for the reference-shortening effect both measure. Both were verified parameter-by-parameter against the papers and the original hawkrobe/tangrams experiment code, and play-tested two-tab at full schedule length.

round_timeout is not from either paper. Both builds set one (60s Hawkins, 180s C&WG) purely so a disconnected or absent partner cannot hang the trial forever — neither original was timed. Rounds it ends are logged as a timeout (multiplayer_outcome: "timeout" in the Hawkins build, ended_by: "timeout" in C&WG) with a null assignment, so they're easy to exclude. In the Hawkins build the limit is the matcher's selection_timeout: both players see a "Time's up" result and the game moves on. A timed-out row has round_result: "timeout", correct: null, and an idle_role: "director" if no director message had reached the matcher by the deadline, otherwise "matcher". The matcher counts those messages when its choice is submitted and shares the count, so both rows carry the same director_messages_by_deadline and idle_role. feedback_shown and timeout_source ("selection_timeout", or "round_timeout" for the 65s backstop) come from the plugin's data. Timeouts never end the game; only a disconnection does.

Current pilot direction

The proposed first paid Prolific run is now a shortened Hawkins-style multiplayer pilot, built from the Hawkins fidelity work in PR #19 (hawkins-cued-fidelity) rather than from the older prototype file in the C&WG infrastructure stack. The working design is 18 continuous trials in three blocks of six. Each dyad receives a random subset of six of the twelve tangrams as targets, repeated once per block in a fresh shuffled order. All twelve tangrams remain visible on every trial. The subset and schedule use shared session randomness, and assigned_target_ids is saved on every row. That is an intentional adaptation: the main goal of the first paid run is to prove the multiplayer pipeline, including pairing, data saving, terminal routes, and participant handling. The reference-shortening replication is still a scientific target, but the shortened pilot should not be described as a full six-block Hawkins replication.

The C&WG paid-run stack remains valuable source material for infrastructure: centralized run configuration, Prolific identifiers, DataPipe egress, no-match routing, dropout handling, and tests should be ported to Hawkins rather than treating C&WG as the first launch target.

Running it

Hawkins (reference-game-hawkins.html)

1. npm run vendor, with a jspsych-multiplayer checkout at ../jspsych-multiplayer (or pass its path: node scripts/vendor.mjs <path>). This builds the multiplayer bundles at the commit pinned in scripts/vendor.mjs and downloads the pinned jsPsych preview build, plugins, and DataPipe Pipe extension into vendor/.
2. Serve the repo over http (e.g. npx http-server .) and open the page. It adds ?mp_session=… to the URL.
3. Open that full URL in exactly one other tab. The two tabs pair, and roles are drawn at random.

npm test runs the tests. As a JATOS group study: npm run jzip, then import the .jzip with JATOS's Import Study. The batch's Max active members must be 2; JATOS then pairs arrivals from a single study link and the adapter seals each pair. npm run jzip refuses to build while any Prolific completion code in CONFIG.COMPLETION_CODES is empty or a placeholder (insertcodehere). For a test build, run npm run jzip -- --allow-placeholder-codes; the page then labels each code as a test code, and the study's JATOS comments say it is a test build.

DataPipe setup for the Hawkins pilot

CONFIG.DATAPIPE_EXPERIMENT_ID in reference-game-hawkins.html is configured for the Google Drive-backed DataPipe experiment wE2Zlitn0uhu. This folder was created primarily for testing; it may also be used for the main study, pending review. Collaborators are welcome to create their own DataPipe experiment with Google Drive as its storage provider and replace this one configuration value with their dashboard's 12-character experiment ID. DataPipe is on only when JATOS serves the page. A local run uploads nothing unless its URL opts in with ?datapipe=1 (e.g. reference-game-hawkins.html?mp_session=…&datapipe=1); use that only for a deliberate test upload, since it writes into the study's Drive folder. Set the ID to an empty string to disable DataPipe everywhere. Turn on Accept new data in the DataPipe dashboard and verify a completed test run in the linked Drive folder before a paid run. The extension stages each completed trial and submits one JSON file when the jsPsych timeline ends; an abandoned run can yield a .partial.json file. A participant who reloads mid-session produces two files: a partial one from the page they left and a short final one from the reloaded page, which records the reloaded exit. The filename is random and carries no participant identifier. Prolific, participant, and dyad IDs remain in the saved rows. JATOS result data is saved separately.

The terminal screen never waits for the upload. It shows the exit message and the Prolific controls at once; its status line reports the save, or after 3 seconds (SAVE_STATUS_BUDGET_MS) says the upload is still running and the participant can submit.

Streaming means data leaves the browser during the session, and closing the tab may leave a partial file. Confirm that this matches the study consent and retention plan. DataPipe's staged-trial limit is 16 KiB per trial; an oversized trial is omitted from a recovered partial file, although the final full-data submission can still include it. See DataPipe's streaming limits.

C&WG (reference-game-cwg.html)

Still on the older multiplayer API and npm package pins, and not runnable until it is ported the way the Hawkins build was.

Running it as a paid study

Not yet. READINESS.md is the full audit, written before jspsych-multiplayer gained session IDs, group formation and rejoin detection, so parts of it are out of date. The Hawkins build now has: pairing from one JATOS study link, per-dyad trial orders from the session's shared randomness, a walkthrough and two practice rounds before the main game (which add time the advertised duration and reward must include), dropout detection with paid exits, per-round timeout classification (timeouts never end the game), reload detection, Prolific IDs and completion routing, and saving to JATOS and DataPipe. Still open: real completion codes are unset in CONFIG (placeholders stand in); the build has not run on a real JATOS server, so no JATOS-hosted run has yet been checked end to end in the DataPipe Drive folder (a local ?datapipe=1 run can check the upload path sooner); and the multiplayer packages are unreleased (the build pins a jspsych-multiplayer commit and a jsPsych preview build).