Skip to main content

Quiz

Interactive multiple-choice quiz questions with support for text, images, timed responses, and scoring.

Example structures​

Simple text quiz​

{
  "type": "Quiz",
  "data": {
    "id": "q1",
    "text": "What is 2+2?",
    "options": ["3", "4", "5", "6"],
    "answer": [2],
    "answerTime": 30,
    "showScoreboard": true
  }
}

Quiz with question image​

{
  "type": "Quiz",
  "data": {
    "text": "What concept does this describe?",
    "options": [
      "A scientifically verifiable assumption",
      "A proven historical fact",
      "An unverifiable claim without structure",
      "A logically compelling conclusion"
    ],
    "answer": [1],
    "answerTime": 20,
    "imageUrl": "concept-image.png"
  }
}

Image-based quiz (option images)​

{
  "type": "Quiz",
  "data": {
    "text": "Which image is AI-generated?",
    "options": [
      {
        "imageUrl": "real-photo.jpg"
      },
      {
        "imageUrl": "ai-generated.jpg"
      }
    ],
    "answer": [2],
    "answerTime": 60
  }
}

Quiz with text and image options​

{
  "type": "Quiz",
  "data": {
    "text": "Identify the correct landmark",
    "options": [
      {
        "text": "Eiffel Tower",
        "imageUrl": "eiffel.jpg"
      },
      {
        "text": "Big Ben",
        "imageUrl": "bigben.jpg"
      },
      {
        "text": "Statue of Liberty",
        "imageUrl": "liberty.jpg"
      }
    ],
    "answer": [1],
    "answerTime": 45,
    "showScoreboard": true
  }
}

Multiple correct answers​

{
  "type": "Quiz",
  "data": {
    "text": "Which of these are prime numbers?",
    "options": ["2", "4", "7", "9"],
    "answer": [1, 3],
    "answerTime": 25
  }
}

Required Properties​

  • text (string) - The question text displayed to participants
  • options (array) - Answer choices, supporting two formats:
    • String format: ["Option 1", "Option 2", "Option 3", "Option 4"]
    • Object format: [{ text?: string, imageUrl?: string }, ...]
      • Each option can have text, imageUrl, or both
      • Useful for visual quizzes or combining text with images
  • answer (array of numbers) - Correct answer indices (1-based, not 0-based!)
    • [2] means the second option is correct
    • [1, 3] means both first and third options are correct
    • Supports multiple correct answers

Optional Properties​

Timing & Display​

  • id (string, optional) - Unique identifier for the quiz question
    • Used for tracking performance in flows and analytics
  • answerTime (number, optional, default: -1) - Seconds allowed to answer
    • -1 or omitted: No time limit (manual progression)
    • > 0: Countdown timer shown to host, auto-advances when time expires
    • Scoring is time-based: faster correct answers earn more points (up to 1000 points)
  • showAnswerManually (boolean, optional, default: false) - Control answer revelation
    • false: Automatically reveal answers when time expires or all participants answer
    • true: Host must manually advance to reveal answers
  • showScoreboard (boolean, optional, default: true) - Display scoreboard after answer reveal
    • true: Shows third phase with participant rankings (host only)
    • false: Skips directly to next node after answer reveal

Visual Content​

  • imageUrl (string, optional) - Main question image shown alongside the question
    • Displayed in left column for host view
    • Automatically sized based on aspect ratio (portrait vs landscape)
    • Path relative to workshop resource directory
  • url (string, optional) - Additional URL reference (legacy/reserved for future use)

Flow & Groups (Advanced)​

  • assignedGroupId (string, optional) - Group assignment for CoCreate flows
  • cardState (string, optional) - Card state in CoCreate context: "preview", "editable", or "completed"
  • completedTimestamp (number, optional) - Completion timestamp for tracking
  • createdByCoCreate (boolean, optional) - Flag indicating quiz was created dynamically by CoCreate node

Quiz Phases​

The Quiz node progresses through up to 3 internal phases:

Phase 0: Question Phase (index: 0)​

  • Participants see the question, options, and timer (if set)
  • Options displayed in a 2x2 grid with colored backgrounds
  • Each option has a unique shape icon: Triangle, Square, Star, Circle
  • Participants can select/change answers until time expires or host advances
  • Host sees question text, timer countdown, and "Waiting for resolution" message
  • Auto-advances when:
    • Timer reaches zero (if answerTime > 0)
    • All participants have answered (if answerTime > 0)
    • Host manually advances (if showAnswerManually: true)

Phase 1: Answer Reveal (index: 1)​

  • Correct answer(s) highlighted in green with increased opacity
  • Incorrect selected answers shown in red
  • Non-selected answers faded to 30% opacity
  • Participants can see which they got right/wrong
  • Host sees "Solution" indicator
  • Scoring calculated based on:
    • Correctness: Answer must be in the answer array
    • Speed: Faster responses earn more points (if timed)
    • Maximum 1000 points per question
  • Auto-advances after a few seconds (unless manually controlled)

Phase 2: Scoreboard (index: 2, optional)​

  • Only shown if showScoreboard: true
  • Displays participant rankings with scores
  • Host-only view
  • Shows cumulative scores if multiple quizzes in session
  • Uses host-only data transmission for security

Scoring System​

Points are awarded based on:

  • Correctness: Answer must match one of the indices in the answer array
  • Speed (if timed):
    • Formula: Math.round((1 - (responseTime / (answerTime * tickrate) / 2)) * 1000)
    • Maximum: 1000 points (instant correct answer)
    • Minimum: 500 points (correct answer at the last moment)
  • No time limit: Correct answers receive 1000 points

