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.

Settings can be categorised in two ways - Analogue/Digital and Global/Specific.

• Analogue/Digital
  • Analogue - Settings that can take on many values
  • Digital - Settings that can take on two values - 1 and 0 (corresponding with on and off)
• Global/Specific
  • Global - Settings that affect the game in general
  • Specific - Settings that are specific to a certain object

Each of these categories can utilise a slightly different menu structure, although 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 "ExampleVariableReservoirQuest", will be used in this tutorial:

ScriptName ExampleVariableReservoirSCRIPT

; ==============================================
; Global Settings

short sGlobalDigitalSetting	; Default 1 - On
short sGlobalAnalogueSetting1	; Default 3
ref rGlobalAnalogueSetting2	; Default ExampleRef
; ==============================================

; ==============================================
; Specific Settings

; Item1
short sItem1DigitalSetting	; Default 0 - Off
short sItem1AnalogueSetting	; 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 Specific Variables).

Initialising Your Variables

To initialise these variables, 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 ExampleVariableReservoirSCRIPT:

set ExampleVariableReservoirQuest.sGlobalDigitalSetting to 1 ; On
set ExampleVariableReservoirQuest.sGlobalAnalogueSetting1 to 3
set ExampleVariableReservoirQuest.rGlobalAnalogueSetting2 to ExampleRef

set ExampleVariableReservoirQuest.sItem1DigitalSetting to 0 ; Off
set ExampleVariableReservoirQuest.sItem1AnalogueSetting to 5

Note that, even though variables initialise to 0, we have set sDigitalSetting2 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.

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 ExampleVariableReservoirQuest 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 ExampleVariableReservoirQuest 1
	StopQuest ExampleInitQuest

End

As you can see, it will run only once - using "SetStage ExampleVariableReservoirQuest 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 whether the setting is an Analogue setting or a Digital setting.

Analogue Settings

Associating the value of analogue settings with features depends entirely on the type of feature. For example, it might consist of several "if"/"elseif" statements like so:

if sGlobalAnalogueSetting1 == 0
	; Do it this way
elseif sGlobalAnalogueSetting1 == 1
	; Do it that way
else
	; Do it another way
endif

Analogue settings might also be used as parameters for functions like KillActor, or they may point to persistent references in order to change the object that a certain feature affects:

ExampleVariableReservoirQuest.rGlobalAnalogueSetting2.KillActor ExampleVariableReservoirQuest.rGlobalAnalogueSetting2 ExampleVariableReservoirQuest.sGlobalAnalogueSetting1

Digital Settings

Associating the value of a digital setting with a certain feature is usually done by placing an "if" statement around the code that denotes the feature:

if ExampleVariableReservoirQuest.sGlobalDigitalSetting
	; Code that affects the associated feature goes here
endif

Obviously, this "if" statement should enclose all code segments that affect the relevant feature

Keep in mind that this is not the only way in which the value of a digital setting can be tied to a feature. For example, digital settings can also be used as parameters for certain functions to change a small part of the function.

Still to Come

• Navigating The Options Menu
• Allowing User Access
• Anything else that I think of

See Also

• ShowMessage
• SetStage