Adding an Options Menu
This tutorial is a Work in Progress. If you have any feedback or suggestions, please leave a comment in the discussion page.
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.
Setting Up Your Plugin To Use An Options Menu
Introduction
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 "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 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.
Still to Come
- Navigating The Options Menu
- Allowing User Access
- Anything else that I think of