MacDevCenter    
 Published on MacDevCenter (http://www.macdevcenter.com/)
 See this if you're having trouble printing code examples


Building Custom iQuiz Data

by Erica Sadun
04/30/2007

If you spend any time over at iTunes, you might have noticed a new iPod game called iQuiz. Apple is promoting it heavily now. It retails for just $0.99, a bargain by anyone's standards. iQuiz offers interactive trivia challenges that play like TV game shows. Very flashy, very easy to use, and a big step up from the iPod's built-in and rather worn out Music Quiz.

What sets iQuiz apart from the ordinary (beyond its especially affordable price and its great interactive style) is that it allows end-users to create their own custom games and run them using the iQuiz interface. This means that you can create your own question database to play with on your iPod or to distribute to friends, colleagues, or students to play on their iPods. In this article, you'll discover how to create your own custom data sets for iQuiz.

Building Basic iQuizzes

If you pop over to Apple's iQuiz web page, you will find a link to game maker Aspyr. Aspyr just introduced a free utility that allows end-users to design iQuizzes. Its iQuiz Maker utility interactively builds iQuiz-compatible files (Figure 1). You add a new question. You type in the question text. You add some answer text. You indicate which answer is correct. Lather. Rinse. Repeat. Save to disk. iQuiz Maker is easy to use and offers all the flexibility and configurability of your average rock.

iQuiz Maker
Figure 1. Aspyr's iQuiz Maker program offers a GUI that allows you to interactively create quiz questions.

If you want to convert an existing trivia database to an iQuiz or to programmatically create test material, iQuiz Maker is not the answer. You must type in each question using Aspyr's UI. There's no way to import data files. Sure, that's fine for a 5- or 10-question quiz (and it's a wee bit tedious even for short quizzes), but it's not so fine for quizzes that run longer than that and involve more customization of iQuiz UI features.

Custom Quiz Materials

Fortunately Apple offers a way to make an end-run around iQuiz Maker. Apple provides a basic markup language that lets you build quiz materials without a GUI. iQuiz can parse and execute certain text files. This lets you build your questions programmatically, automating much of the iQuiz creation process to produce more robust and interesting databases.

The text-based data files you create are not compiled or put into any unreadable form. That means that this is not a particularly good way to produce a for-pay product, but it works well for recreational and educational users. Two target areas that work particularly well in this arena are trivia games and training drills. Drills can include mathematics, languages, history, and any other fact-based academic subject.

iQuiz also lets you add customized TARGA graphics files. These files can supplement or replace nearly all the graphics in the iQuiz game. Customizable images include backgrounds, buttons, arrows, and even the spinning countdown images shown at the start of the game. Whenever iQuiz detects an image with a certain name in your quiz folder (e.g., lost_background.tga is the background image for the "You Lose" screen), it replaces the standard picture with the custom one. You don't have to update or change the iQuiz graphics, but the functionality is there if it so suits you.

Tip: The iQuiz language is superficially similar to the one used for iPod Notes, which you can read about in Mac DevCenter's Building Interactive iPod Experiences.

Creating the Quiz File

Custom quizzes are stored in a file called trivia.txt. This file consists of a header followed by a list of questions. The header provides basic information about how the quiz operates including the name of the quiz, the number of questions to ask for any session, and so forth. The questions offer the text of the challenge and their possible answers. You do not have to add questions in any particular order, as iQuiz selects them randomly from your text file.

The Header

The iQuiz header consists of key/value pairs. Each key, or "tag" as Apple calls them, appears in uppercase on a single line. The next line sets the value for the tag. Here's the header for a quiz I recently wrote. It's called "Multiplication Adept" as I state in the TITLE tag, and it drills children on multiplication math facts from 2 x 2 up to 10 x 10. It's one of several multiplication quizzes that I wrote, all of which appear in the iQuiz menu under a "Math Quizzes" heading, i.e., the GROUP tag. In the quiz, children are asked 10 multiplication questions, set by the ASK tag. If they get three questions wrong (the LOSE tag), the game ends and they are prompted to try again (LOST MESSAGE).

TITLE
Multiplication Adept (2 - 10)

GROUP
Math Quizzes

ASK
10

LOSE
3

WON MESSAGE
You're a Multiplication Genius!

LOST MESSAGE
Sorry! Too many wrong answers. Try again next time!

VERSION
1

Game Tags

Here's a quick rundown of the game tags you can use in your trivia.txt file:

Tip: I'm not a big fan of the "LOSE" feature. I find that disabling it (set the LOSE value to 0) leads to better trivia game play especially for challenging trivia sets.

