QuizMenuTool Tutorial
This article is unfinished. You can help expanding it.
This guide explains how to use QuizMenuTool to create a custom Personality Quiz. The bulk of this guide will explain the use of the google sheets portion of the tool. A rudimentary understanding of SkyTemple scripting will be assumed, namely adding new acting scenes, and adding scenes to unionall.ssb. For help with these topics... TODO: Link supplemental resources or suggest #support.
Who QuizMenuTool is for
If either of the below points do not apply to you, you do not need QuizMenuTool.
- You would like to expand (or shrink) the list of starter options in the game.
- You would like to keep the personality quiz in the game, or edit the quiz directly.
If you only want to change the size of the starter list, and do not want the personality quiz (as if the SkipQuiz patch is applied), you should instead use StarterMenuTool, which is less powerful but requires much less work to set up.
Programs and Files
Required Programs and Files
General Spreadsheet Tips
Making a Copy of the Sheet
The above link does NOT grant edit access. In order to use the sheet, a copy will need to be made as follows:
First click the "File" button on the top left. Next, "Make a Copy" of the sheet. Finally, name the copy as desired.
Cell Color-Coding
Throughout the spreadsheet, most cells are color-coded. Here's a brief explanation of each color present in the sheet:
- Green Cells are for user input. If a cell is green, it is intended to contain input data.
- Grey Cells contain formulas. They will update automatically, and should not be edited.
- Orange Cells are for user outputs. If a cell is orange, it is intended to be exported elsewhere, such as to a SkyTemple script.
- Cells without a color or of an unspecified color are typically safe to edit. Always check for a formula first though!
Paste Values Only
This tab is the first which will require the use of "Paste Values". When this guide specifies that a copy/paste must "Paste Values", this means that the copied text is a formula, and the pasted text should not be a formula.
There are two ways to paste values, either by right-clicking the paste location and selecting "Paste Special" then "Values Only", or by holding shift as you paste.
Quiz Preamble Generator: A Good First Impression!
The Quiz Preamble Generator Tab as a whole exists to create the very beginning of the quiz.
Upper Panel
Most tabs in the sheet contain an upper panel of some kind, with various simple inputs and feedback on them:
The "Bottom Screen" and "Top Screen" inputs are the map ID that should be used for that screen's background. Similarly, the Background Music Name/ID is a BGM name (or number) of the BGM that should play throughout the quiz. The "White Space?" checkbox will attempt to add indents to the output ExplorerScript lines, making the output script more human-readable.
Preamble Text
This is the first of many direct inputs for ExplorerScript code. Due to the way spreadsheets store cell data, " " behave weirdly when present in the final script. Please use ' ' instead. This input is for the first set of dialogue before the questions actually begin.
Outputs
The orange output cell on this sheet is largely unimportant, but is present for debug purposes. It compiles the portions of the script using the inputs on this tab of the sheet.
Starter Selection Generator: Actually Adding the Starters...
This tab of the sheet is primarily for inputting data about the starters, or the personality pools they belong to.
Upper Panel
This upper panel contains 4 inputs, 3 of which are for Special Processes pertaining to starter selection. If other Special Processes have already been added, these Special Process IDs will need to be changed to free slots. The "White Space?" checkbox is the same as before, except for this tab of the sheet. The 4 grey cells are useful statistics about the input starters: how many different pools are used by the starters, how many species are present, and how many options there are for the hero and partner.
Personality Pool Input
Next, on the lower right is the nature "Pool" input. These contain the pool name, and the text that should be displayed if that pool is selected by the quiz.
The "Pool Name" field is only used by the Question Generator Tab, and will not show up anywhere in the final script. Modify these as desired as soon as possible, as it will be difficult to do so after designing the quiz questions. For best results, ensure all pool names are unique!
Starter Species Data
The bottom left segment of the sheet is the "Starter Species Data" input. This is part of a wider table, but each segment will be discussed individually.
While some of these fields should be intuitive, A brief description of each column is as follows:
- Species Name: The name of the species as you want it shown in the quiz. If the cell turns purple on entering a species name, this means the Pokémon could not be found in Vanilla Translation Strings. French and German Translations will need to be added by hand, or all strings involving the Pokémon will need to be translated manually.
- Species ID: The ID in SkyTemple of the Pokémon. [TODO: Explain how this is affected by ExpandPokeList].
- Gender: The gender of the Pokémon, used to set the frame color, and to add "♂" and "♀" to the hero/partner selection list. 0 is Male, 1 is Female, and 2 is Genderless.
- Pool ID: The number of the Pool the Pokémon should be categorized under. Each Pool that could be chosen by the Quiz should have at least one valid Pokémon, or Bulbasaur will be selected as a failsafe. If the species are not sorted by Pool ID, cells will turn red. The sheet will produce invalid labels if this table is not sorted by Pool ID!
- Start w/ Vowel: If the Pokémon should be referred to as "...an [Pokémon]", check this box.
Talk Group & Role Exclusion
Continuing along the table, the next two subsections are for "Talk Groups" and "Role Exclusion". Both of these segments relate to either the hero, or the partner.
In the vanilla game, the hero and partner have differing dialogue depending on their species-specific "Talk Group". These columns are dedicated to assigning the talk group for the hero or partner if that row's species is chosen. While it handles pronouns for dialogue, especially in gendered languages, it also affects the way the partner's dialogue is written. It does the same for the hero's dialogue, but in the English localization it only affects 2 lines in the entire game ("Whoa" <-> "Wah", "All right" <-> "OK"). This is how they are used in vanilla:
| # | Used By | Notable Species | Description |
|---|---|---|---|
| 1 | Partner | Male Squirtle/Totodile/Chimchar/Meowth/Munchlax | More Masculine/"Rural" Dialogue. (Refers to self as "Oira" in Japanese) |
| 2 | Partner | All other Male Pokémon | More Masculine/"Boyish" Dialogue. (Refers to self as "Boku" in Japanese) |
| 3 | Partner | All Female Pokémon | More Feminine Dialogue. (Refers to self as "Watashi" in Japanese) |
| 4 | Hero | All Male/Genderless Pokémon | Uses Masculine Pronouns |
| 5 | Hero | All Female Pokémon | Uses Feminine Pronouns |
The "Role Exclusion" checkboxes blacklist the row from being an option as a hero or as a partner respectively. Certain Pokémon, particularly Meowth and Munchlax, are unable to be heroes in the vanilla game. This section is how to replicate that feature of the original quiz.
Fuwarante Blacklist
Finally, on the far end of the table, is the Fuwarante Blacklist inputs. These are perhaps the most complicated portion of this tab of the sheet.
Each column corresponds to a bit of the script variable $BIT_FUWARANTE_LOCAL. If the matching flag is on, the starter in that row cannot be chosen. This will be elaborated on further in the "Question Loop Generator", but this is a brief explanation of what the bits represent by default:
| Bit | Description/Use Case |
|---|---|
| 0 | If enabled, $PLAY_OLD_GAME will be true, meaning the player answered that they have played Time/Darkness before. |
| 1 | If enabled, the player has played EoS before, according to a custom starting question. |
| 2 | If enabled, the player has participated in a Mystery Mail event before, according toa custom ending question. |
| 3 | If enabled, the player claimed to be female in the final gender question. Enable for male starters. |
| 4 | If enabled, the player claimed to be male in the final gender question. Enable for female starters. |
Outputs
Once again, the orange output cells on the far right of this sheet are largely unimportant, but are present for debug purposes. It compiles the portions of the script using the inputs on this tab of the sheet.
Question Loop Generator: Before, After, and For How Long?
Upper Panel
The upper panel of this sheet mostly consists of inputs, though the single output is a reminder of how many unique pools are used by the Starter Selection Generator. The input directly left of it is for telling the Question Loop Generator how many pools are in use, and should be changed to match the display. On the upper left of the panel, there are inputs for how many questions the game should ask the player, and how many questions will be written for the quiz to randomly choose from. In vanilla, there are 64 possible questions, and 8 will be given to the player.
The bottom row consists of checkboxes to enable/disable the Custom/Standard First and Last Questions, such as the Gender Question and the Time/Darkness Question, which boosts recruit rates for certain species if you answer yes, and adds points to certain pools containing sky-exclusive Pokémon.
ExplorerScript Pre/Post Quiz Questions
Room for an additional question before and after the quiz has also been made, which along with the Gender and Time/Darkness questions can be modified in the below ExplorerScript inputs:
These are the primary use-cases for the Fuwarante Blacklist described above.
Question Generator: Multiple Choice Monotony
About Question Templates
This tab of the sheet is dedicated to the design and storage of the individual random questions in the quiz. The way this sheet works revolves around "Question Templates" that store the question text, question number, answer text, pool ID, and points for that pool ID. Below is an example of a Question Template, and how it translates to question data:
| Question Text | Question # | |||||||
|---|---|---|---|---|---|---|---|---|
| Do you prefer to be busy or to have a lot of free time? | 35 | |||||||
| Answer Text | Pool 1 ID and Pts | Pool 1 ID and Pts | Pool 1 ID and Pts | Pool 1 ID and Pts | ||||
| Being busy. | 11 | 4 | 8 | 2 | - | - | - | - |
| Free time! | 9 | 4 | - | - | - | - | - | - |
| In between. | 12 | 4 | - | - | - | - | - | - |
Question Template Input
On the far left, is an input for an existing Question Template.
The "Use Question Template Input" checkbox tells the sheet whether or not to use the Question Template provided. When writing questions entirely from scratch, disable this checkbox. When modifying existing questions, enable the checkbox, and paste in the Question Template. This will subsequently auto-fill the Question Data Inputs with the data within the template. If the auto-filled data itself needs to be altered, you will need to copy and paste values the data, then disable the checkbox.
Question Data Inputs
The Question Data Inputs Area should seem relatively intuitive. The question text is at the top, the answers are beneath, and up to 4 Personality Pools can gain points from each answer choice. The White Space checkbox is identical to the previous tab, and the question index is just the internal "ID" of the question. It should be incremented for each new question created, and will translate to the ID of the switch case in the final code. Note that the drop-down for the Pool Names is sourced from the Pool Names column of the Starter Selection Generator, and any changes to that list after creating the questions may lead to problems. With the current setup of the sheet, each question is limited to a maximum of 26 answer choices, but this limit is arbitrary, and can be circumvented by editing the question template manually, and pasting it in the Template List. In the event that a single question requires more than 26 choices, please ping happylappy in a support thread.
Question Template Output & Template List
Finally, once the question is complete, a template for the question will be created in "Question Template Output".
Before moving onto the next question, copy the template output, and Paste Values in the corresponding slot on the "Question Template List". By default, templates for each vanilla question are already in the Question Template List, ready to be edited or modified by copying and pasting into the Question Template Input. The Script Output Column is again for debug purposes, and is read automatically by another tab of the sheet.
Personality Pool Selection Generator: Gerrymandering and Tie-Breaking
Once the quiz itself is completed, the points need to be tallied, so that a winning pool can be selected. The exact way that this happens in vanilla is a tad complicated, especially when it comes to breaking ties. Here are the steps that occur in vanilla:
- Points are added to pools containing Sky-Exclusive Starters if the player has played Time/Darkness.
- If Male is chosen for the gender question, +4 Points are added to Relaxed, Hasty, and Sassy. (Phanpy, Shinx, and Riolu)
- If Female is chosen for the gender question, +4 Points are added to Relaxed and Jolly. (Vulpix and Eevee)
- The highest pool is found, and chosen.
- If there is a tie, it is broken by adding a random number (0-19) to each, and rescoring the points.
- If there is STILL a tie, it chooses the smallest pool it can.
This tab of the sheet serves to implement these two features in a customizable way.
Upper Panel
About half of the upper panel is actually new this time. The "White Space" and "Number/# of Pools In Use" are unchanged, except they apply to this sheet.
The checkbox for "Do Pool Tinkering" enables/disables the Pool Tinkering portion of this sheet, while the "Maximum Tiebreaker Points" input determines the random value added to tied pools to decide a victor. Larger numbers result in less chance of a secondary tie, but could result in overflow for certain pools.
Pool Tinkering
As stated above, the vanilla quiz favors pools with Sky-Exclusive Starters for the specified gender if they've played Time/Darkness. Through checking the BIT_FUWARANTE_LOCAL flags from the "Question Loop Generator", we can mimic this effect.
On the far left, are the IDs of the two flags that should be checked (without modification, this could be 0 for "Time/Darkness", and 3/4 for "Male/Female"). Depending on if the 1st and 2nd flags are true (1), or false (0), the selected pools (as many as needed) will gain the specified number of points. In order to accommodate for the "Surprise Me!" gender option, 2 points are given for male, 2 for "not male", 2 for "female", and 2 for "not female", in order to influence every pool containing a sky-exclusive starter. (A similar process is done for the Time/Darkness exclusive starters I've added to my example quiz, if the player has NOT played time/darkness). Up to 10 slots are present for pool tinkering, though more could be added if there is a pressing need.
Aura Bow Generator: Fortune Telling and Color Theory
The Aura Bow Generator serves to emulate the cinematics of the vanilla aura bow portion of the quiz. In addition to simply detecting when and for how long the player is touching the Aura Bow, the actual bow color needs to be determined! For the vanilla quiz, the process is as follows:
- Use DS Favorite Color (75% Chance): If the DS Favorite Color is selected, the user's favorite color will match the color of the bow.
- Use DS Mac Address (25% Chance): If the Mac Address is selected, then "mac_address & 0xF" determines the color of the bow.
This functionality can be replicated by QuizMenuTool, and the chances can even be altered!
Upper Panel
The Aura Bow Generator's Upper Panel is one of the largest of every tab, though many of these inputs are similar to prior tabs of the sheet. The top left input boxes are Special Process IDs for the 4 Special Processes needed to emulate the Aura Bow portion of the quiz, and the "White Space?" Checkbox is the same as always. The "Aura Bow Output" on the top right is the final script output for this tab, unnecessary outside of debug purposes.
Beginning with the bottom left of the panel, there are 4 map LEVEL names. "Bottom 1" is for the background while touching the Aura bow, Bottom Screen 2 is for the presentation of the colored Aura Bow, and the Bottom/Top Screen 3 is the backgrounds that the script should end with, when transitioning to the starter reveal. Finally, on the bottom right of the upper panel is the "Touch Screen Aura Bow Object Name". Per the name, this is the name or ID of the object that should be present on the bottom screen, that will animate when the player touches it. The last three digits of the object seem to vary depending on unknown factors, so be sure to verify that yours matches by inspecting this object in M00A01A with SkyTemple.
Aura Reading Panel
Beginning on the lower left of the tab, the Aura Reading Panel consists of 3 ExplorerScript code segments, which play before the blank aura bow fades in, after the aura bow fades in, and if the player lets go of the touch screen too quickly.
At the very bottom of this panel, there are inputs for dialogue in all 5 languages that will play during the aura reading process. Unlike most text in the quiz, this string must be translated here, as every localization takes a different amount of time to print the dialogue. The length of time the touch screen should have been held for is calculated for each [W:X] text tag, and compared against the actual length of time the touch screen was held. Customizing this text string is possible in the box, so these calculations must be done by the sheet. If your hack is for a US ROM, or will be english-only, disable the "Use EU Strings" Checkbox. "Expected Text Speed (# of chars per frame)" should be the speed your dialogue prints at in SkyTemple. This will ensure that the actual length of the text is properly accounted for in the calculation. "Touch Screen Frame Tolerance" is a grace period for letting go of the bow. This is necessary for certain emulators, damaged touch-screens, failure to account for the dialogue box opening/closing, etc. Feel free to adjust as desired, such that the quiz is possible to complete.
Bow Selection Panel
Finally, the Bow Selection Panel handles the actual selection and presentation of the Aura Bow.
The upper left of the panel is for assigning weights to the three methods for selecting a bow color: DS Favorite Color, DS MAC Address, or a custom block of code. Note that these weights must be integers or the sheet will generate invalid code. For convenience, the percent chance of each option is computed by the sheet, based on the weights and total weight. The ExplorerScript input for the custom bow selection is on the right of this panel, and on the bottom left is the flavor-text for each bow color.
Variable Cleanup & End-Cap Generator: Nearly Finished!
This tab of the sheet aims to clean up the bevy of variables used by the quiz, and prep the game for actually running. Since QMT uses a majority of the script variables the game has to function, this tab resets them all back to what they should be at the beginning of a save file, now that the quiz no longer needs them. If some part of the quiz needs to be remembered, such as the color of the aura bow, whether the player has played Time/Darkness, or the winning Quiz personality pool, that needs to be preserved in this tab. In addition, this is the tab where the starters are officially initialized, which allows them to be nicknamed.
Upper Panel
This tab ALSO has an upper panel! The number of pools to clear should ideally match the number of pools in use. "White Space" does the same thing it has up to this point, and the far right output cell is read elsewhere, and only exists for debug purposes.
In the center of the panel are three new checkboxes. "Name Partner?" and "Name Hero?" should be somewhat intuitive, they enable/disable the ExplorerScript inputs for naming the hero and partner respectively, which will be elaborated on below. Finally, "Set $VERSION to 1?" sets the "$VERSION" script variable to 1 at the very end of the script. Without ASM modification, saving the game with this variable as anything besides 1 results in a "corrupt" save file. In the absence of a strong reason otherwise, this box should remain checked.
Hero Name, Partner Name, & Closing Remarks
Script Variable Preservation Panel
