Difference between revisions of "Adding an Options Menu"

{| style="width:650px;height:50px;background:lavender;border:1px solid royalblue;margin: 1em auto 1em auto"

| align="center" | '''This article is a Work in Progress.'''  <br /><small>If you have any feedback or suggestions, please leave a comment in the discussion page.</small>

<p>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.</p>

<p>If you're only reading this tutorial because you want to learn how to make a multi-level menu, then I recommend that you skip straight to section two.</p>

<h2>Setting Up Your Plugin To Use An Options Menu</h2>

<p>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>

<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".</p>

<h3>Variable Reservoirs</h3>

<p>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:</p>

float fDamagedWeaponHealthPercent ; Default 0.75

</pre>

<p>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.</p>

<p>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.</p>

<h3>Initialising Your Settings</h3>

<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:</p>

set ExampleVRQuest.fDamagedWeaponHealthPercent to 0.75

</pre>

<p>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]].</p>

<p>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".</p>

<p>An Initialisation Quest is a Start Game Enabled quest that stops itself with the [[StopQuest]] command after running its script once.  It can be used to initialise any number of things - in this example we'll use it to initialise our variables by using [[SetStage]]:</p>

End

</pre>

<p>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.</p>

<h3>Using Your Settings</h3>

<p>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.</p>

<p>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:</p>

<p>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.</p>

<p>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.</p>

<p>Right.  Now that your variables have been utilised, it's time to create the options menu.</p>

<h2>Creating An Options Menu</h2>

<p>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:</p>

<li>Give the player access to the menu</li>

<li>Create the menu</li>

<h3>Giving The Player Access To The Menu</h3>

<p>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.</p>

<p>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:</p>

<li>Give the player a "Menu Key" - A piece of equipment which the player can equip in order to open the menu.</li>

<li>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.</li>

<p>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).</p>

<p>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:</p>

<p>Now, when your variables are first initialised, the Menu Key that you just made will be automatically added to the player.</p>

<p>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.</p>

<p>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:</p>

<p>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:</p>

<p>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.</p>

<p>Now that that's set up, all that's left is the actual Menu script, which will be attached to the token.</p>

<h3>Creating The Menu</h3>

<p>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.</p>

<p>The example menu that I'm going to use for this tutorial will have five levels, each with their own sButton variables:</p>

<li>Level 0 - Initialisation->Introduction Message</li>

<li>Level 1 - Introduction Message->Main Menu</li>

<li>Level 2 - Main Menu->Sub Menu</li>

<li>Level 3 - Sub menu->Setting</li>

<li>Level 4 - Setting->Value</li>

<p>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:</p>

<p>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.</p>

<p>Before we look at what any of these blocks will contain in specific detail, I'd like to go over their structure in general.</p>

<h4>Basic Structure Of A Menu Level</h4>

<p>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:</p>

Button Check 1

<pre>if sButtonX == -1

set sButtonX to GetButtonPressed

</pre>

<p>If the sButton variable still has a value of -1 after Button Check 1, then "Return" is used to end the script for the current frame.</p>

<pre>if sButtonX == -1

Navigation Check

<p>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.</p>

<pre>if sButtonX-1 == 0 ; Player came through button 0

; Button Check 3

; Button Check 3

elseif ...

</pre>

<pre>if sButtonX == 0 ; Player pressed button 0

endif

</pre>

<p>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.</p>

<p>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.</p>

<pre>ShowMessage PreviousMessage

<p>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 3, instead of being called multiple times in the result for each button.</p>

<pre>if sButtonX == 0 ; Player pressed button 0

Menu Level Incrementation

<p>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).</p>

<pre>set sMenuLevel to X + 1

</pre>

</li>

<p>Keep these structures in mind as you read through the following sections, which describe the contents of each section of this example menu.</p>

<h3>Contents Of An Example Menu</h3>

<h4>Initialisation</h4>

<p>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:</p>

<p>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.</p>

<h4>Introduction Message</h4>

<p>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:</p>

if sButton1 == -1

set sButton1 to GetButtonPressed

<h4>Main Menu</h4>

<p>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.</p>

<p>There are three types of button in this example Main Menu:</p>

<li>Buttons that take the player to a Sub Menu</li>

<li>A "Defaults" button that sets all settings to their default values</li>

<li>A "Done" button that closes the menu</li>

<p>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.</p>

if sButton2 == -1

set sButton2 to GetButtonPressed

<p>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.</p>

<h4>Sub Menu</h4>

<p>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:</p>

<li>Buttons that take the player to a Setting Menu, where the can select a new value for the setting</li>

<li>Buttons that toggle a setting between two values</li>

<p>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.</p>

if sButton3 == -1

set sButton3 to GetButtonPressed

<p>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.</p>

<p>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.</p>

<h4>Setting</h4>

<p>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:</p>

<li>The "menu level incrementation" doesn't actually increment sMenuLevel - all it does is reset the current sButton variable to -1</li>

<li>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 3.</li>

if sButton4 == -1

set sButton4 to GetButtonPressed

<h3>Conclusion</h3>

<p>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.</p>

<p>Now that the script is finished, let's look at the whole thing in one piece!</p>

if sButton1 == -1

set sButton1 to GetButtonPressed

if sButton2 == -1

set sButton2 to GetButtonPressed

if sButton3 == -1

set sButton3 to GetButtonPressed

if sButton4 == -1

set sButton4 to GetButtonPressed

<h2>See Also</h2>

[[SetStage]]

[[ShowMessage]]