Game: Create a new quiz feature

[CYX22222003]

Description

Previously, the quiz feature of the game was implemented by jumping between dialogue segments based on the player's choices. We have now separated the quiz component from the dialogue objects and achieved the following improvements:

• Display scores and store quiz results
• Create branching storylines based on different quiz results
• Simplify story writing syntax for quiz components

GameQuizManager

Renders the quiz using dialogue boxes and prompts UI. A prompt for players to choose whether they want to start the quiz is added before every quiz starts.

QuizParser

Parses the quiz content under the quizzes header in the story file.

Saving quiz results

Quiz results are saved as an array of [string, number] pairs, representing the quizId and the latest score of the corresponding quiz. The score of a quiz is the number of questions answered correctly.

New actions & conditions

Adds new action show_quiz to show a quiz. The show_quiz action is recommended to only be used in dialogues. During a quiz, the dialogue box and speaker belonging to the dialogue will be set invisible, and keyboard inputs will be disabled.

New conditions attemptedQuiz, passedQuiz, and quizScore are added for story writers to check the completion status of a quiz. attemptedQuiz is true if the player has played all questions in the given quiz, regardless of the scores obtained. passedQuiz is true if the player has played all questions in the given quiz and got full marks. quizScore is true if the score of the given quiz is greater than or equal to the given number. The syntax for conditions in txt file is as follows:

attemptedQuiz.<quizId>
passedQuiz.<quizId>
quizScore.<quizId>.<number>

Interpolation of quiz scores in dialogues

Storywriters can insert quiz scores in dialogue lines. This allows writers to define how they want to show the quiz score. The syntax in txt file is similar to inserting the player's name in dialogues:

@scottie, normal, left
You got {<quizId>.score} questions right!

Type of change

• [ ] Bug fix (non-breaking change which fixes an issue)
• [x] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
• [x] This change requires a documentation update
• [x] Code quality improvements

How to test

As this feature should be backward compatible, all previous mock chapters on Source Academy & all chapters already uploaded on Source Academy should function without issues. A mock chapter containing quizzes is used to test the new features in the game simulator.

Checklist

• [x] I have tested this code
• [x] I have updated the documentation

[coveralls]

Pull Request Test Coverage Report for Build 9675378498

Details

• 0 of 0 changed or added relevant lines in 0 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage remained the same at 31.45%

---

Totals
Change from base Build 9663643298:	0.0%
Covered Lines:	4891
Relevant Lines:	14648

---

💛 - Coveralls

[reginateh]

Added the following changes:

1. Save the latest score (number of questions correct) of a quiz instead of "attempted" and "completed" status.
2. New condition quizScore to check if the quiz score is >= the given number. This condition has 2 parameters, a quizId and a number.

   quizScore.<quizId>.<number>

3. Change the name of completedQuiz to passedQuiz to improve clarity.
4. Support interpolation of quiz scores in dialogue lines. This allows writers to define how they want to show the quiz score. The syntax in txt file is similar to inserting the player's name in dialogues:

   @scottie, normal, left
   You got {<quizId>.score} questions right!

5. Remove the not customizable quiz score display message.

Also updated the PR description.

[CYX22222003]

Hi, sorry for the late review, thanks wo I did a quick look through the code and have some rough feedback below.

P.S.: Could you provide a screenshot of what the new feature looks like?

quiz question and options:

quiz starting prompt

character reaction to students' response

[CYX22222003]

Thanks for the PR @CYX22222003 @reginateh - your work over the semester is much appreciated! This feature should be quite helpful for game storywriters moving forward 😄

Apart from the images (which I see you've posted), could you also provide a full example of a quiz being written in a checkpoint txt file? It would be helpful as a cross-reference.

Also, after this PR, please don't forget to update the documentation for the game developer guide & the storywriter guide!

Here are some small queries / nits to address:

Here is a sample of quiz:

quizzes
    sourceManual
        0
        What is the pre-declared constant for: The Number value for π, the ratio of the circumference of a circle to its diameter?
        answer: 3
        option
            apple_Pi
            @ershk, thinking, left
            ...Are you hungry or something?
        option
            math_Pi
        option
            math_pi
        option
            math_PI

        1
        What is the pre-declared constant for: The Number value for the base-10 logarithm of e, the base of the natural logarithms?
        answer: 2
        option
            math_L10
        option
            math_LOG10
        option
            math_LOG10E
        option
            math_L10E

    telebayConsole
        0
        The first expression is: 100 + 37; What is the simplified form for this expression?
        answer: 3
        option
            13
        option
            37
        option
            100
        option
            137
            @scottie, smile, left
            Great! Looks like that worked.

        1
        The second expression is: (6 + 8) * 7 + 2 * 3; What is the simplified form for this expression?
        answer: 1
        option
            103
        option
            104
            @scottie, smile, left
            Great! Looks like that worked, too.
        option
            300
        option
            378

Use the showQuiz method inside a dialogue

 2
        @ershk, excited, left
        Yeah. Let's do this!
        @ershk, happy, left
        You can refer to the Source documentation if you'd like! Maybe that will help us get used to it, too.
        @ershk, normal, left
        Let's get started!
            show_quiz*(sourceManual)
        @ershk, normal, left

[CYX22222003]

Thanks for the PR @CYX22222003 @reginateh - your work over the semester is much appreciated! This feature should be quite helpful for game storywriters moving forward 😄

Apart from the images (which I see you've posted), could you also provide a full example of a quiz being written in a checkpoint txt file? It would be helpful as a cross-reference.

Also, after this PR, please don't forget to update the documentation for the game developer guide & the storywriter guide!

Here are some small queries / nits to address:

We have updated the game developer guide but we cannot push our changes of the storywriter guide to the general repo.