Difference between revisions of "Adding an Options Menu"

26,890 bytes added ,  22:12, 23 July 2010
Converting to wiki markup
imported>Cipscis
(First draft of tutorial - still very much incomplete)
 
imported>DewiMorgan
(Converting to wiki markup)
 
(13 intermediate revisions by one other user not shown)
Line 1: Line 1:
<p>This tutorial is a Work in Progress.  If you have any feedback or suggestions, please leave a comment under the appropriate section of my User Talk page.</p>
=Disclaimer=
<p>I'm assuming that anybody reading this is familiar enough with the GECK that I can ignore things like how to make a new quest, and can instead concentrate on the scripting side of things.</p>


<h1>Adding an Options Menu</h1>
This tutorial is split into two main parts.  The first section is about how to set up your plugin to use an options menu, and focuses on where and how to set up your settings, and how to use them remotely.  The second section is about making the actual menu, and focuses on giving the player access to the menu and the scripting involved in creating the menu.


<h2>Introduction</h2>
If you're only reading this tutorial because you want to learn how to make a scripted menu, then I recommend that you skip straight to section 3.  Alternately, a tutorial that focuses entirely on the scripting behind [[ShowMessage]] menus is available on [http://www.cipscis.com/ cipscis.com].  To view this tutorial, see the [[Adding_an_Options_Menu#External_Links|External Links]] section at the bottom of this page


<p>Creating an Options Menu for is a good way to keep your plugin Modular without having to make multiple plugin files available.  It allows the user to change two types of settings in game:</p>
==Setting Up Your Plugin To Use An Options Menu==
<ul>
<li>
Analogue settings - Changing the value of a setting
</li>
<li>
Digital settings - Turning a feature on or off
</li>
</ul>
<p>Each of these settings utilises a slightly different menu structure, although they can both be incorporated into the same Options Menu.</p>


<h2>Declaring Our Variables</h2>
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.


<p>The first step in making these settings editable is to define them in a "Variable Reservoir" Quest ScriptA Variable Reservoir script, or VR script is a script that contains no Begin/End blocks, but consists entirely of variable declarationsThis example VR script, which is attached to the "Start Game Enabled" quest "ExampleVariableReservoirQuest", will be used in this tutorial:</p>
The settings that can be changed in your options menu may be used in many different places in your Mod, so it's important that you know where to find them so that you can change them.  If you know the location of the script in which the variable you want to use or change was declared, then you can access that variable from any script.  To do this is we're going to create a Quest with a Variable Reservoir script.  Let's give it the EditorID "ExampleVRQuest".


<pre>ScriptName ExampleVariableReservoirSCRIPT
===Variable Reservoirs===


; ===============================================
A Variable Reservoir script, or VR script, is one which contains only variable declarations.  It will never actually run, but it gives you a specific location at which you can define all of your settings.  The VR script that we'll be using in this tutorial will declare four variables:
; Digital Settings
short sDigitalSetting1 ; Default 1 - On
short sDigitalSetting2 ; Default 0 - Off
; ===============================================


; ===============================================
<pre>ScriptName ExampleVRSCRIPT
; Analogue Settings
short sAddExampleItem ; Default 1
short sAnalogueSetting1 ; Default 3
short sItemCount ; Default 3
short sAnalogueSetting2 ; Default 5
 
; ===============================================
short sAddDamagedWeapon ; Default 0
</pre>
float fDamagedWeaponHealthPercent ; Default 0.75</pre>
 
Keep in mind that these settings are only examples, yours will probably be completely different.  As you can see, I've prefixed these variables according to their type (s for short, f for float), and named them according to their function.  While it's up to you to choose a naming system that you're comfortable with, it's important that you name your variables according to their function.  Don't start using variable names like "Variable1" or "ReferenceVariable", as these are ambiguous and it'll make your scripts very difficult to understand.
 
Now that you've defined your variables in a specific location, you can use them remotely in any script.  The syntax for using a variable remotely is "LocationEditorID.VariableName", where LocationEditorID is the EditorID of the quest or reference that the script where the variable is declared is attached to.
 
===Initialising Your Settings===