Scores are stored in state.scoreboard[nodeIndex][userId] for leaderboard tracking.

Animations & Visual Design​

Answer Options​

  • Colors: Fixed color scheme for consistency
    • Option 1 (Triangle): #FF7BA3 (pink)
    • Option 2 (Square): #85C1CD (blue)
    • Option 3 (Star): #32CE7D (green)
    • Option 4 (Circle): #FFBA42 (orange)
  • Layout:
    • 2x2 grid for 3-4 options
    • 2x1 grid for 2 options
    • Responsive sizing with consistent borders
  • Animations: Sequential fade-in-up animation for unanswered questions
    • Staggered delays (0ms, 100ms, 200ms, 300ms)
    • No animations when reviewing answered questions
  • Text Sizing: Auto-adjusts based on longest option length
    • ≤2 words: text-6xl
    • ≤3 words: text-4xl

    • 3 words: text-3xl

Question Image (Host View)​

  • Displays with skeleton loader during load
  • Quick fade-in animation (300ms) once loaded
  • Responsive column width based on aspect ratio:
    • Portrait: 25% width (1/4)
    • Landscape: 33% width (2/6)
  • Rounded corners with object-cover fit

Participant View​

  • Options displayed in 2x2 grid with shapes and text
  • Selected answer highlighted with yellow border
  • Mobile-optimized with responsive text sizing
  • Shapes scale based on role (host: 4rem, participant: 5rem)

Sound Effects​

The Quiz node uses three sound effects (host only):

  1. CountDownRand - Played when question phase begins (countdown start)
  2. DrumHit - Played when answer is revealed (dramatic effect)
  3. CountUpRand - Played when scoreboard is shown (celebration)

Flow Integration​

Quiz nodes can be part of a flow sequence (e.g., series of quiz questions):

Flow Behavior​

  • When used in a flow, the Quiz node tracks progress through state.activeFlow
  • After completing a quiz in a flow:
    • Automatically advances to next quiz in sequence
    • Returns to origin node (typically CoCreate) when flow completes
    • Triggers client-side flow summary for last quiz in flow
  • Flow summary includes:
    • All questions in the flow
    • User's selected answers for each question
    • Correct/incorrect status
    • Option details for review

Flow Summary Payload​

When a participant completes the last quiz in a flow, the client receives:

{
  "flowId": "flow-name",
  "originNodeIndex": 5,
  "matchId": "match-123",
  "workshopKey": "workshop-key",
  "flowNodeDetails": [
    {
      "nodeIndex": 7,
      "questionText": "Question 1",
      "options": ["A", "B", "C", "D"],
      "correctAnswerIndices": [2],
      "nodeId": "q1",
      "selectedOptionText": "B",
      "isCorrect": true
    }
  ]
}
  • Next: Moves to next quiz in flow, or returns to origin if at end
  • Back: Moves to previous quiz in flow, or returns to origin if at start
  • Resets internal quiz state (index to 0) when transitioning between quizzes

User Performance Tracking (LEAF System)​

Quiz responses are automatically tracked in the LEAF state system:

state.leafState.users[userId].quizPerformance[nodeIndex] = {
  nodeText: "Question text",
  selectedAnswer: 2, // 1-based index
  selectedOptionText: "Selected option text",
  isCorrect: true,
  timestamp: 1234567890,
  questionId: "q1",
  allOptions: [...], // Full options array
  correctAnswerIndices: [2], // Correct answer indices
  questionImageUrl: "image.jpg"
}

This data enables:

  • Performance analytics across multiple quizzes
  • Flow completion summaries
  • Learning progress tracking
  • Individual and group performance reports

Host Features​

Display​

  • Question text shown prominently at top
  • Timer displayed when active (red text when ≤9 seconds)
  • Phase indicator: "Waiting for resolution", "Solution", or timer
  • Question image shown in left column (if provided)
  • Answer options in right column with full details

Controls​

  • Can manually advance through phases (if showAnswerManually: true)
  • Sees scoreboard in final phase
  • Timer countdown visible throughout question phase
  • Navigation shows "Next node in X seconds" during auto-advance

Participant Features​

Display​

  • Options shown in grid with shape icons
  • Mobile-optimized responsive layout
  • Selected answer highlighted with yellow border
  • Answer feedback shown after reveal (green/red)

Interaction​

  • Click/tap to select answer
  • Can change answer before time expires
  • Visual confirmation of selection
  • Locked after time expires or answer reveal

Example: Complete Quiz Sequence​

{
  "type": "Quiz",
  "data": {
    "id": "conspiracy-q1",
    "text": "What best describes 'conspiracy hypothesis'?",
    "options": [
      "A scientifically verifiable assumption",
      "A proven historical fact",
      "An unverifiable claim without structure",
      "A logically compelling conclusion"
    ],
    "answer": [1],
    "answerTime": 20,
    "showAnswerManually": false,
    "showScoreboard": true,
    "imageUrl": "conspiracy-concept.png"
  },
  "hostdata": {
    "notes": "Emphasize the difference between hypothesis and theory"
  }
}
tip
  • Answer indices in the answer array are 1-based (not 0-based like JavaScript arrays)
    • answer: [1] means the first option is correct
    • answer: [2, 4] means the second and fourth options are correct
  • Maximum 4 options supported (due to fixed color/shape scheme)
  • Images should be placed in the workshop's resource directory
  • Quiz nodes can be reused in multiple flows with different participants
  • Internal state (index) automatically resets to 0 when leaving/re-entering the node
  • Scoreboard aggregates scores across all quiz nodes in the workshop session
  • Sound effects play only for the host to avoid disrupting participants