A beginner's guide, lesson 4 - Anatomy of a quest, part 1

Preamble

This is the fourth in a proposed series of Tutorial Lessons designed to teach how to mod TES IV: Oblivion. The tutorials are aimed at beginners and will build up into a Complete Modding Course.

Don't worry there are no exams, though there is some homework. It is not intended to aid the transfer of modders from Morrowind. Nor is it intended for experienced modders, although as the series develops, they may find something of interest here.

Files

I have uploaded some files which we will use to accompany the next few tutorials.

They include:

A. BGModTut4.esp:
This contains a building, a farmhouse, and a dungeon that we will use as sets in lessons 6, 7 and 8. I have uploaded it now to give you a chance to do a little personalisation before the next lesson is released (see Homework at end of lesson 5)

B. BGModAnvilCheat.esp:
This is a small optional cheat mod to give users 5000 septims to allow them to follow this tutorial if they have not completed the quest. (See Introduction)

C. A RTF document
This contains the text for the first 5 lessons (as requested).

Download the following three files from here (external link)

Introduction

I'm afraid we are about to take a step backward in term of progress. This lesson shares many qualities with the first lesson in this series. We will learn loads of information but do no practical modding ourselves.

In this lesson, we will examine a quest from the game in great detail, looking at its implementation from beginning to end. This is a very long exercise and I have split it into two lessons, although both follow directly on from each other, and have been released together.

It is inevitably going to be a bit of a spoiler if you have not played the quest. The quest is the Anvil House acquisition mod "Where Spirits have Lease". If you have not played this it might be an idea to do so.