<p>Note that it consists entirely of variable declarations, and will never actually runThat means that these variables need some method of being initialised to their default values - at the moment they are all 0.</p>
At the moment, the variables that have just been declared have been initialised to a value of "0"However, we want most of our variables to be set to a default value other than 0. To do this, we're going to create a quest stage result script for stage 1 of ExampleVRQuest:


<h2>Initialising Our Variables</h2>
<pre>set ExampleVRQuest.sAddExampleItem to 1
set ExampleVRQuest.sItemCount to 3


<p>To initialise these variables, we are going to add a result script to Stage 1 of ExampleVariableReservoirQuest. A quest 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.</p>
set ExampleVRQuest.sAddDamagedWeapon to 0
<p>This is the result script that would used to initialise the variables in ExampleVariableReservoirSCRIPT:</p>
set ExampleVRQuest.fDamagedWeaponHealthPercent to 0.75</pre>


<pre>set ExampleVariableReservoirQuest.sDigitalSetting1 to 1
Note that, even though these variables are all initialised to 0, I have still set sAddDamagedWeapon to its default value of 0. Doing this means that you can create a "Defaults" button in your Options Menu that sets all settings to their default values by using [[SetStage]].
set ExampleVariableReservoirQuest.sDigitalSetting2 to 0


set ExampleVariableReservoirQuest.sAnalogueSetting1 to 3
Now, you need a way of running this initialisation script in order to set your settings to their default values. There are a few ways to do this, the one I'm going to describe here involves creating a separate "Initialisation Quest".  Let's give it the EditorID "ExampleInitQuest".
set ExampleVariableReservoirQuest.sAnalogueSetting2 to 5</pre>


<p>Note that, even though sDigitalSetting2 initialises to 0 anyway, we have set it to 0 in this result script.  This ensures that a "Set to Defaults" option can be included in the Options Menu that can set or reset all settings to their default values with a simple "SetStage ExampleVariableReservoirQuest 1" command.</p>
An Initialisation Quest is a Start Game Enabled quest that stops itself with the [[StopQuest]] command after running its script onceIt can be used to initialise any number of things - in this example we'll use it to initialise our variables by using [[SetStage]]:
<p>Of course, we need some way in which to run this result script initially - as it will not be run until ExampleVariableReservoirQuest 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 ExampleVariableReservoirQuest 1" somewhere.</p>
<p>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:</p>


<pre>ScriptName ExampleInitSCRIPT
<pre>ScriptName ExampleInitSCRIPT
Line 57: Line 46:
Begin GameMode
Begin GameMode


SetStage ExampleVariableReservoirQuest 1
SetStage ExampleVRQuest 1
StopQuest ExampleInitQuest
StopQuest ExampleInitQuest
End</pre>
Now, when you first load the game with your plugin installed, your settings will be initialised to their default values.  This means that you can now use them remotely, wherever they need to be used.
===Using Your Settings===
At the moment, all your settings are doing is sitting in your VR Quest at their default values.  They're not actually <em>doing</em> anything, and changing them at this point wouldn't have any effect.  Before there's any point in creating an options menu to change them, you'll have to utilise them remotely.
How exactly you do this will, of course, depend on the nature of your settings.  The example settings used in this tutorial are just that, examples.  Here's how I will be implementing them:
<pre>ScriptName ExampleItemDispenserSCRIPT
; This script is attached to an item dispenser
; When activated, it gives out either ExampleItems or Pencils
ref rActionRef
Begin OnActivate
set rActionRef to GetActionRef
if rActionRef
if ExampleVRQuest.sAddExampleItem
rActionRef.AddItem ExampleItem ExampleVRQuest.sItemCount
else
rActionRef.AddItem Pencil01 ExampleVRQuest.sItemCount
endif
endif
End
</pre>
<pre>ScriptName ExampleWeaponsRackSCRIPT
; This script is attached to a weapons rack
; When activated, it gives out ExampleWeapons
ref rActionRef
Begin OnActivate
set rActionRef to GetActionRef
if rActionRef
if ExampleVRQuest.sAddDamagedWeapon
rActionRef.AddItemHealthPercent ExampleWeapon 1 ExampleVRQuest.fDamagedWeaponHealthPercent
else
rActionRef.AddItem ExampleWeapon 1
endif
endif
End
</pre>
The way in which I've implemented them isn't important to this tutorial, I've just give you those scripts as examples of how to utilise your settings.
Note the syntax that I've used with these remote variables.  You'll have to do the same thing, but obviously replacing ExampleVRQuest with the EditorID of your VR Quest and using your variable name instead of the example one.
Right.  Now that your variables have been utilised, it's time to create the options menu.
==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
===Giving The Player Access To The Menu===
Before you create the actual menu, you'll have to set up the plugin so that the player is able to access the menu.  By doing this before you 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 you can use the Menu Key in a script, you'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 that 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 you initialised all of your variables by using a [[SetStage]] command to run a result script?  Now you're going to go back to that result script now and add three more lines:
<pre>if player.GetItemCount ExampleMenuKey == 0
player.AddItem ExampleMenuKey 1
endif
</pre>
Now, when your variables are first initialised, the Menu Key that you just made will be automatically added to the player.
When the Menu Key is equipped, you'll want it to run some code that adds a token to the player, but before you can do this you 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.
Once you've created the token, you 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:
<pre>ScriptName ExampleMenuKeySCRIPT
short sDoOnce
Begin OnEquip
set sDoOnce to 1
AddItem ExampleMenuToken 1 1
End
</pre>
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:
<pre>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
</pre>
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.
<pre>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
End
</pre>
</pre>


