4. File Specification: Instruction Schema (`instruction.jsonl`)

The instruction.jsonl file defines the sequence of screens (instructions, test trials, quizzes) that a participant sees before the main experiment begins. Each line contains one JSON object representing a "Module" object, which are presented in order.

4.1. Top-Level Structure

The file contains one "Module" object per line. Each Module object must have a type field, which determines the other required fields.

{ "type": "instruction", ... }
{ "type": "test_trial", ... }
{ "type": "comprehension_quiz", ... }

4.2. Module Type: `instruction`

This is the most common Module. It displays a page of text and/or images to the participant.

Key	Type	Description
`type`	String	Must be `"instruction"`.
`text`	String	The main body of text for the page. Can contain simple HTML tags like `<p>`, `<strong>`, `<ul>`, `<li>`.
`media_url`	Array of Strings	(Optional) An array of image/video paths to display, identical to the `media_url` in `trial.jsonl`.

4.3. Module Type: `test_trial`

This Module displays a fully functional trial (a stimulus and queries) from trial.jsonl. This allows participants to practice the task. Important: A test_trial should feature an identical looking trial that participants would encounter in the main experiment, allowing them to familiarize themselves with the interface and task format before proceeding.

Key	Type	Description
`type`	String	Must be `"test_trial"`.
`stimuli_id`	String	The `stimuli_id` of the trial from `trial.jsonl` to display.
`feedback`	String	(Optional) A text block to show after the user clicks "Submit", e.g., "The correct answer for this practice trial is X."

4.4. Module Type: `comprehension_quiz`

This Module presents one or more questions (identical to the Query Object format) to check the participant's understanding. It provides immediate feedback. Important: Unlike test_trial, a comprehension_quiz focuses on high-level questions about the experiment itself (e.g., "What is your main task?", "How should you respond?"), rather than presenting actual experimental stimuli.

Key	Type	Description
`type`	String	Must be `"comprehension_quiz"`.
`text`	String	(Optional) Introductory text to display above the questions.
`queries`	Array of Objects	An array of Query Objects (as defined in Section 3.2). These are the quiz questions. See note below.

Note on Quiz Queries: Queries within a comprehension_quiz (usually multi-choice) must include an answer field to provide real-time feedback to the user. The answer field is defined in the Trial Schema (Section 3.2).

4.5. Full `instruction.jsonl` Example

This example shows a sequence containing a welcome page, a second instruction page with an image, a test trial, and a final comprehension quiz.

{
  "type": "instruction",
  "text": "Thank you for participating. In this task, you will observe an agent (a blue circle) move in a simple environment.
Your goal is to determine what the agent wants.Please pay close attention to its behavior."
}
{
  "type": "instruction",
  "text": "You will see a scene like the one below. The blue circle is the agent. The red and blue boxes are potential goals. Your task is to judge which goal the agent wants after observing its movement.",
  "media_url": [
    "https://placehold.co/600x400/e2e8f0/334155?text=Example+Scene"
  ]
}
{
  "type": "test_trial",
  "image": "assets/stimuli/demo_1.gif",
  "commentary": "Observe the agent's action in the image above.



If more than one gem seems likely, you can select all likely gems. Remember that some keys might be hidden among the boxes.",
  "queries": [
    {
      "prompt": "What is the agent's primary goal?",
      "type": "multi-choice",
      "options": ["Reaching the red box", "Reaching the blue box", "Looking for a key"],
      "required": true,
    }
  ],
  "feedback": "In this example, the player is going for the red box!"
}
{
  "type": "comprehension_quiz",
  "text": "Please answer the following questions.",
  "queries": [
    {
      "prompt": "What is your main task in this experiment?",
      "type": "multi-choice",
      "tag": "quiz_q1",
      "option": [
        "To click the boxes as fast as possible.",
        "To determine the agent's goal.",
        "To count the number of circles."
      ],
      "answer": 1
    },
    {
      "prompt": "Is this a timed experiment?",
      "type": "multi-choice",
      "tag": "quiz_q2",
      "option": [
        "Yes",
        "No"
      ],
      "answer": 1
    }
  ]
}

4.6. Live Demo of Instruction Sequence

Below is a simulation of how the sequence from the example JSON above would be rendered to the participant, one Module at a time. Click the options in Module 4 to see the feedback.

Module 1 of 4: Instruction

Thank you for participating. In this task, you will observe an agent (a blue circle) move in a simple environment.

Your goal is to determine what the agent wants.

Please pay close attention to its behavior.

Module 2 of 4: Instruction

You will see a scene like the one below. The blue circle is the agent. The red and blue boxes are potential goals. Your task is to judge which goal the agent wants after observing its movement.

Module 3 of 4: Practice Trial

Observe the agent's action in the image above.

What is the agent's primary goal?

Reaching the red box Reaching the blue box Looking for a key

How confident are you in your answer?: 50

Feedback: In this example, the player is going for the red box!

Module 4 of 4: Comprehension Check

Please answer the following questions.

What is your main task in this experiment?

To click the boxes as fast as possible. To determine the agent's goal. To count the number of circles.

Is this a timed experiment?

Yes No

4. File Specification: Instruction Schema (instruction.jsonl)

4.1. Top-Level Structure

4.2. Module Type: instruction

4.3. Module Type: test_trial