(Note: I have included a cheat mod in the above file link which will speed you through this quest. It is undoubtedly a cheat. No bones about it. So if you prefer to play it the "honest" way, don't load it.)

What makes a building mod really work? Clearly, good design plays its part. But beyond that, it is the "extras" that come with the buildings that really sell the mod. A classic example of this is the "Kumiko Manor" mod.

Taken purely as a building mod, it adds a nice-sized manor house on its own private island. The house, which is based on one of the Leyawiin guild houses, is a well furnished, well decorated and well executed building. However, thanks to the designer's talent for scripting, you get so much more.

It is the extras that make this one of the "must have" mods. If we are to move on, we too must learn how to script, build quests and make useful working NPCs. They are linked together, and we will need to learn each to execute a well made quest mod.

Quest Structure

Quests are the bedrock of Oblivion's game mechanics. You can't really play the game without encountering quests. Even if you decide to be a rebel and ignore every headlined quest, you will still encounter them.

For example, let's say you decide to use your character as a hunter of beasts and a gatherer of plants. You then sell these to Merchants.

When you encounter a merchant and enter the barter/sell menu you are in a quest. The game has a quest, which does not appear on your journal, which controls merchant transactions. When you walk down the street and overhear two NPCs talking, the conversation is controlled by another hidden quest.

The more obvious quests are those that produce journal updates. Let's look at one of these in detail to see how it is structured and how it operates.
We will follow it step by step. We will encounter lots of important new concepts and functions. Rather than break off the run through to look at those, I have included them as linked appendixes.

I give you fair warning the next two lessons are quite long. Break out a lot of cookies and coffee and let us follow the quest together.

MS02 Where Spirits Have Lease

The quest we will look at is called "Where Spirits Have Lease". The plotline goes something like this:

The player overhears a rumour and is directed to a character called Velwyn Benirus. He offers to sell you a manor house on the cheap. When you part with your 5000 septims and head to the manor, it appears a bit run down. Still it was cheap. However, when you sleep in the manor you are attacked by ghosts.

You discover the place is cursed. Stopping to collect a diary and a strange skeletal hand, you go off to find Velwyn, only to find out he has fled town. You track him down to the Imperial City, where - thanks to the diary - you find out his grandfather was a nasty bit of work (necromancer) and that only Velwyn can help lift the curse.

Back to Anvil you go. Velwyn opens a door to a secret chamber and then runs away. You are left to fight his grandfather's evil influence alone. When that is done, you speak to Velwyn for the last time, and return to find the curse lifted and you now own a lovely new house.

It is listed in the CS as MS02

Open up the CS, with just Oblivion checked in the Data box. Look at the menus on the top bar and select CHARACTER. (That in itself tells you a lot about the nature of quests.) Now select Quests. The quest window pops up.

If you are not sure about all the features of the quest window, you should take a time-out and go through Appendix One: the Quest Window.

Getting Started

Now let's try to follow the paper trail of the quest from beginning to end. We will flit about from location to location and look at a whole lot of windows.

First remember, this quest began running the second you started the game.

It just did nothing except try to run the quest script.

Open it up and have a look at it. To do this select the Quest Data tab and then click on the button with the ••• on it.

The Script looks like this:

Scriptname MS02Script

short GhostGen
short Doonce3
short Doonce4
short Doonce5
short Doonce6
short Doonce7
short Doonce8
short VelwynGo
short BenirusEscort
short BenirusFollow
short GhostJournal
short MetHim
short ManorLike
short Runaway
short DoorCheck
float fQuestDelayTime

begin menumode

;This part of the script enables ghost attacks if player sleeps

if ( GetStage MS02 >= 30 ) && ( GhostGen == 0 )
     if ( IsPCSleeping == 1 && player.getincell AnvilBenirusManorHaunted == 1 )
     MS02GhostTest1Ref.Enable
     MS02GhostTest2Ref.Enable
     MS02GhostTest3Ref.Enable
     WakeUpPC
     set GhostGen to 1
     endif
endif

end

begin gamemode

;This triggers new journal when first arriving at manor

if ( GetStage MS02 == 30 )
     if ( Player.GetDistance MS02BenirusManorWaitFollow <= 500 )
         setstage MS02 35
     endif
endif

End

I know it is confusing but we will try to decipher it bit by bit a little later in this tutorial. The Key lines for now are the two IF conditions:

if ( GetStage MS02 >= 30) && ( GhostGen == 0 )

if ( GetStage MS02 == 30)

From the start of the game, this script has been running. But, each time it tried, it got as far as the highlighted condition and failed. These will only work when the quest reaches stage 30.

But it kept trying every 5 seconds. The quest is, in fact, stuck prior to Stage 10. We can think of it as being at Stage 0.

It remains this way until your character heads for Anvil. When in Anvil, you will pass many NPCs who will have conversations with each other. What you hear depends on the conditions set in the Topic and Conversation tabs and the priority of the quests you are running. One possible conversation is the one that progresses this quest.

Let's look at the Topics and Conversations that apply to this quest. Click on the View Filtered Dialogue Window button. It by default selects the current quest, but we can select others. You can select more than one quest by using the CTRL and click methods. You can even select ALL. For now select MS02.

A new window opens. It is similar to the quest window, except it is missing the first three tabs. This window filters out all dialogue that is not directly linked to MS02.

If you look under conversation and INFOGENERAL you will find two entries.

These are both set with a random flag, so provided the conditions are met, the game will use either one, between a HELLO and a GOODBYE in a conversation between two NPCs.

Each has a fairly lengthy set of AND conditions.

All these must be met for this conversation info to be played. Look at the conditions one by one. (We will look more closely at the syntax of conditions as we make progress.)

In order, they check that the following are true:

1. That the Quest has not been completed (MS02<110)

2.That the speaker is not a Dark Elf, an Orc, a Khajiit, a High Elf, or an Argonian
(This is to save having to create multiple voice files for every race)

3. That you are in Anvil.
(Note "Anvil" is a dummy cell, it contains no objects at all. This is a trick so that a cell called Anvil shows up in the drop down menu. It allows a search for any cell containing the word Anvil, this includes all interiors which begin with Anvil ie AnvilCastle and all exteriors which begin with the word Anvil. The designers use this trick to create catch-all words for the key areas like Arena, Bruma, IC , Skingard etc. The game searches for all instances of Anvil in the text name.)

4. That the speakers are locals.
(Anvil Faction. Factions are a way of creating sets to group actors by)

5. That the speaker is not Velwyn Benirus.
(So he doesn't gossip about himself)

6. That Velwyn Benirus is, in fact, alive.
(This is a belts and braces approach since Velwyn is marked as an essential actor and can't be killed. But the game may be modded so he can die. If this happens the quest is broken, since this dialogue can never be triggered)

7. That the other character - called the target - is also not Velwyn.
(To prevent the rumours from being directed at Velwyn)

When you hear this conversation, the game carries out two actions as directed by the response information:

1. It adds a new topic called Velwyn Benirus Topic so that this can be activated by a dialogue. (See topic box on RHS)

2 It links or moves to a new conversation called TRANSITION.
(This is in fact a sequence of coughs, ums and ahs that merely end conversations.)

The key action here is the New Topic.

This is a TOPIC and is accessed by you, as the player, opening a dialogue with the NPCs. But not just any old NPC, No! Again there are conditions.

Look under the VELWYN BENIRUS TOPIC in the topic tab. You'll find five entries.
We are interested in the last one that directs the character to the Count's Arms.
(Generally conversations are added so that the one you want to appear first in the game is last on the list)

It is conditional on the following:

1. A list limiting the NPC's race
2. You are in Anvil
3. The speaker is from Anvil
4. The Quest has not reached stage 10
5. The speaker is not Velwyn

So provided you speak to a human, Anvil local in Anvil before you've started the quest and after you've heard the conversation about Benirus, you will get a chance to find out he hangs out at the Count's Arms. (Phwew!.)

And THEN the really cool bit.

Under Results in this dialogue, it progresses the Quest to STAGE 10 using:

SetStage MS02 10

Immediately the quest moves to and through Stage 10. When we arrive at a stage, the game carries out its instructions.

Stage 10

It taken us some time, but finally we are truly off and running.

Let's look at the Quest Stage tab to see what Stage 10 is all about.

Following the dialogue, the program now executes STAGE 10.

This adds this journal entry to your characters journal:

I've overheard a rumor that Velwyn Benirus wants to sell a manor here in Anvil, and that he's selling it cheap. I should go find him and see what he has to offer.

That is it, nothing else. (Remember that, every 5 seconds or so, the game is still trying to run that Quest Script and failing its conditions).

One of the greatest features of the game is the fact that it does not progress you automatically to the next stage in a quest. You can now rush off to the Count's Arms to find out about the house or, you can go off and save the world, or kill a few innocent civilians.

It's your call.

The quest waits patiently for you to make the right move. In this case it's a conversation with the man Velwyn himself. The designer needs to show us where the man is. We have information via the quest journal we can refer to, but the Target Tab will help give us a visual clue.

This leads us to one of the hottest topics on the forums. That is the Quest Target arrows that appear on the Maps. Some folk love 'em, some folk loathe 'em. By giving a dialogue and journal clue we can ignore the map. However, others will need that extra help. The controls for these are contained under the quest Target Tab. It simply lists the target and the condition under which that target should be set. This is usually linked to a stage.

Here it sets VelwynBenirusRef (Velwyn's NPC Actor object in the objects window. (from here on, if I refer to Velwyn, I am referring to this NPC object) as the target if we have passed stage 10. Following the arrows will lead you to Velwyn. The map will update automatically to show where the target is.

When we find him he will use the GREETING topic to say hello to us. He has several possible greetings which again are conditional on the progress through the quest. The one that really matters the first time we speak to him is the one at the bottom. However, note that it is not conditional that you have reached stage 10.

This is important. If you come across Velwyn before you've heard the rumour mill that started the quest, it would be silly if he didn't mention his house for sale. So the quest makes no precondition. This is important. ALL STAGES are not essential. You can, depending on your actions in game, skip some stages. (When designing a quest try to remember that players can do all sorts of surprising things that will affect the dynamics of your quest. Get others to play test, who have not been directly involved in the quests development and give them very little lead-in information.)

The result of this conversation is as follows:

It sets MS02 Stage to 20

This adds another Journal Entry:

I've met Velwyn Benirus. He has a manor house for sale here in Anvil. I should question him further to see how much he wants for it.

It increments a variable called MS02.MetHim to 1.

(This lets the game know that you've now met Velwyn and know about the house. If you end the conversation here, the game will use a different greeting next time to indicate that you've already met this character before, and save repetition. Again this anticipates the chance a player may not want to rush straight on with the quest.)

Finally it opens a new topic called Manor.

Stage 20

When you select Manor (either straight away or at a later stage), it again looks for the correct response.

The different responses reflect the stage you are at. The designers generally have set responses from bottom to top in stage order. This matters because, when there is more than one response that meets the conditions, the game uses the first it come to.

In this case, both the bottom responses are valid.

The first is a longer speech introducing you to the manor. It is flagged as say once so that it not repeated. The second time you ask about the manor you will get the second response.

The first response adds a set of choices into the topic menu. These allow you to either buy the manor or decline. If you decline, it produces a simple neutral response and stalls the quest...

If you accept the offer, the next action is initiated.

It produces a response depending on whether you can actually pay or not. (See conditions)

If you can pay and you do accept, the following result script attached to the dialogue runs:

player.additem BenirusManorKey 1
player.additem MS02BenirusDeed 1
player.removeitem gold001 5000
setstage MS02 30

This set the stage to 30

This is a significant development.

Stage 30

Stage 30 is the first stage with a results script.

Go to the Quest Stage Tab and look at Stage 30. It has a results script:

set MS02.fQuestDelayTime to .1
VelwynBenirusRef.moddisposition player 30
MS02PlayerDoor.SetOwnership
MS02PlayerDoor02.SetOwnership
SetCellOwnership AnvilBenirusManorHaunted

Also, one of the pre-conditions contained in the quest script is now met, so some of it will also now run.

Finally we get another Journal update.

I've purchased the manor from Velwyn. He gave me a key and the deed of ownership. I can now move in there at any time.

And a target tab update to show the location of the house.

All that just by clicking the Yes option in the Topic Menu of an NPC.

I know all that scripting can be very confusing and I will try to explain it, but I want to hold off just for one moment until we encounter the next bit of scripting.

For now what we need to know is that the results of the script are:

• You get a key
• You get a deed
• You lose 5000 gold
• You become the house owner
• Velwyn likes you more
• And, when you get close enough to the house, the quest stage is moved to 35.

Stage 35

This stage produces a journal update:

I've arrived at my new house in Anvil, Benirus Manor. Looks like the place may need some work, but it was a great deal I just couldn't pass up. I can now make myself at home.

Again the quest goes into wait mode.

The Quest script is waiting for the PC to meet the next set of conditions.

In this case the condition is going to sleep in the house. When this happens you are woken by three ghosts that attack you (controlled by the Quest script).

Let's look at the cell called AnvilBenirusManorHaunted.

This is the house interior cell. If you notice some unusual render effects when looking around, this is because this cell contains two versions of the house superimposed on each other. In the game only one is enabled (visible) at a given time.

Look for the three Ghosts surrounding the bed called:

MS02FirstGhosts.
Click on any one of them, select edit base and then click on the ••• next to script and we see yet another script that is used in this quest.

Scriptname MS02FirstGhosts

short FirstGhosts

begin onDeath

;This part of the script enables the inital Ghost Generation & Sets Journal 40
set MS02.GhostJournal to MS02.GhostJournal + 1
if ( MS02.GhostJournal == 3) && ( GetStage MS02 <=35 )
      SetStage MS02 40
      VelwynBenirusRef.EvaluatePackage
      VelwynBenirusRef.MoveTo MS02VelwynArrivalMarker
endif
end

Now is a really good time to take a break from our dissection and look in a little more detail at script rules. I have again included this in an appendix section.

(I also need a refill and snack, so I'll see you in "A beginner's guide, lesson 5 - Anatomy of a quest, part 2".)