Oblivion Mod:Q-Core/Modding/Your First Action

Intro

Modding with Q-Core is centered around a few 'new' concepts: Actions, Triggers, and Events. Triggers and Events don't really do anything without Actions, so we'll start with Actions.

An Action is an Object Script attached to an Inventory Item. By adding specific blocks to the Action script we are able to define what an Action does under specific circumstances. Actions can be assigned to hotkeys, Actions can be activated via Menus, Actions can be triggered by Events, and they can also be triggered by other Actions. For this tutorial we'll stick with the first two of those: Hotkeys and Menus.

Before continuing, make sure you've read the Modding/Getting Started section so that you have the Q-Core.esm file properly loaded into the Construction Set when you work on your mod.

Creating the Action

The first thing to do is create a new Object Script in the Construction Set, then enter in the following code:

scn aaHelloWorldActionScript


begin onadd QCTriggerDefault
    messagebox "Hello World"
end

Next we need to create the Action Item and attach the script to it. In the Object Window under MiscItem you will see a bunch of items starting with aaQC___. These are items used by Q-Core.esm. DO NOT edit these. Instead, right click in the list and select New. Type in an 'aaHelloWorldAction' for the EditorID and 'Hello World' for the name, then select the aaHelloWorldActionScript from the script dropdown menu:

Presto! Now we have our first action.

NOTE: There is a bug in OBSE 0015a with CopyIconPath. Until this bug is fixed, you will need to assign an icon to your Action in order for the icon for the assigned key/mouse button to show up in the Q-Core menu system. Any .dds icon file will do, as the filename will be copied over by the system anyway when the game starts up.

Registering the Action

QCTriggerDefault is a Trigger -- a container reference placed in an external cell (aaQCTriggers). When the Action Item is added to the QCTriggerDefault container, the code in the above block will trigger and a messagebox will be displayed on the screen. However, in order for the item to get added to the QCTriggerDefault container we need to register the Action in one or both of two ways:

The Action List

In order for our action to be able to be triggered when the user presses a key, we need to add our Action Item to the Action List. We can do this with the following code:

QCActionList.additem aaHelloWorldAction 1

However, in order for the user to be able to assign the action to a hotkey, we'll also have to add it to a Q-Core Container Menu.

The Q-Core Menu System

As long as an Action is in the Action List, it can be assigned to a hotkey by the player by right-clicking on it from a Q-Core Container Menu. Adding our Action to a Container Menu is as simple as adding it to the Action List:

QCMenuDebug.additem aaHelloWorldAction 1

Note that you do not need to add an Action the Action List for it to work from a Q-Core menu, you only need to add it to the Action List if you want the Action to be able to be assigned to a hotkey.

Once the Action has been added to those two containers by your script, when the player opens the Debug Menu, they will see the Hello World Action. Left-clicking on it will trigger the QCTriggerDefault block, because that's what the Q-Core menu system is programmed to do. Right-clicking on it will automatically bring up the Key Assignment menu, and the player can then assign the Hello World action to a hotkey.

That's it! You can now change the code in the QCTriggerDefault block to whatever you want it to be. Making Hotkeys with Q-Core really is as simple as writing the code for what you want the hotkey to do, and then telling the Q-Core system when it should trigger.

What's Next

While the above process is really quite simple, Actions in Q-Core are capable of much more advanced behavior. As an example, the Spellbook Sorting feature of Q-Core (aaQCSpellbookManager) is coded as a single Action. Before diving into the advanced stuff though, read through the Modding/Terminology and Techniques section to get an idea of how the system is laid out, as well as tips and suggestions for how to keep your project organized and efficient.