Color Tags

In addition to the game control tags listed above, iQuiz lets you specify optional color tags to control the text color for various UI text elements. Colors are comma-separated RGB triplets using values between 0 (darkest) and 255 (brightest). For example, to set the score color to a medium green:

SCORE COLOR
0, 128, 0

Color tags include the following:

QUESTION COLOR (defaults to black: 0, 0, 0),
ANSWER COLOR (black: 0, 0, 0),
EXPLANATION COLOR (white: 255, 255, 255),
SCORE COLOR (light grey: 191, 191, 191),
COUNT COLOR (light grey: 191, 191, 191),
MENU TITLE COLOR (bright blue-green: 50, 255, 255),
MENU BUTTON COLOR (black: 0, 0, 0),
MENU TITLE COLOR (dark grey: 64, 64, 64),
STAT LABEL COLOR (black: 0, 0, 0), and
END MESSAGE COLOR (black: 0, 0, 0).

The Questions

A list of questions follows the header and forms the rest of the trivia.txt file. You can add up to a thousand questions per game. A multiple-choice game of, say, 500 questions with 4 answers each might run as long as 4,000 lines of text.

iQuiz supports three kinds of questions: multiple choice, true/false questions where the answer is TRUE, and true/false questions where the answer is FALSE. In the latter case, you provide an explanation of why the answer was false. This explanation displays after a choice is made, regardless of whether the answer was correct or not. Pedagogically that's a great thing. Not only do you respond to the user's choice, but you reinforce the correct fact at the same time.

Here are examples of all three kinds of questions. Multiple-choice questions start with the MC tag on a single line. This is followed by two to four answers. The last line is a number with the correct answer choice. Leave an empty line before the next question.

MC
What color is the 5 ball in pool?
Blue
Green
Orange
Red
3

True/false questions start with the TF tag on a single line followed by the question on another line. If the answer is true, the next line is TRUE followed by an empty line. If the answer is false, the next line is (theoretically optional) text that explains the correct answer. This is followed by FALSE and then an empty line.

TF
Is 2 multiplied by 3 equal to 6?
TRUE

TF
What do you get if you multiply 2 by 4? Is it 10?
2 X 4 = 8
FALSE

Feel free to mix and match question types in your trivia.txt file, in any order you like. You can include all true/false questions, all multiple choice, or any combination of the two.

Tip: Internationalize your game by providing localized trivia files. Just add the standard Apple two-letter language tag to a translated trivia.txt file. For example, trivia-it.txt for the Italian version, trivia-fr.txt for the French version, and so on. You can localize game materials to any standard Apple language. The built-in Apple iQuiz menus, however, can only be localized to English, Dutch, French, German, Italian, Japanese, and Spanish.

Custom Graphics

iQuiz looks for custom graphic files in the same trivia pack folder it finds trivia.txt. When it finds files with certain names, it replaces the default graphics with the custom ones. You can only use TARGA images with iQuiz, and Apple specifies the allowable dimensions for each kind. It's very easy to put these files together using an image editor like Photoshop but it's also a lot of work. I'd recommend you skip custom graphics unless you have a pressing need to create a unique visual signature for your quizzes.

You'll find a complete list of file names and specifications at the Apple iQuiz web page.

Tip: The iQuiz 1.0.ipg file in your iPod Games folder is actually a zip archive. Copy it to a new folder and unzip it to gain instant access to the original source images (and lots of other source material). Use these graphics as a jumping-off point for your adaptations.

Building Questions Programmatically

Now that you've seen how to create the trivia.txt file for custom game packs, the next challenge comes from filling that file with compelling content. Educational material in an existing digital form provides a rich source of questions. (Apple Learning Interchange 2007 seems to agree.) For example, with a list of foreign language words and their proper gendered form (la mano, i bimbi, lo zoo), you can easily build a program or script to scramble the forms with possible errors, e.g.:

MC
Which is correct?
la scuola
il scuola
lo scuola
le scuola
1

Here are a few key factors that will help you put together effective quizzes.

Quiz Generation Example

Here is the C source of my multiplication quiz, demonstrating all of the above points in turn. (And yes, my use of variable names is terrible.) To use, compile and then paste the results into the bottom of a trivia.txt file.

// Erica Sadun
// April 2007
// 
// makequiz -- makes a Multiplication quiz with question variations
//

#include <stdio.h>
#include <stdlib.h>
#include <time.h>

//
// Provide 4 answers for every question. Include an answer key.
//

