reference-game: disjoint layouts and role-keyed feedback

[Mandyx22]

Adds two options to plugin-multiplayer-reference-game. Both come from auditing a replication against the original tangrams experiment (hawkrobe/tangrams, OSF osf.io/vzvmf) and finding behaviour the plugin could not express. Neither is specific to that paper.

scramble_mode: "disjoint"

Like "independent", but no object may occupy the same slot for both players — a derangement between the two layouts.

"independent" only guarantees the two layouts are not identical. A random permutation pair still shares about 1/e of its positions, so in a 12-object grid roughly four tangrams sit in the same cell for both players on a typical trial, and "the one in the bottom left corner" works by luck often enough to matter. That undercuts the whole point of scrambling. The original re-rolls until every position differs (game.core.js, notMatchingLocs / arraysDifferent).

Implemented as bounded rejection sampling over the existing deterministic salts — a random pair is disjoint ~37% of the time, so it normally lands within a few tries — backstopped by a rotation of the other player's order, which cannot have a fixed point. It stays deterministic, so both clients still derive the same pair with no extra network traffic, and partner_order still lands in the data without a push. Disjointness is impossible for a single object, so it is skipped there.

Role-keyed feedback_content

feedback_content may now be given per role:

feedback_content: {
  director: { reveal_target: false, show_score: false, show_partner_choice: true },
  matcher:  { reveal_target: true,  show_score: false, show_partner_choice: false },
}

The original shows each role exactly one thing — the director sees which object the matcher clicked, the matcher sees the intended target — where the plugin showed both players everything. Detected by the presence of a director / matcher key, so a flat object behaves exactly as before and omitted keys fall back to the per-key defaults.

Compatibility

Both are opt-in; no existing behaviour changes. "independent" still means what it meant, which matters for experiments already configured against it — a named scramble mode that quietly changes geometry between versions would make two runs of the same experiment file incomparable.

Testing

12 new tests, 61 passing in the package. Disjointness across 60 rounds × 3 participant-id pairs; cross-client agreement and argument-order independence; permutation integrity; the N=2 and N=1 edge cases; an explicit check that plain "independent" really does produce coincidences, so the new mode is not a no-op; and the four role-keyed feedback paths, including the flat-object fallback.

Full monorepo suite: 544 passing, 25 suites. adapter-multiplayer-firebase fails to run on a missing firebase/app module — pre-existing, identical on main (532 passing there; the 12 new tests are the difference).

README and a changeset are included.

Related

jspsych/multiplayer-test-experiments#19 uses both options and is blocked on this — that build cannot run until this merges and the package publishes.

🤖 Generated with Claude Code