Adding an Options Menu
| This article is a Work in Progress. If you have any feedback or suggestions, please leave a comment in the discussion page. |
Setting Up Your Plugin To Use An Options Menu
Creating an Options Menu is a good way to keep your plugin modular without having to make multiple plugin files available. It allows the user to change settings in-game.
Depending on how each setting works, it will utilise a slightly different menu structure. In order to make it clear which menu structure should be used for each setting, I'm going to sort them into four categories:
- General Toggle Settings, or GTs. GTs affect the game as a whole, and can be toggled on and off. They have the simplest menu structure of all setting types, and can be toggled simply by clicking on their button in the main menu.
- General Select Settings, or GSs. GSs affect the game as a whole, and have a range of values available to them. Their menu structure consists of a button on the main menu, and a sub-menu in which the user can select a new value for them. Note that these values can include an "off" value.
- Object-Specific Toggle Settings, or OTs. OTs affect specific objects, and can be toggled on and off. Usually, many different objects will have their own versions of each OT. The menu structure used by OTs requires the user to select the appropriate object before toggling the OT by pressing the relevant button.
- Object-Specific Select Settings, or OSs. OSs affect specific objects, and have a range of values available to them. OSs have the most complex menu structure of any setting, in that the user must first select the relevant object, then the setting, and then choose a new value for the setting.
Although each of these categories utilises a slightly different menu structure, they can all be incorporated into the same Options Menu.
Declaring Your Variables
The first step in making these settings editable is to define them in a "Variable Reservoir", or "VR" Quest Script. A VR script is a script that contains no Begin/End blocks, but consists entirely of variable declarations. This example VR script, which is attached to the "Start Game Enabled" quest "ExampleVRQuest", will be used in this tutorial:
ScriptName ExampleVRSCRIPT ; ============================================== ; General Settings short sGT1 ; Default 1 - On short sGS1 ; Default 3 ref rGS2 ; Default ExampleRef ; ============================================== ; ============================================== ; Object-Specific Settings ; Item1 short sItem1OT1 ; Default 0 - Off short sItem1OS1 ; Default 5 ; ==============================================
Note that it consists entirely of variable declarations, and will never actually run. That means that these variables need some method of being initialised to their default values - at the moment they are all 0.
Keep in mind that your variables should be named according to their function. The variable names I have used here were chosen to illustrate the type of setting they are used for, and are not practical.
You should name your variables according to the setting that they affect, and the object that they are associated to (for OTs and OSs).
Initialising Your Variables
To initialise these variables to their default values, we are going to add a result script to Stage 1 of our VR quest. A result script is different from regular scripts in that it can't declare any variables of its own, and it doesn't contain any Begin/End blocks. Instead, a quest result script will run once when its quest reaches the stage that it is attached to, provided that the conditions assigned to it evaluate to true.
This is the result script that would used to initialise the variables in ExampleVRSCRIPT:
set ExampleVRQuest.sGT1 to 1 ; On set ExampleVRQuest.sGS1 to 3 set ExampleVRQuest.rGS2 to ExampleRef set ExampleVRQuest.sItem1OT1 to 0 ; Off set ExampleVRQuest.sItem1OS1 to 5
Note that, even though variables initialise to 0 anyway, we have set sItem1OT1 to 0 in this result script. This ensures that a "Defaults" option can be included in the Options Menu that can set or reset all settings to their default values with a simple "SetStage ExampleVRQuest 1" command.
Of course, we need some way in which to run this result script initially - as it will not be run until our VR quest reaches Stage 1. Attaching the result script to Stage 0 (which quests default to when they first start running) won't work, we need to actually use "SetStage ExampleVRQuest 1" somewhere.
To do this, we will create another "Start Game Enabled" quest, this time in the interest of initialising our variables. The quest script attached to ExampleInitQuest will look like this:
ScriptName ExampleInitSCRIPT Begin GameMode SetStage ExampleVRQuest 1 StopQuest ExampleInitQuest End
As you can see, it will run only once - using "SetStage ExampleVRQuest 1" to initialise our settings to their default values.
Utilising Your Variables
At the moment, all our variables are doing is sitting in our VR quest. If we make any changes to their values they won't affect the plugin in any way.
Tying these variables to settings will always depend on just how the setting works, and is generally done differently depending on the category that the setting belongs to.
GTs
General Toggle settings are usually used to toggle features on and off. Therefore, the most common way of linking GTs to their feature is to simply enclose the relevant code in an if statement:
if ExampleVRQuest.sGT1 ; Function code goes here endif
As you can see, enclosing the relevant code in an if statement like the one above will cause the feature to be present if and only if ExampleVRQuest.sGT1 is not 0. This will enable the feature to be toggled on and off by toggling ExampleVRQuest.sGT1 on and off.
For General Toggle settings, the relevant feature's code will usually be present in a single place - usually a quest script. This means that only one section of code usually needs to be enclosed in an if statement.
GSs
General Select settings are usually used to change how a certain feature works. They will usually be seen in calculations, or as parameters for certain functions. For example:
ExampleVRQuest.rGS2.KillActor ExampleVRQuest.rGS2 ExampleVRQuest.sGS1
In the above code, ExampleVRQuest.rGS2 controls which actor will be killed, and ExampleVRQuest.sGS1 controls which limb will be dismembered. They can also be used to switch on/off certain aspects of the feature:
- If ExampleVRQuest.sGS1 is set to -1, no limb will be dismembered
- If ExampleVRQuest.rGS2 is set to point to a dummy reference (i.e. one the player will never encounter), no actor will be killed.
OTs
Object-Specific Toggle settings are usually used to toggle features on and off. Therefore, the most common way of linking TTs to their feature is to simply enclose the relevant code in an if statement:
if ExampleVRQuest.sItem1OT1 ; Function code goes here endif
As you can see, enclosing the relevant code in an if statement like the one above will cause the feature to be present if and only if ExampleVRQuest.sItem1OT1 is not 0. This will enable the feature to be toggled on and off by toggling ExampleVRQuest.sItem1OT1 on and off.
For Object-Specific Toggle settings, the relevant feature's code will usually be present in a multiple places, as multiple objects will have their own copy of the feature. This means that many sections of code usually need to be enclosed in the same if statement.
OSs
Object-Specific Select settings are usually used to change how a certain feature works. They will usually be seen in calculations, or as parameters for certain functions. For example:
player.AddItem Item1 ExampleVRQuest.sItem1OS1
In the above code, ExampleVRQuest.sItem1OS1 controls how many of Item1 is added to the player. If sItem1OS1 is set to 0, none will be given to the player, effectively switching the feature off.
Creating An Options Menu
Now that your plugin is set up for using an options menu, you can finally add the menu to your plugin. To do this, you'll need to do two things:
- Give the player access to the menu
- Create the menu
Before we create the actual menu, we'll have to set up the plugin so that the player is able to access the menu. By doing this before we start working with the menu code, it'll make testing a whole lot easier.
The method I'm going to describe here is not the only method, although it is the method that I prefer. It consists of two stages:
- Give the player a "Menu Key" - A piece of equipment which the player can equip in order to open the menu.
- When the player equips the Key, a token will be added to them. A token is a piece of unplayable (invisible to the player) equipment, and in this case will contain the script that controls the options menu.
Before we can use the Menu Key, we're going to have to make it. It's going to be a piece of armour with no Biped Objects (slots) so that equipping it won't force anything else to be unequipped. It's also going to be a quest item, so the player can't lose it anywhere (this also has the side effect of preventing the player from attaching it to a hotkey).
Remember when we initialised all our variables by using a SetStage command to run a result script? Now we're going to go back to that result script now and add three more lines:
if player.GetItemCount ExampleMenuKey == 0 player.AddItem ExampleMenuKey 1 endif
Now, when our variables are first initialised, the Menu Key that we just made will be automatically added to the player.
When the Menu Key is equipped, we want it to run some code that adds a token to the player, but before we can do this we have to make the token. It's also going to be a piece of armour, but unlike the Menu Key it's going to have the "playable" flag unchecked. This ensures that the player can't see it in their inventory.
Now that we've created the token, we can write a script for the Menu Key that adds the token to the player's inventory. Because the Menu Key is a quest item, it can't be given a hotkey - meaning that the player has to equip it manually from their inventory. If you want the menu to open right then and there, this script will suffice:
ScriptName ExampleMenuKeySCRIPT short sDoOnce Begin OnEquip set sDoOnce to 1 AddItem ExampleMenuToken 1 1 End
However, I personally prefer to have the menu open after the player has put away their Pip-Boy. To do this, a timer will need to be used so that the menu doesn't appear as soon as the player starts to put away their Pip-Boy (that's when the game returns to GameMode). It takes about half a second for the player to put the Pip-Boy away, so let's use a script like this:
ScriptName ExampleMenuKeySCRIPT short sDoOnce float fTimer Begin OnEquip ; Don't need to check MenuMode here, as Quest Items can't be attached to hotkeys set fTimer to 0.5 ; It takes about 0.5 seconds to put the Pip-Boy away set sDoOnce to 1 End Begin GameMode if sDoOnce == 1 if fTimer > 0 set fTimer to fTimer - GetSecondsPassed ; Count down to 0 else ; Once the Pip-Boy has been put away, open the Options Menu player.AddItem ExampleMenuToken 1 1 set sDoOnce to 0 endif endif End
That's looking very nice now, but because the menu is being opened in GameMode you may also want to prevent the player from opening the menu while they're in combat. To do this, you'll need to check whether or not the player is in combat when they equip the Menu Key, and unequip the Key without adding the token if this is the case.
ScriptName ExampleMenuKeySCRIPT short sDoOnce float fTimer Begin OnEquip ; Don't need to check MenuMode here, as Quest Items can't be attached to hotkeys if player.IsInCombat == 1 ShowMessage ExampleNoMenuCombatMsg ; Prevent the player from opening the menu ; during combat player.UnequipItem ExampleMenuKey 0 1 else set fTimer to 0.5 ; It takes about 0.5 seconds to put the Pip-Boy away set sDoOnce to 1 endif End Begin GameMode if sDoOnce == 1 if fTimer > 0 set fTimer to fTimer - GetSecondsPassed ; Count down to 0 else ; Once the Pip-Boy has been put away, open the Options Menu player.AddItem ExampleMenuToken 1 1 set sDoOnce to 0 endif endif End
Now that that's set up, all that's left is the actual Menu script, which will be attached to the token.
The main difference between a single-level menu and a multi-level menu is that the latter requires navigation - the script needs to remember the path that the player took to get to where they are. Our script will achieve this by having a "sMenuLevel" variable to store the current level of navigation, and giving each level of navigation its own "sButton" variable. That way, the script can remember which buttons the player pressed on each level of navigation.
The example menu that I'm going to use for this tutorial will have four levels, each with their own sButton variables:
- Level 0 - Initialisation->Introduction Message
- Level 1 - Introduction Message->Main Menu
- Level 2 - Main Menu->Sub Menu
- Level 3 - Sub menu->Settings
The basic structure of the script consists of one big GameMode block filled with a list of "if" statements checking the values of sMenuLevel and the various sButton variables. At the highest level, it only checks sMenuLevel:
ScriptName ExampleMenuSCRIPT short sMenuLevel ; Records the current depth of the ShowMessage framework ; 0 - Initialisation -> Introduction Message ; 1 - Introduction Message -> Main Menu ; 2 - Main Menu -> Sub Menu ; 3 - Sub Menu -> Setting ; This GameMode block contains all of the ShowMessage framework Begin GameMode ; ================================================= ; INITIALISATION --> INTRODUCTION MESSAGE ; ================================================= if sMenuLevel == 0 ; Show Introduction Message endif ; ================================================= ; INTRODUCTION MESSAGE --> MAIN MENU ; ================================================= if sMenuLevel == 1 endif ; ================================================= ; MAIN MENU --> SUB MENU ; ================================================= if sMenuLevel == 2 endif ; ================================================= ; SUB MENU --> SETTING ; ================================================= if sMenuLevel == 3 endif End
As you can see, the GameMode block is now divided up into four different segments. Which one runs will depend on the menu's current level of navigation.
The first section of the script runs when sMenuLevel == 0. Because variables are initialised to 0, this section will run when the script first runs. This section is also the simplest - all that happens in it is the introduction message is called, sMenuLevel is incremented to 1, and sButton1 is intialised:
; ================================================= ; INITIALISATION --> INTRODUCTION MESSAGE ; ================================================= if sMenuLevel == 0 ; Show Introduction Message ShowMessage introMessage set sMenuLevel to 1 set sButton1 to -1 endif
If you're wondering why I've included an Introduction message before the Main Message, it's useful if you have conditions for the buttons in the Main Menu that have to be initialised before each time it's opened. Usually, you'll use an OnAdd block in this script to initialise them.
Now, because we've set sMenuLevel to 1, the next section of the script will run. In this section, we need to check when the player clicks the button to continue from the Introduction message into the Main Menu. When this happens, the script will call the Main Menu, increment sMenuLevel to 2, and initialise the next sButton variable - sButton2:
; ================================================= ; INTRODUCTION MESSAGE --> MAIN MENU ; ================================================= if sMenuLevel == 1 if sButton1 == -1 set sButton1 to GetButtonPressed endif if sButton1 == -1 ; None of the buttons have been pressed yet Return else ; Show the Main Menu ; MainMenuMessage contains buttons corresponding to Sub Menus ShowMessage MainMenuMessage set sMenuLevel to 2 set sButton2 to -1 endif endif
The next section is a step up again in complexity. Unlike the Introduction Message, the Main Menu contains multiple buttons. That means that, in this section of the script, we need to check which button the player presses and update the Menu accordingly.
There are three types of button in this Main Menu:
- Buttons that take the player to a Sub Menu
- A "Defaults" button that sets all settings to their default values
- A "Done" button that closes the menu
If the player clicks on a Sub Menu button, we'll need to show the appropriate message, as well as increment sMenuLevel to 3 and set sButton3 to -1. If they click the "Defaults" button, we'll need to set all settings to their default values (with "SetStage ExampleVRQuest 1", remember?), then show the Main Menu again and reset sButton2 to -1. If the player clicks on the "Done" button, we'll remove the token from their inventory to close the menu.
; ================================================= ; MAIN MENU --> SUB MENU ; ================================================= if sMenuLevel == 2 if sButton2 == -1 set sButton2 to GetButtonPressed endif if sButton2 == -1 ; None of the buttons have been pressed yet Return elseif sButton2 == 0 ; Show the 1st Sub Menu ShowMessage SubMenu1Message elseif sButton2 == 1 ; Show the 2nd Sub Menu ShowMessage SubMenu2Message elseif sButton2 == 2 ; "Defaults" button - reinitialise all settings SetStage ExampleVRQuest 1 ShowMessage MainMenuMessage set sButton2 to -1 Return else ; "Done" button - close Options Menu player.UnequipItem OptionsMenuEquipKey 0 1 RemoveMe endif set sMenuLevel to 3 set sButton3 to -1 endif
As you can see, this section has the same organisation as the previous section. The only differences are that there are "Done" and "Defaults" buttons and, depending on which button the player pressed, a different menu is shown. We still use GetButtonPressed to check if a button has been pressed, and when one has we increment sMenuLevel and initialise the next sButton variable.
The next section is the final section for this example script - it's where the actual settings are changed. It differs from the previous level in that, when a button is pressed, we change a quest variable (remember them?) instead of showing a menu, and it has a "Back" button instead of a "Done" button.
There are two ways this section can be organised - by which setting was selected and by which sub-menu the player came through. In this example, the script is sorted by which sub-menu the player came through. The reason for this is that it is easier to visualise and can shorten the script a fair amount.
; ================================================= ; SUB MENU --> SETTING ; ================================================= if sMenuLevel == 3 if sButton3 == -1 set sButton3 to GetButtonPressed endif if sButton3 == -1 Return ; None of the buttons have been pressed yet elseif sButton2 == 0 ; The player came through the 1st Sub Menu if sButton3 == 0 ; The 1st setting was selected set VariablesQuest.Variable1 to (VariablesQuest.Variable1 == 0) elseif sButton3 == 1 ; The 2nd setting was selected set VariablesQuest.Variable2 to (VariablesQuest.Variable2 == 0) endif ShowMessage SubMenu1Message elseif sButton2 == 1 ; The player came through the 2nd Sub Menu if sButton3 == 0 ; The 1st setting was selected set VariablesQuest.Variable3 to (VariablesQuest.Variable3 == 0) elseif sButton3 == 1 ; The 2nd setting was selected set VariablesQuest.Variable4 to (VariablesQuest.Variable4 == 0) endif ShowMessage SubMenu2Message else ; "Back" button was pressed ShowMessage MainMenuMessage set sMenuLevel to 2 set sButton2 to -1 Return endif set sMenuLevel to 3 set sButton3 to -1 endif
As you can see, the highest level of "if" statements in this example checks which Sub Menu the player came though, and the next level of "if" statements checks setting they just selected. It would be perfectly acceptable to swap these two around if you'd like.
This method of making multi-level menus can be used to make menus with any number of levels that you'd like, although obviously the script will become more complicated at higher levels. You should also remember that your menu doesn't have to function as an options menu. It could be used for many other things - for example, determining which path the player will progress along in a quest.
Now that the script is finished, let's look at the whole thing in one piece!
ScriptName ExampleMenuSCRIPT short sMenuLevel ; Records the current depth of the ShowMessage framework ; 0 - Initialisation -> Introduction Message ; 1 - Introduction Message -> Main Menu ; 2 - Main Menu -> Sub Menu ; 3 - Sub Menu -> Setting short sButton1 ; sButton variable for the Introduction Message level - Menu level 1 short sButton2 ; sButton variable for the Main Menu level - Menu level 2 short sButton3 ; sButton variable for the Sub Menu level - Menu level 3 ; This GameMode block contains all of the ShowMessage framework Begin GameMode ; ================================================= ; INITIALISATION --> INTRODUCTION MESSAGE ; ================================================= if sMenuLevel == 0 ; Show Introduction Message ShowMessage introMessage set sMenuLevel to 1 set sButton1 to -1 endif ; ================================================= ; INTRODUCTION MESSAGE --> MAIN MENU ; ================================================= if sMenuLevel == 1 if sButton1 == -1 set sButton1 to GetButtonPressed endif if sButton1 == -1 ; None of the buttons have been pressed yet Return else ; Show the Main Menu ; MainMenuMessage contains buttons corresponding to Sub Menus ShowMessage MainMenuMessage set sMenuLevel to 2 set sButton2 to -1 endif endif ; ================================================= ; MAIN MENU --> SUB MENU ; ================================================= if sMenuLevel == 2 if sButton2 == -1 set sButton2 to GetButtonPressed endif if sButton2 == -1 ; None of the buttons have been pressed yet Return elseif sButton2 == 0 ; Show the 1st Sub Menu ShowMessage SubMenu1Message elseif sButton2 == 1 ; Show the 2nd Sub Menu ShowMessage SubMenu2Message elseif sButton2 == 2 ; "Defaults" button - reinitialise all settings SetStage ExampleVRQuest 1 ShowMessage MainMenuMessage set sButton2 to -1 Return else ; "Done" button - close Options Menu player.UnequipItem OptionsMenuEquipKey 0 1 RemoveMe endif set sMenuLevel to 3 set sButton3 to -1 endif ; ================================================= ; SUB MENU --> SETTING ; ================================================= if sMenuLevel == 3 if sButton3 == -1 set sButton3 to GetButtonPressed endif if sButton3 == -1 Return ; None of the buttons have been pressed yet elseif sButton2 == 0 ; The player came through the 1st Sub Menu if sButton3 == 0 ; The 1st setting was selected set VariablesQuest.Variable1 to (VariablesQuest.Variable1 == 0) elseif sButton3 == 1 ; The 2nd setting was selected set VariablesQuest.Variable2 to (VariablesQuest.Variable2 == 0) endif ShowMessage SubMenu1Message elseif sButton2 == 1 ; The player came through the 2nd Sub Menu if sButton3 == 0 ; The 1st setting was selected set VariablesQuest.Variable3 to (VariablesQuest.Variable3 == 0) elseif sButton3 == 1 ; The 2nd setting was selected set VariablesQuest.Variable4 to (VariablesQuest.Variable4 == 0) endif ShowMessage SubMenu2Message else ; "Back" button was pressed ShowMessage MainMenuMessage set sMenuLevel to 2 set sButton2 to -1 Return endif set sMenuLevel to 3 set sButton3 to -1 endif End