<p>As you can see, it will run only once - using "SetStage ExampleVariableReservoirQuest 1" to initialise our settings to their default values.</p>
Now that that's set up, all that's left is the actual Menu script, which will be attached to the token.
 
===Creating The Menu===
 
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 five 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->Setting
* Level 4 - Setting->Value
 
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:
 
<pre>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
; 4 - Setting -> Value
 
; 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
 
 
; =================================================
; SETTING --> VALUE
; =================================================
if sMenuLevel == 4
endif


<h2>Still to Come</h2>
End
</pre>


<ul>
As you can see, the GameMode block is now divided up into five different segments.  Which one runs will depend on the menu's current level of navigation.
<li>
 
Utilising Our Variables
Before we look at what any of these blocks will contain in specific detail, I'd like to go over their structure in general.
</li>
 
<li>
====Basic Structure Of A Menu Level====
Navigating The Options Menu
 
</li>
Each level of our menu is contained within an "if" statement, which checks the value of sMenuLevel.  Within this "if" statement the structure of each menu level is basically the same, although deeper levels will be more complicated.  Each level, unless stated otherwise,  has the following structures in common:
<li>
 
Allowing User Access
'''Button Set'''
</li>
 
Anything else that I think of
Each menu level begins by checking if its sButton variable has been set/reset (i.e. has a value of -1) and, if so, sets it to [[GetButtonPressed]]:
</li>
 
</ul>
<pre>set sButtonX to GetButtonPressed</pre>
 
Using this method ensures that the value of each sButton variable is maintained until it is explicitly reset.
 
'''Button Check 1'''
 
If the sButton variable still has a value of -1 after Button Set, then "Return" is used to end the script for the current frame.
 
<pre>if sButtonX == -1
Return
elseif ...</pre>
 
'''Navigation Check'''
 
If the script has got this far, then the player must have pressed a button.  If the menu level is deep enough, "if" statements are used to determine, via previous sButton variables, which path the player took to their current menu.  If the menu level is not deep enough, or there is only one possible path that the player could have taken, there is no need for a navigation check.
 
<pre>if sButtonX-1 == 0 ; Player came through button 0
; Button Check 2
elseif sButtonX-1 == 0 ; Player came through button 1
; Button Check 2
elseif ...</pre>
 
'''Button Check 2'''
 
