User:Quetzilla/How to Use QZ Keys

About QZ Keys

QZ Keys is a modder's resource which is designed to enable you to add hotkeys to a mod without bothering with any of the stuff about detecting keys or whatnot. All hotkeys are managed with a single script. In the future it will provide a menu to allow the user to re-assign keys on their own to prevent conflicts, but that requires FOSE functions that don't exist yet.

Using QZ Keys

The following may look like a lot of steps, but it's really not. Trust me.

Setting Up

Setting up is simple, but you have to do it right or things won't work.

1. QZ Keys requires FOSE so make sure to install that first.
2. Next, download QZ Keys, which you can find here, then install the files to your /Data/ folder.
3. In order to use QZ Keys with the GECK, you need to enable multiple master editing in the GECKCustom.ini file. Directions for that can be found here.
4. The next step is to load QZ Keys.esm when working on your mod. In the Data Files window of the GECK, set your mod as the Active File, but make sure to put a checkmark next to QZ Keys.esm (which will be at the top of the list). You only need to do this the first time you use QZ Keys with a mod, the next time it will be loaded automatically.

Creating Your Hotkey

Creating a hotkey is so simple, your four-year old kid who isn't even born yet could do it:

1. In the Object Window of the GECK, select Form List, which is under Miscellaneous in the tree layout on the left-hand side. At the top of the list of Form Lists, you will see aaQZKeysList. Double click it to view the list.
2. At the bottom of the list you will see TemplateAction and TemplateActionScript. We're going to make copies of both of these. First, double click TemplateAction.
3. Notice the angry text in the name box that says 'MAKE NEW COPY - DO NOT EDIT THIS'. Do not edit the TemplateAction itself -- always make a new copy.
4. Change the editor ID from TemplateAction to something suitable for your mod, like 'MyStupidHotkey', then change the Name to something like 'My Stupid Hotkey'.
5. Here you'll need to get the DirectX scancode for the key you want to link to your Hotkey. You can find the list of scancodes here. When you've found the one you need, place that number into the Value field for the hotkey.
6. Now click OK. When it asks if you want to make a new form, click yes.
7. We've got our Hotkey item, but it's still using TemplateActionScript, so we'll want to change that. Create a new script, the paste the following into the text area:

scn MyStupidHotkeyScript

begin onadd player
	printc "How stupid is this hotkey? ...Don't answer that."
end

Now go back to your 'MyStupidHotkey' key item and change the script to be the new script we created. Congratulations, we're almost done!

Registering Your Hotkey

In order for QZ Keys to know that your mod has a hotkey to check for, you have to register the hotkey. Assuming you want your hotkey to be usable all the time, you would do the following:

1. Create a new Quest and attach a quest script to it. Set the Quest as Start Game Enabled.
2. Paste the following code into the quest script:

scn WhateverYouWantScript

begin gamemode

	;; add hotkey to action list
	if ListGetFormIndex ActionList MyStupidHotkey == -1
		listaddform ActionList MyStupidHotkey
		printc "StupidMod - Stupid Key registered"
	endif

end

Congratulations, now you really are finished!

Though that may have seemed like a long process (but I hope it didn't), it's easy to get the hang of it once you've done it a few times. It's also a lot easier than coding your own hotkey detection scripts every time you want to add a hotkey to a new mod.

Notes

• You'll notice there are two action lists: ActionList and MenuActionList. Hotkeys registered to ActionList will only trigger in GameMode, and hotkeys registered to MenuActionList will only trigger in MenuMode (obviously). You can also register a hotkey to both lists if you want it to work all of the time.
• You need to register the hotkey every time the game starts up. The above script takes care of this, but in case you want a hotkey that isn't enabled right away (such as for an ability granted by a Perk or Armor), you'll need to make sure to that the key gets re-registered every time the game starts. You also want to make sure not to add it to the action list more than once.
• When triggered, the scripted key item will remain in the player's inventory for as long as the actual key is held down. Most of the time all you'll care about is when the player first pressed the key, so most code will go in the 'begin onadd player' block, but you can also put code in a GameMode block, and the code will run for as long as the key is held down.
• Multiple hotkey actions can be assigned to the same physical key. I have intentionally not prevented this because there are many circumstances where this can be useful. In the future this will be updated so that the user can re-assign hotkeys on their own, thus resolving any possible hotkey conflicts.
• With the possible exception of future Official Patches, updates to QZ Keys will not require you to change your mod in any way.

One Last Thing

Do not include QZ Keys with your own mod. Instead, please instruct your users to download and install QZ Keys on their own from the link provided above.