void fourAnswers(x, y)
int x, y;
{
   int ans[7], i, a, b, tmp;

   // Seven "wrong answer" patterns based on common mistakes
   ans[0] = (x * y) - 1;
   ans[1] = (x * y) + 1;
   ans[2] = ((x + 1) * y);
   ans[3] = ((x - 1) * y);
   ans[4] = (x * (y + 1));
   ans[5] = (x * (y - 1));
   ans[6] = ((int) ((x * y) / 10)) + ((int) ((x * y) % 10) * 10);

   // Allow dupes of wrong answers but not of right ones by adding 
   // random, positive number to answers that dupe the correct one
   for (i = 0; i < 7; i++)
      if (ans[i] == x * y) 
         {ans[i] += (rand() % 80) + 1;}

   // Shuffle answers randomly multiple times
   for (i = 0; i < 30; i++)
   {
      a = (int)(rand() % 7);
      b = (int)(rand() % 7);
      tmp = ans[a]; ans[a] = ans[b]; ans[b] = tmp;
   }

   // Insert correct answer randomly into one of first 4 items
   a = (int)(rand() % 4);
   ans[a] = x * y;

   // Print question in trivia.txt format using one of four styles.
   printf("MC\n");
   b = (int)(rand() % 4);
   if (b == 0) 
      {printf("What is %d X %d?\n", x, y);}
   else if (b == 1) 
      {printf("What do you get if you multiply %d by %d?\n", x, y);}
   else if (b == 2) 
      {printf("What is %d times %d?\n", x, y);}
   else 
      {printf("What is %d multiplied by %d?\n", x, y);}

   // Print out answers. 4 per question, one per line.
   for (i = 0; i < 4; i++) {printf("%d\n", ans[i]);}

   // Print the correct answer index and extra CR
   printf("%d\n\n", a + 1);
}

main()
{
   int x, y, z;
   srand(time(NULL));

   for (z = 0; z < 3; z++) // three sets of questions
     for (x = 2; x <= 12; x++) // multiply 2x2 up to 12x12
      for (y = 2; y <= 12; y++)
      {
        fourAnswers(x,y);
      }
}

Other Sources for Questions

If you do not have data sources on hand, you can easily google up data sets for both educational and entertainment trivia. Search, for example, for free public-domain or open source "pub quizzes" and "trivia databases." These, when put into the proper format, make excellent iQuiz games. In my searches, I found several open source trivia databases including these sets, which are part of the MisterHouse project.

Assembling and Installing Trivia Packs

To install a game, start by creating a new folder. Name it with the title of your trivia pack. Place the trivia.txt folder inside along with any custom TARGA image files.

After purchasing and downloading iQuiz, iTunes automatically creates an iPod Games/iQuiz 1.0 folder inside your iTunes folder (typically found in ~/Music). Drag the trivia pack folder you just created into the iQuiz 1.0 folder and then sync your iPod. iTunes will automatically load your new trivia pack onto your iPod.

Unmount your iPod and launch iQuiz. Your new trivia packs appear in iQuiz's "new game" menu (if didn't enable the "HIDDEN" tag, that is). As you wait for your Quiz to load, you'll see a pulsing iQuiz logo. If you mess a little bit with the scroll wheel when you see this, you'll be pleasantly surprised by the rubber-band-like results.

Tip: If you're curious and you've enabled disk access, you'll find your games in /Volumes/(name-of-your-iPod)/iPod_Control/GameData_RO. One of the folders in that directory--possibly 11002--contains the iQuiz game. In that folder, look under UserTrivia/Packs to discover your user-installed game sets.

Examples

I've put together a bunch of sample files to accompany this article. These include three variations on the multiplication game, the C source used to create them, and a set of six trivia packs built using trivia data from the Net that was represented as open source and/or public domain on the sites I downloaded from. (If anyone knows otherwise, please let me know and I'll remove them.)

Conclusions

In this article, you've seen how to create custom iQuiz files. You can go the simple route by using Aspyr's easy-to-use iQuiz Maker utility, or you can go the slightly harder but ultimately more rewarding route by building your data files from scratch. Once again, Apple has provided a flexible and useful tool that goes way beyond expectations and offers exciting possibilities for anyone willing to get up to speed.

If this article inspires you to build your own trivia packs, please leave a link and a description in the comments.

Erica Sadun has written, co-written, and contributed to almost two dozen books about technology, particularly in the areas of programming, digital video, and digital photography.


Return to Mac DevCenter.

Copyright © 2009 O'Reilly Media, Inc.