Skip to content

Usage Guide

For Moderators

Initial Setup

  1. Open /dashboard and log in with the moderator password.
  2. Use the dashboard as the main control surface for the session.
  3. Participants do not join through a static URL alone; they join through tokenized invitation links generated by the moderator.

Running a Session

Step 1: Open Entry - Click Open Entry. - A new game session is created and the state becomes OPEN. - Players may now redeem invitation tokens and enter the waiting room.

Step 2: Generate Invitation Tokens - Click Generate Tokens. - Download the CSV containing participant join links. - Send one link to each participant.

Step 3: Wait for Participants - Players open their personal links and redeem their tokens. - After redeeming, they enter the waiting room. - When 2 participants are present, the session automatically moves to READY.

Step 4: Start the Game - Click Start Game. - The state becomes IN_PROGRESS. - Players are redirected to their assigned roles: - Player 1: secret card holder - Player 2: guesser with the 12-card grid - The moderator can watch through the moderator view.

Step 5: Observe Round 1 - Watch live chat, voice activity, and eliminations from the Moderator View (/moderator). - The moderator view shows the current secret card and all eliminated cards in real time.

Step 6: Swap Roles for Round 2 - When round 1 is complete, click Swap Roles. - The application closes round 1, swaps player roles, starts round 2, and assigns a new secret card. - Players are redirected automatically.

Step 7: End the Game - Click End Game when the session is finished. - The current round is closed and the game state becomes ENDED.

Step 8: Reset the Session - Click Reset Session. - The state returns to CLOSED. - You can now open a new entry for the next pair of participants.

Moderator Notes

  • Moderator authentication is session-based.
  • The moderator is not treated as a participant with a participant ID in the normal flow.
  • Moderator chat messages are still stored in the chat table with role = 'moderator'.

For Participants

Joining a Game

  1. Receive your invitation link
  2. The moderator sends you a personal invitation link.

  3. Open the link in your browser.

  4. Redeem the token

  5. If the token is valid and unused, you may proceed.

  6. If the token is expired or already used, access is denied.

  7. Enter the waiting room

  8. After redeeming the token, you enter the waiting room.

  9. Wait there until both players are present and the moderator starts the game.

  10. Receive your role

  11. When the game starts, you are redirected automatically.
  12. You become either:
    • Player 1: sees only the secret card
    • Player 2: sees the 12-card grid

During Gameplay

  • Use the chat box to communicate.
  • Use voice chat if enabled. Your browser will ask for microphone permission the first time — click Allow.
  • If you are Player 2, eliminate cards that no longer match the answers.
  • If the moderator swaps roles for round 2, your page redirects automatically.

If You Close the Browser

  • Your player identity is preserved through the player join flow.
  • If the session is still active, reopening your role page (/player1 or /player2) can return you to the game.
  • If the session has ended or been reset, the game is no longer active and you must wait for a new invitation.

Session States

  • CLOSED: no active entry
  • OPEN: players may join with valid tokens
  • READY: two players joined; waiting for moderator to start
  • IN_PROGRESS: active gameplay
  • ENDED: gameplay finished

What Gets Stored

  • Secret card per round → rounds.chosen_card_id
  • Round timing → rounds.started_at, rounds.ended_at
  • System/session events → events
  • Chat messages → chat
  • Eliminated cards → eliminated_cards
  • Invitation tokens → access_tokens