"If" statements are used to cycle through the various buttons that the player could possibly have pressed.  If there is a "Back" or "Done" button (normally there won't be both), then it is usually the bottom button.  This allows it to be checked with an "else" statement as opposed to an "elseif" statement, which makes it slightly easier to add more buttons to the menu later.
 
<pre>if sButtonX == 0 ; Player pressed button 0
; Button Result
elseif sButtonX == 1 ; Player pressed button 1
; Button Result
elseif...
else ; Player pressed Back/Done button
; Button Result
endif</pre>
 
'''Button Result'''
 
This is essentially the button's "result script".  It contains the code that will execute itself when the button is pressed.  With the exceptions of "Done" buttons and buttons that leave the player on the same menu, this code will contain a [[ShowMessage]] function.
 
If the button doesn't take the player to the <em>next</em> menu level, the result script is terminated with a "Return" statement.  The deepest level is an exception to this, in that it is the buttons that don't leave the player on the <em>same</em> level that are terminated with a "Return" statement.
<pre>ShowMessage PreviousMessage
set sMenuLevel to X-1
Return
</pre>
Because the deepest level leaves the player on the same level instead of taking them back to the previous level, the path cannot branch from here so most of the buttons will probably take the player to the same menu.  Because of this, the [[ShowMessage]] function can be called at the end of the navigation check, after button check 2, instead of being called multiple times in the result for each button.
<pre>if sButtonX == 0 ; Player pressed button 0
...
else ; Player pressed "Back" button
ShowMessage PreviousMessage
set sMenuLevel to X - 1
Return
endif
ShowMessage CurrentMessage</pre>
 
'''Menu Level Incrementation'''
 
Because of the various "Return" statements utilised in each menu level, this code will only execute if the player has selected a button that takes them to the next menu level (or, in the case of the deepest level, leaves them on the same level).
 
<pre>set sMenuLevel to X + 1</pre>
 
 
Keep these structures in mind as you read through the following sections, which describe the contents of each section of this example menu.
 
===Contents Of An Example Menu===
 
====Initialisation====
 
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:
 
<pre> ; =================================================
; INITIALISATION --> INTRODUCTION MESSAGE
; =================================================
if sMenuLevel == 0 ; Show Introduction Message
ShowMessage introMessage
set sMenuLevel to 1
endif
</pre>
 
If you're wondering why I've included an Introduction message before the Main Message, it's quite 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.
 
====Introduction Message====
 
Now, because you've set sMenuLevel to 1, the next section of the script will run.  In this section, you need to check when the player clicks the button to continue from the Introduction message into the Main Menu by using [[GetButtonPressed]].  When the player clicks the button, the script will call the Main Menu, increment sMenuLevel to 2, and initialise the next sButton variable - sButton2:
 
<pre> ; =================================================
; INTRODUCTION MESSAGE --> MAIN MENU
; =================================================
if sMenuLevel == 1
 
set sButton1 to GetButtonPressed
 
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
 
endif
 
endif
</pre>
 
====Main Menu====
 
This 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, you need to check which button the player presses and update the Menu accordingly.
 
There are three types of button in this example 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.
 
<pre> ; =================================================
; MAIN MENU --> SUB MENU
; =================================================
if sMenuLevel == 2
 
set sButton2 to GetButtonPressed
 
if sButton2 == -1 ; None of the buttons have been pressed yet
 
Return
 
elseif sButton2 == 0 ; Show the "Weapons Rack" Sub Menu
 
ShowMessage WeaponsRackSubMenuMessage
 
elseif sButton2 == 1 ; Show the "Item Dispenser" Sub Menu
 
ShowMessage ItemDispenserSubMenuMessage
 
elseif sButton2 == 2 ; "Defaults" button - reinitialise all settings
 
SetStage ExampleVRQuest 1
ShowMessage MainMenuMessage
Return
 
else ; "Done" button - close Options Menu
 
player.UnequipItem OptionsMenuEquipKey 0 1
RemoveMe
 
endif
 
set sMenuLevel to 3
 
endif
</pre>
 
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.
 
====Sub Menu====
 
This section is the similar to the previous section - it's where the player selects the setting that they'd like to change.  Once again, there are multiple types of button in these menus:
 
* Buttons that take the player to a Setting Menu, where the can select a new value for the setting
* Buttons that toggle a setting between two values
 
We're now deep enough in the menu that there are multiple paths that the player could have taken to reach their current menu level.  Because of this, we'll need to check the values of the sButton variables of the higher levels, in order to build a kind of cookie-trail.
 
<pre> ; =================================================
; SUB MENU --> SETTING
; =================================================
if sMenuLevel == 3
 
set sButton3 to GetButtonPressed
 
if sButton3 == -1
 
Return ; None of the buttons have been pressed yet
 
elseif sButton2 == 0 ; The player came through the "Weapons Rack" Sub Menu
 
if sButton3 == 0 ; The "Damaged" setting was selected
set ExampleVRQuest.sAddDamagedWeapon to (ExampleVRQuest.sAddDamagedWeapon == 0)
ShowMessage WeaponsRackSubMenuMessage
Return
elseif sButton3 == 1 ; The "Condition" setting was selected
ShowMessage ConditionSettingMessage ExampleVRQuest.fDamagedWeaponHealthPercent
else ; "Back" button was pressed
ShowMessage MainMenuMessage
set sMenuLevel to 2
Return
endif
 
elseif sButton2 == 1 ; The player came through the "Item Dispenser" Sub Menu
 
if sButton3 == 0 ; The "Item" setting was selected
set ExampleVRQuest.sAddExampleItem to (ExampleVRQuest.sAddExampleItem == 0)
ShowMessage ItemDispenserSubMenuMessage
Return
elseif sButton3 == 1 ; The "Amount" setting was selected
ShowMessage AmountSettingMessage ExampleVRQuest.sItemCount
else ; "Back" button was pressed
ShowMessage MainMenuMessage
set sMenuLevel to 2
Return
endif
 
endif
 
set sMenuLevel to 4
 
endif
</pre>
 
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.  Depending on which button the player selected, either the setting will be toggled or the player will enter a new menu in which they can select a new value for the setting that they selected.
 
The next section is the final section in this example menu.  At this level, the player will be able to choose a new value for the setting that they just selected.
 
====Setting====
 
This section differs slightly from all previous sections, because the player can advance no further in the menu.  This means that, instead of taking the player to the next menu level, most of the buttons will leave the player on the current level.  This means a couple of structural changes need to take place:
 
* The "menu level incrementation" doesn't actually increment sMenuLevel - all it does is reset the current sButton variable to -1
* Because most buttons in any menu will leave the player on the same menu, the [[ShowMessage]] section of the results of these buttons can be moved to the end of the navigation check, after button check 2.
 
<pre> ; =================================================
; SETTING --> VALUE
; =================================================
if sMenuLevel == 4
 
set sButton4 to GetButtonPressed
 
if sButton4 == -1
 
Return ; None of the buttons have been pressed yet
 
elseif sButton2 == 0 ; The player came through the "Weapons Rack" Sub Menu
 
; Don't need to check sButton3 - it must be equal to 1
if sButton4 == 0
set ExampleVRQuest.fDamagedWeaponHealthPercent to 0.25
elseif sButton4 == 1
set ExampleVRQuest.fDamagedWeaponHealthPercent to 0.50
elseif sButton4 == 2
set ExampleVRQuest.fDamagedWeaponHealthPercent to 0.75
else ; "Back" button was pressed
ShowMessage WeaponsRackSubMenuMessage
set sMenuLevel to 3
Return
endif
ShowMessage ConditionSettingMessage ExampleVRQuest.fDamagedWeaponHealthPercent
 
elseif sButton2 == 1 ; The player came through the "Item Dispenser" Sub Menu
 
; Don't need to check sButton3 - it must be equal to 1
if sButton4 == 0
set ExampleVRQuest.sItemCount to 1
if sButton4 == 1
set ExampleVRQuest.sItemCount to 2
if sButton4 == 2
set ExampleVRQuest.sItemCount to 3
else ; "Back" button was pressed
ShowMessage ItemDispenserSubMenuMessage
set sMenuLevel to 3
Return
endif
ShowMessage AmountSettingMessage ExampleVRQuest.sItemCount
 
endif
 
endif
</pre>
 
===Conclusion===
 
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!
 
<pre>ScriptName ExampleMenuTokenSCRIPT
 
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
; 4 - Setting -> Value
 
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
short sButton4 ; sButton variable for the Setting level - Menu level 4
 
; 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
endif
 
 
; =================================================
; INTRODUCTION MESSAGE --> MAIN MENU
; =================================================
if sMenuLevel == 1
 
set sButton1 to GetButtonPressed
 
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
 
endif
 
endif
 
 
; =================================================
; MAIN MENU --> SUB MENU
; =================================================
if sMenuLevel == 2
 
set sButton2 to GetButtonPressed
 
if sButton2 == -1 ; None of the buttons have been pressed yet
 
Return
 
elseif sButton2 == 0 ; Show the "Weapons Rack" Sub Menu
 
ShowMessage WeaponsRackSubMenuMessage
 
elseif sButton2 == 1 ; Show the "Item Dispenser" Sub Menu
 
ShowMessage ItemDispenserSubMenuMessage
 
elseif sButton2 == 2 ; "Defaults" button - reinitialise all settings
 
SetStage ExampleVRQuest 1
ShowMessage MainMenuMessage
Return
 
else ; "Done" button - close Options Menu
 
player.UnequipItem OptionsMenuEquipKey 0 1
RemoveMe
 
endif
 
set sMenuLevel to 3
 
endif
 
 
; =================================================
; SUB MENU --> SETTING
; =================================================
if sMenuLevel == 3
 
set sButton3 to GetButtonPressed
 
if sButton3 == -1
 
Return ; None of the buttons have been pressed yet
 
elseif sButton2 == 0 ; The player came through the "Weapons Rack" Sub Menu
 
if sButton3 == 0 ; The "Damaged" setting was selected
set ExampleVRQuest.sAddDamagedWeapon to (ExampleVRQuest.sAddDamagedWeapon == 0)
ShowMessage WeaponsRackSubMenuMessage
Return
elseif sButton3 == 1 ; The "Condition" setting was selected
ShowMessage ConditionSettingMessage ExampleVRQuest.fDamagedWeaponHealthPercent
else ; "Back" button was pressed
ShowMessage MainMenuMessage
set sMenuLevel to 2
Return
endif
 
elseif sButton2 == 1 ; The player came through the "Item Dispenser" Sub Menu
 
if sButton3 == 0 ; The "Item" setting was selected
set ExampleVRQuest.sAddExampleItem to (ExampleVRQuest.sAddExampleItem == 0)
ShowMessage ItemDispenserSubMenuMessage
Return
elseif sButton3 == 1 ; The "Amount" setting was selected
ShowMessage AmountSettingMessage ExampleVRQuest.sItemCount
else ; "Back" button was pressed
ShowMessage MainMenuMessage
set sMenuLevel to 2
Return
endif
 
endif
 
set sMenuLevel to 4
 
endif
 
 
; =================================================
; SETTING --> VALUE
; =================================================
if sMenuLevel == 4
 
set sButton4 to GetButtonPressed
 
if sButton4 == -1
 
Return ; None of the buttons have been pressed yet
 
elseif sButton2 == 0 ; The player came through the "Weapons Rack" Sub Menu
 
; Don't need to check sButton3 - it must be equal to 1
if sButton4 == 0
set ExampleVRQuest.fDamagedWeaponHealthPercent to 0.25
elseif sButton4 == 1
set ExampleVRQuest.fDamagedWeaponHealthPercent to 0.50
elseif sButton4 == 2
set ExampleVRQuest.fDamagedWeaponHealthPercent to 0.75
else ; "Back" button was pressed
ShowMessage WeaponsRackSubMenuMessage
set sMenuLevel to 3
Return
endif
ShowMessage ConditionSettingMessage ExampleVRQuest.fDamagedWeaponHealthPercent
 
elseif sButton2 == 1 ; The player came through the "Item Dispenser" Sub Menu
 
; Don't need to check sButton3 - it must be equal to 1
if sButton4 == 0
set ExampleVRQuest.sItemCount to 1
if sButton4 == 1
set ExampleVRQuest.sItemCount to 2
if sButton4 == 2
set ExampleVRQuest.sItemCount to 3
else ; "Back" button was pressed
ShowMessage ItemDispenserSubMenuMessage
set sMenuLevel to 3
Return
endif
ShowMessage AmountSettingMessage ExampleVRQuest.sItemCount
 
endif
 
endif
 
End
</pre>


<h2>See Also</h2>
==External Links==
* [http://www.cipscis.com/fallout/tutorials/menu.aspx Making a Menu]


<ul>
[[Category:Scripting]]
<li>
[[Category:Tutorials]]
[[ShowMessage]]
</li>
<li>
[[SetStage]]
</li>
</ul>
Anonymous user