Editing A beginner's guide, lesson 5 - Anatomy of a quest, part 2

'''TES IV: Oblivion Modding for Beginners'''

'''B. Scripts, Quests and NPC's'''

'''Lesson Five: Anatomy of a Quest. Part Two'''

'''Preamble'''

This is the fifth 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:

'''[http://www.tessource.net/files/cache/4865.html Download the following three files from here (external link)]'''

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 containing the text for the first 5 lessons (as requested).

=='''Introduction'''==

This is a continuation of our dissection of a quest. We are about to
get a bit technical, and I am going to recommend a nice little utility
called "the script dumper". If you drag an '''esp''' or '''esm''' over the
executable file, it creates a folder containing the named scripts for
that '''esp''' or '''esm'''. The scripts are produced in HTML form. And this is
the really cool bit - all the commands and functions will have links
to the relevant page on the Wiki. I've found this very useful. You
don't need it but it can be a good labour saving device. (Note: It
does not look at results scripts).

=='''MS02 Script Analysis'''==

Let's look then at the scripts that have run so far in this quest.

All the writing in ''italics'' are comments by me explaining what the
script does.

Most Functions have syntax like this:

OBJECT_REFERENCE  <sub>&bull;</sub> FUNCTION   TARGET_REF PARAMETER(s)

For example,  player.additem BenirusManorKey 1

First let's look at the dialogue '''Result Script''' which ran when
the manor was bought.

'''player.additem BenirusManorKey 1'''

''(This adds the key object BenirusManorKey to the player's inventory.
The number 1 denote how many keys are added. Additem is a commonly
used function. Note the period between player and additem, and no
space between '''add''' and '''item'''. The target reference must be a
container, which includes player)''.

'''player.additem MS02BenirusDeed 1'''

''(This adds 1 copy of a book item called MS02BenirusDeed. Note this
purely cosmetic. The deed does not actually transfer ownership; it is
just a bit of window dressing)''.

'''player.removeitem gold001 5000'''

''(Removes 5000 gold from the player. This can cause problems if the
player has not got the money in his inventory. Take care to set
conditional checks before you remove money or items as you can get
minus values still appearing in an inventory.)''

'''setstage MS02 30'''

''(This sets the quest stage to 30)''

The SetStage to 30 triggered a '''quest result script'''

'''set MS02.fQuestDelayTime to 1'''

''(This is a useful bit of code. The FQuestDelayTime float variable is
a kind of a hybrid global variable. It has to be declared but the
system knows what you mean by it. It is used to set the time between
quest scripts running. This is a default 5 seconds. This line changes
that to '''1 second''' for this '''script'''.)''

'''VelwynBenirusRef.moddisposition player 30'''

''(This is not a reference script so we need to say VelwynBenirusRef,
so the game knows who we are talking about. The function is a part of
a family of functions of the form '''mod''' something. In this
case in modifies the disposition of the player by adding 30 to it.)''

'''MS02PlayerDoor.SetOwnership'''

(''This is a function of the '''set''' something family. It
sets the ownership of the door. By default if '''no target
reference''' is given, the target is assumed to be the
'''player''').

'''MS02PlayerDoor02.SetOwnership'''

(''As above'')

'''SetCellOwnership AnvilBenirusManorHaunted'''

''(Slightly different format because it '''sets''' a whole
cell ownership, not an object, no target=player)''

Then the quest Script blocks where finally able to run

 '''Scriptname MS02Script'''
 ''(Unique script name)''
 
 '''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'''
 
 ''(Declares not only the variable for the quest script but for all
 the results and dialogue scripts)''
 
 '''begin menumode'''
 ''(This begins the script only when the player is using one of the
 menus.  F2 or sleeping for example)''
 
 ''';This part of the script enables ghost attacks if player sleeps'''
 
 ''(This is a developer comment denoted by the semicolon (''';''')''
 ''You must include a ''';'''  at the start of every comment line. ''
 ''Do not use my example here and write in italic the game does not like it.)''
 
 '''if ( GetStage MS02 &gt;= 30 ) &amp;&amp; ( GhostGen == 0 )'''
 
       '''if ( IsPCSleeping == 1 &amp;&amp; player.getincell AnvilBenirusManorHaunted == 1 )'''
 
 ''(A set of '''nested if''' conditions. '''IF''' statements are the bread and butter of scripting. As such I will save a special place for them in the next tutorial. Just for now note double '''==''' for '''equal to''')''
 
 '''MS02GhostTest1Ref.Enable'''
 '''MS02GhostTest2Ref.Enable'''
 '''MS02GhostTest3Ref.Enable'''
 ''(These three creatures were as set up in game as initially disabled (invisible and inactive)''
 
 '''WakeUpPC'''
 ''(Not your computer but the Playing Character)''
 
 '''set GhostGen to 1'''
 '' It is included in the '''if statement''' as being '''true''' if it is = 0.''
 ''This line set the value to 1.''
 ''(Note for Basic programmers: it uses "TO", not "=" to do this,  ie "set X to 1", not "set X=1 )''
 ''From now on this '''IF block''' will be '''false''' unless we reset GhostGen back to zero.''
 ''Do once checksums are another Bread and Butter tool in scripting.''
 ''Hence the large number of Doonce variable declared at the top of the script'')
 
   '''endif'''
 '''Endif'''
 (''Closes the IF statement'')
 
 '''end'''
 ''(ends the block)''
 
 '''begin gamemode'''
 (''begins this block whenever the game is in normal game mode. Note
 the game has been trying this from the very start of the game, not
 just since the above block ran'')
 
 '';This triggers new journal when first arriving at manor''
 ''(developers comments)''
 
 '''if ( GetStage MS02 == 30 )'''
       '''if ( Player.GetDistance MS02BenirusManorWaitFollow &lt;= 500 )'''
 (''This uses one of the '''Get'''something family of functions to find the distance of the player from an x-marker in the Benirus Manor Cell. Look in the cells object list. '''Get''' type functions are information retrieval functions'')
  
 	 '''setstage MS02 35'''
 	 (''Set the stage to 35'')
 	 '''endif'''
 '''endif'''
 
 '''End'''
 
Finally there is the script attached to the ghost:
 
''(Note the indenting of script is for clarity rather than function)''
 
 '''Scriptname MS02FirstGhosts'''
 
 '''short FirstGhosts'''
 
 '''begin onDeath'''
 ''(Begins when the Actor (ghost) dies. Because this is a reference script attached to the ghost it assumes we mean when the ghost dies, and we don't have to give a reference)''
 
 ''';This part of the script enables the inital Ghost Generation &amp; Sets Journal 40'''
 
 '''set MS02.GhostJournal to MS02.GhostJournal + 1'''
 ''(This is a counter that adds to the variable mentioned in the quest script. By referencing using "MS02."  we can add to it.)''
 
 '''if ( MS02.GhostJournal == 3) &amp;&amp; ( GetStage MS02 &lt;=35 )'''
       '''SetStage MS02 40'''
       ''(Set the stage to 40 when all three ghosts are dead)''
 
 '''VelwynBenirusRef.EvaluatePackage'''
 
 ''(This is another really useful bit of script. It is a forced
 Evaluation of the AI Package that an NPC is using. It is used when we
 change a key game condition that affects packages and want it to have
 an immediate effect. Normally Actor evaluate its AI once an hour. 
 When evaluating it choses the first valid AI package in its list'')
 
 '''VelwynBenirusRef.MoveTo MS02VelwynArrivalMarker'''
  ''(This is a Teleport instruction. It instantly moves the Actor
 Velwyn Benirus to a marker in the Imperial City, The King and Queen Tavern)''
   '''endif''' 
 '''end'''

=='''Stage 40'''==

Okay let's get back to the quest and continue to follow its progress. 

Stage 40 updates the journal

''Benirus Manor is haunted! I was awakened by ghosts that attacked me
as I slept. As I awoke, I thought I heard a crash from downstairs. I
should search the house and investigate.''

And runs this script

Script for stage 40

 ;HouseChange
 
 RFDpot01broke01Ref.Enable
 PotLidRef.Enable
 CandleFat01Yellow64FellRef.Enable
 MS02SkeletonHandRef.Enable
 MS02'''LorgrenDiaryRef'''.Enable
 MS02SkeletonHandRef.Playgroup Forward, 1
 set MS02.fQuestDelayTime to 0
 
 This '''enables''' a lot of objects in the house which were previously '''disabled. '''
 Look for the references in the render window.
 It also animates the Skeleton hand.
 Among the objects enabled is '''Longren's Diary'''. 
 When the player picks this up in the game it activates this ''script attached to the diary''.
 
 '''Scriptname MS02LorgrenDiaryScrapScript'''
 
 '''begin OnActivate'''
 
 '''if ( GetStage MS02 &gt;=40 ) &amp;&amp; ( IsActionRef Player == 1 )'''
 ''(IsActionRef Player is another really useful script function  that makes sure it is the player who has activated a scripted object not a NPC)''
 '''Activate'''
 ''(Opens the diary so you can read it)''
 '''setstage MS02 45'''
 ''(Sets the stage to 45)''
 '''endif'''
 
 '''End'''

=='''Stage 45'''==

We get another journal update.
 
''I've found a skeletal hand next to a page from a diary. The diary
makes mention of a secret room in the house that only a true-blooded
Benirus can open. I am going to need to talk to Velwyn about this. I
may have to ask around town to find out where he's gone.''

And the results script runs

 ''';This part of the script enables the ghosts'''
 
 '''MS02BenirusGhostARef.Enable'''
 '''MS02BenirusGhostBRef.Enable'''
 '''MS02BenirusGhostCRef.Enable'''
 '''MS02BenirusGhostDRef.Enable'''
 '''MS02BenirusGhostERef.Enable'''
 '''MS02BenirusGhostFRef.Enable'''
 '''MS02BenirusGhostGRef.Enable'''
 
 This Enable a whole bunch of ghost creatures
 Each has this script attached to them.
  
 '''Scriptname MS02BenirusGhosts'''
  
 '''short GhostKill'''
 
 '''begin gamemode'''
 
 '''if ghostKill == 1'''
       '''Return'''
 
 ''(This ends the processing of the '''entire script''' for 1 frame. It will try again next frame, but all the lines below this one are not processed following the '''return''' command)'' 
     '''endif'''
 
 '''if ( GetStage MS02 &gt;= 90 ) &amp;&amp; ( GhostKill == 0 )'''
       '''Kill'''
       '''set GhostKill to 1'''
 '''Endif'''
 ''(This '''if block''' is used to get rid of the ghost near the end of the quest. It also sets ghostKill ==1 so that the return statement kicks in and prevent this script from running every frame)''
 
 '''if ( GetDisabled == 0 ) &amp;&amp; ( GetDead == 1 )'''
       '''if ( Getstage MS02 &gt;= 40 ) &amp;&amp; ( getstage MS02 &lt; 90 ) &amp;&amp; ( Player.GetInCell AnvilBenirusManor == 0 )'''
       '''Resurrect'''
       '''endif'''
 '''endif'''
 (''This block checks that the ghosts have been enabled (not disabled , and that you have killed a ghost and you are in the manor. It then resurrects the ghost. This means they will keep coming back'')
 
 '''end'''

We now have a house full of resurrecting ghosts. The next stage
advancement comes from the Topic Tab.

Under '''Velwyn Benirus Topic,''' two new responses become available
due to the new quest stage bump.

The first directs you to the '''Kings Arms.'''  The second, if you are
in the '''Kings Arms''', directs you to '''the Imperial City'''.  This
second dialogue also sets the stage to 50 in its results script.

=='''Stage 50'''==

Another Journal Update

''I've discovered that Velwyn has left town and made his way to the
Imperial City. If I am to find out why Benirus Manor is haunted, I
need to find him there.''

And a target update setting it to Velwyn Benirus. 

Again the quest stalls waiting for the next advancement. Are you picking up a pattern yet?

Generally, the technique is:

* Trigger a Stage, and do some changes to the settings to reflect the new status.
* Go into a hiatus, while we wait for the player to trigger the next action sequence
* When triggered, do the actions, then when it's done, trigger the next stage.

When you reach the Imperial City, we unlock, via the conditions set, two '''new''' valid topic '''responses''' for the '''Velwyn Benirus Topic'''.

The first directs us to the Elven Garden District if we are not
already there.  If we are there, we get directed to the King and Queen
Arms.  This second response also updates the Stage to 60.

=='''Stage 60'''==

The Journal gets updated

''I've been told that Velwyn stays in the King and Queen Tavern here
in the Imperial City. I should go there to find him.''

Talking to Velwyn updates the stage to 70 via a dialogue result.  The
second response is to cover the situation should you end the
conversation and return later.

=='''Stage 70'''==

''I've found Velwyn at The King and Queen Tavern in the Imperial
City. I should speak to him further about the manor and the strange
goings on within.''  

To progress to the next stage you have to navigate through a dialogue
with Velwyn. The dialogue is again conditional on you having collected
the '''skeleton hand''' and '''diary''', and that Velwyn '''LIKES'''
you. The disposition bump you got earlier on should help this.
But if you are a fairly unlovable character, you may need to play
the disposition game. When your disposition reaches 60, the results
script updates a variable called ManorLike to 1 and adds a new topic
'''Longren Bernirus''' to the Topic Menu.

Click on that and you get a lengthy response. This is too long to practically display on the screen at one go.  It is split into a sequence of linked responses. Each new line is linked using the '''|''' symbol.  After the speech, you get a new topic update, "'''Lifting the curse'''"  And a stage bump to 75.

=='''Stage 75'''==

Journal updates again

''After questioning Velwyn, I've learned that his grandfather dabbled
in necromancy and was killed when the townspeople of Anvil found
out. Strangely, the body was never recovered. Since then, the house
has been cursed. I need to convince Velwyn to come back with me to
Anvil and lift the curse.''

If you don't have the diary, Velwyn cuts you short. This is again
controlled by the conditioning in the topic responses.  If you do
have the diary Velwyn agrees to accompany you back to Anvil.  We
get another bump to Stage 80 in the dialogue result script.

=='''Stage 80'''==

The journal updates

''Velwyn agreed to meet me back in Anvil at the Count's Arms. I should
return there as soon as possible.''

The stage result script also gives you another disposition bump by 20.

Now it's time to look at another script which has been trying to run
and failing due to its '''If conditions'''. This one is attached to
Velwyn himself.

Find his character in the Actor NPC list in the object window of the
CS.  Double click to open it. The characters object window opens. We
will look at characters in the next lesson.

'''Before we look at the script you may wish to look at the appendix
to this lesson which looks at NPC Behaviour and AI packages. I have
separated it out as it is quite a detailed look at this complex
area. Read it and return here.'''  

Back to the Script. Select the &bull; &bull; &bull; next to Script

This script is a very complex one, mainly because it has been written
in an unusual manner. There may be good technical reasons for this or
it may be that new script was added later. However, the blocks are not
listed in strict chronological order. Rather than deal with it
en-bloc, let's break it up and look at it in bite-size chunks as they
become active due to conditions.

 '''Scriptname MS02VelwynScript'''
 
 '''short BenirusGreet'''
 '''short Doonce'''
 '''short Doonce1'''
 '''short Doonce2'''
 '''short Doonce3'''
 '''short SeeDoor'''
 '''short Duration'''
 '''float Timer'''
 '''float Timer2'''
 
 '';Move Velwyn back to Anvil from IC at Stage 80''
 
 '''begin gamemode'''
 
 '''if ( GetStage MS02 &gt;=80 ) &amp;&amp; ( MenuMode == 0 ) &amp;&amp; ( Doonce == 0 ) &amp;&amp; ( Player.GetInCell ICElvenGardensTheKingandQueenTavern == 0 )'''
       '''VelwynBenirusRef.MoveTo MS02VelwynReturnMarker'''
       '''VelwynBenirusRef.EvaluatePackage'''
       '''Set Doonce to 1'''
       '''endif'''
 
 '';Deals with Velwyn getting near the secret door''
 
 '''if ( Doonce3 == 0 )'''
       '''if ( GetStage MS02 &gt;= 87 ) &amp;&amp; ( VelwynBenirusRef.GetDistance MS02BenirusManorOpenSecretDoor &lt;= 400 )'''
       '''set SeeDoor to 1'''
       '''setstage ms02 88'''
       '''VelwynBenirusRef.EvaluatePackage'''
       '''Set Doonce3 to 1'''
       '''endif'''
 '''endif'''
 
 '';Stops the UseItem for SearchWall''
 
 '''if ( GetIsCurrentPackage MS02VelwynUsesDoor == 1 ) &amp;&amp; ( Duration == 0 )'''
       '''setpackduration 20'''
       '''set Duration to 1'''
 '''endif'''
 
 '''end'''
 
 '';Force greet when Velwyn gets inside of Manor and set Velwyn to Follow''
 
 '''begin onPackageEnd MS02VelwynManorEscort'''
  
 '''if BenirusGreet == 0 '''
       '''if ( GetStage MS02 &lt;= 85 )'''
       '''setstage MS02 87'''
       '''VelwynBenirusRef.StartConversation player, Greeting'''
       '''set BenirusGreet to 1'''
       '''set MS02.BenirusFollow to 1'''
       '''VelwynBenirusRef.EvaluatePackage'''
       '''endif'''
 '''endif'''
 
 '''end'''
 
 '';Deals with the actual secret door open and Stage 90 set''
 
 '''begin OnPackageEnd MS02VelwynOpensDoor'''
 	  '''set MS02.DoorCheck to 1'''
 	  '''VelwynBenirusRef.EvaluatePackage'''
 '''end'''
 
 '''begin OnPackageEnd MS02VelwynUsesDoor'''
 	  '''set MS02.Runaway to 1'''
 	  '''VelwynBenirusRef.EvaluatePackage'''
 	  '''setstage MS02 90'''
 	  '''BenirusDoorRef.Activate VelwynBenirusRef'''
 	  '''set Doonce2 to 1'''
 '''end'''
 
 This block is the first to become active (have its IF conditions met)
 
 '''if ( GetStage MS02 &gt;=80 ) &amp;&amp; ( MenuMode == 0 ) &amp;&amp; ( Doonce == 0 ) &amp;&amp; ( Player.GetInCell ICElvenGardensTheKingandQueenTavern == 0 )'''
       '''VelwynBenirusRef.MoveTo MS02VelwynReturnMarker'''
       '''VelwynBenirusRef.EvaluatePackage'''
       '''Set Doonce to 1'''
 
 (''This forces Velwyn back to Anvil as soon as the PC has left the
 tavern. The GetInCell check, prevents him just disappearing in front
 of the PC. Finally, it forces him to adopt his "back in Anvil" AI
 packages. Without this he would simply start walking back to the
 Imperial City for lunch'')
 
 '''Endif'''
 
Again we head for Anvil, or do as we like. In the tavern, talking to
him, forces a conditional greeting which adds two '''new topics'''
via the '''choice''' window offering to go to the manor to deal with
the ghosts.  
 
Selecting the '''not ready''' option '''stalls the quest'''
 
Selecting '''ready''' runs this result script:
 
 setstage MS02 85
 set MS02.BenirusEscort to 1
 VelwynBenirusRef.EvaluatePackage
 (''this sets Velwyn into an Escort package'')

=='''Stage 85'''==

''I've met Velwyn at The Count's Arms Tavern. He's agreed to escort me to the house and open the secret room.''
 
This forces Velwyn to evaluate his package selection.  A new AI
package will run called '''MS02VelwynManorEscort'''.(because it is the
highest valid package in the list). This will make Velwyn Escort
or stay close to you as you approach the manor.  When he meets
the conditions for this packages end, the next bit of the script
becomes valid.
 
 '''begin onPackageEnd MS02VelwynManorEscort'''
 ''(the package must complete for this block to run)''
 '''if BenirusGreet == 0 '''
       '''if ( GetStage MS02 &lt;= 85 )'''
       '''setstage MS02 87'''
 ''(bumps the stage)''
       '''VelwynBenirusRef.StartConversation player, Greeting'''
 ''(Forces a conversation. The actual greeting depends on whether you are inside or outside the house at the time)''
       '''set BenirusGreet to 1'''
 ''(do once checksum)''
       '''set MS02.BenirusFollow to 1'''
 ''(sets a variable to make the next package up the list valid. See Velywn's AI packages)''
       '''VelwynBenirusRef.EvaluatePackage'''
 ''(forces a package change)''
       '''endif'''
 '''endif '''
 '''End'''

=='''Stage 87'''==

''Velwyn and I have arrived in Benirus Manor. I must proceed cautiously
to the secret room's entrance and prevent any harm from befalling us
if the curse is to ever be lifted from this place.''

The next AI package, called '''MS02VelwynManorFollow''', will see him
follow you into the basement.

 ''';Deals with Velwyn getting near the secret door'''
 
 '''if ( Doonce3 == 0 )'''
       '''if ( GetStage MS02 &gt;= 87 ) &amp;&amp; ( VelwynBenirusRef.GetDistance MS02BenirusManorOpenSecretDoor &lt;= 400 )'''
       ''(Checks Velwyn is close to the secret door)''
       '''set SeeDoor to 1'''
       '''setstage ms02 88'''
       '''VelwynBenirusRef.EvaluatePackage'''
       ''(Forces yet another change in AI based on the fact that SeeDoor is now 1)''
       '''Set Doonce3 to 1'''
       '''endif'''
 '''endif'''

=='''Stage 88'''==

''Velwyn and I have arrived at the secret door.''

This stage sees Velwyn's script execute its final actions.

This first bit effectively creates a 20 second delay in the action to
allow the package where Velwyn approaches the door and waves his hands
about to play out.

 '';Stops the UseItem for SearchWall''
 
 '''if ( GetIsCurrentPackage MS02VelwynUsesDoor == 1 ) &amp;&amp; ( Duration == 0 )'''
       '''setpackduration 20'''
       '''set Duration to 1'''
 '''endif'''

Now we get to the final part of the script. When Velwyn re-evaluates
his AI Package he should start the MS02VelwynOpenDoor package.  There
is a minor omission in the script here.  There is no forced
evaluation, and occasionally users have complained that Velwyn just
stands by the door waving his hand about.  Eventually he breaks the
loop, normally after the 20 second delay.  The Duration to 1 check
enables the MS02VelwynOpenDoor package.  When this has run its course
the final part of Velwyns script kicks in.

 '';Deals with the actual secret door open and Stage 90 set''
 
 '''begin OnPackageEnd MS02VelwynOpensDoor'''
 	  '''set MS02.DoorCheck to 1'''
 	  '''VelwynBenirusRef.EvaluatePackage'''
 	  ''(Forces next package, to simulate door opening activity'')
 '''end'''
 
 '''begin OnPackageEnd MS02VelwynUsesDoor'''
 	  '''set MS02.Runaway to 1'''
 	  '''VelwynBenirusRef.EvaluatePackage'''
 ''(Sets Velwyn's behaviour so he will run away. Controls any dialogue you try to have with him)''
 	 '''setstage MS02 90'''
 	 ''(Bumps the stage)''
 	 '''BenirusDoorRef.Activate VelwynBenirusRef'''
 ''(This actually opens the door. All the rest of the bits above have been fluff and filler aimed at making Velwyn simulate opening the door. This is the only command needed to ACTUALLY open the door)''
 	 '''set Doonce2 to 1'''
 '''end'''

=='''Stage 90'''==

''Velwyn successfully opened the door to the secret room, which has
stopped the ghosts from attacking. He then ran off, leaving me to
clean up the mess. It's up to me, and me alone, to investigate what's
beyond the mysterious portal.''

The door has its very own script attached to it. Of course it has.

 '''Scriptname MS02SecretDoor '''
 
 '''Begin [[OnActivate]]'''
 ''(starts when the door is activated)''
 
 '';Activation capability for door after stage 88 and post quest''
 
 '''if ([[GetStage]] MS02 &gt;= 110 ) &amp;&amp; ([[IsActionRef]] [[Player]] == 1 ) [[Activate]]'''
 ''(This block means the door will open only for you, once you complete the quest)''
   '''elseif ([[GetStage]] MS02 &gt;= 90 ) &amp;&amp; ([[IsActionRef]] VelwynBenirusRef == 1 ) [[Activate]]''' 
 ''(This block means the door will only open for Velwyn until you complete the quest)''
   '''endif '''
 '''End '''
 '''Begin [[GameMode]]'''
 '''Unlock'''
 '''End '''

Velwyn, when he re-evaluates his AI status, will find the next valid
package forces him to flee to the Counts Arms. He will run and must
complete this package. The game again stalls here.

You can go off and complete all the other quests if you wished, and this quest would wait patiently idling along waiting for the next trigger.
<br>This comes when you activate the Altar.
<br>This object has a script attached.
<br>This is a really clever but complicated bit of scripting.

 ''' [[Scriptname]] MS02LorgenAltar'''
 
 '''short Doonce'''
 '''short LorgrenBlab'''
 '''float Timer'''
 ''(sets the variables)''
  
 '''[[<u>Begin</u>]] [[<u>OnActivate</u>]]'''
 ''(starts when the altar is activated)''
 
 '''if ([[GetStage]] MS02 &gt;= 90 ) &amp;&amp; ([[GetStage]] MS02 &lt; 100 ) &amp;&amp; ([[IsActionRef]] [[Player]] == 1 ) &amp;&amp; ( Doonce == 0 )'''
 
 ''(Checks that we are at the correct stage and that we haven't activated the altar before)''
 
 '''[[Set]] LorgrenBlab to 1'''
 '''[[Set]] Doonce to 1'''
 ''(sets some checksum values to control the in game Mode script)''
 '''endif '''
 
 '''[[End]]'''
 
 '''[[Begin]] [[GameMode]]'''
 
 '''if ([[GetStage]] MS02 &lt; 100 )'''
 '''[[Set]] timer to ( timer - [[GetSecondsPassed]])'''
 ''(This makes the value of the timer -1 , ie less than 0)''
 '''endif '''
 
 '''if (Timer &lt;= 0 )'''
   '''if ([[GetStage]] MS02 &lt; 100 ) &amp;&amp; ( LorgrenBlab == 1 )'''
   '''[[Set]] Timer to MS02LorgrenAltarRef.[[Say]] LorgrenSpeech 1 LorgrenBenirusNPC 1'''
 
 (''This is a very complex bit of script but is also very elegant. ''
 ''It sets the value of the variable '''Timer''' and at the same activates a conversation info called LorgrenSpeech.''
 ''Look this up in the '''topic tab''' for the quest.''
 ''The '''1''' forces the subtitles to be displayed.''
 ''When the LongrenSpeech starts it plays the first part of a long speech because LongrenBlab is set at 1 and this is one of the '''responses conditions'''.''
 '''''Now here is the really cool bit.'''''
 ''Whenever you use the '''Say''' function to force a speech, the Say function returns  a '''numerical value''' equivalent to the '''length''' of the mp3 file that '''still has to play'''.''
 ''So by setting the Variable called Timer to '''MS02LorgrenAltarRef.[[Say]] LorgrenSpeech 1 LorgrenBenirusNPC 1''', you set the timer value to the length of time this response still left to play. As long as this is a positive number the script will not pass its if statement.''
 ''Eventually the MP3 file stops and the value ''drops to zero. 

 ''The IF condition passes and the script moves on to the next bit of the speech'')
 
 '''[[<u>Set</u>]] LorgrenBlab to 2'''
   '''elseif ( LorgrenBlab == 2 )'''
 '''[[<u>Set</u>]] Timer to MS02LorgrenAltarRef.[[<u>Say</u>]] LorgrenSpeech 1 LorgrenBenirusNPC 1'''
   ''(repeats for each bit of the speech)''
 '''[[<u>Set</u>]] LorgrenBlab to 3'''
   '''elseif ( LorgrenBlab == 3 )'''
 '''[[<u>Set</u>]] Timer to MS02LorgrenAltarRef.[[<u>Say</u>]] LorgrenSpeech 1 LorgrenBenirusNPC 1'''
 
 '''[[<u>Set</u>]] LorgrenBlab to 4'''
   '''elseif ( LorgrenBlab == 4 )'''
 '''[[<u>Set</u>]] Timer to MS02LorgrenAltarRef.[[<u>Say</u>]] LorgrenSpeech 1 LorgrenBenirusNPC 1'''
 
 '''[[<u>Set</u>]] LorgrenBlab to 5'''
   '''elseif ( LorgrenBlab == 5 )'''
   ''(ends the speech run)''
 '''[[<u>SetStage</u>]] MS02 100'''
  ''(bumps the stage)''
   '''endif'''
 '''endif'''

=='''Stage 100'''==

''After touching the altar, I heard the voice of Lorgren Benirus. He
said he wished to atone for his past and make peace with the
Nines. All he wished was to be whole again. This must be the way to
lift the curse from Benirus Manor. I should touch his skeleton while I
carry the bony hand and put an end to this madness.''

Again we are in a Quest hold until we want to activate the skeleton.
When we do, you guessed it another bit of script kicks in.  Remember,
like all the named scripts we have looked at, this has been trying to
run in the background throughout the game. Every time we entered the
Basement it has run every frame and made little progress due to the IF
conditions inside the script. However, when we activate the skeleton,
all that changes.

 '''Scriptname MS02LorgrenBones '''
 
 '''short ILiveAgain '''
 '''short Doonce '''
 '''short LorgrenYap '''
 '''float Timer '''
 
 '''[[Begin]] [[OnActivate]]'''
 
 '''if ( [[GetStage]] MS02 &gt;= 100 ) &amp;&amp; ( [[GetStage]] MS02 &lt; 110 ) &amp;&amp; ( [[IsActionRef]] [[Player]] == 1 ) &amp;&amp; ( Doonce == 0 ) &amp;&amp; ( [[Player]].[[GetItemCount]] MS02SkeletonHand == 1 ) '''
 '''[[Set]] LorgrenYap to 1'''
 ''(Variable bump that allows GameMode to run)''
 '''[[Set]] Doonce to 1'''
 '''endif'''
 ''(this block uses the if conditions to set two control variables)''
 '''[[End]]'''
 
 '''[[Begin]] [[GameMode]]'''
 
 '''if ( [[GetStage]] MS02 &lt; 110 )'''
 '''[[Set]] Timer to ( Timer - [[GetSecondsPassed]] )'''
 '''endif '''
 
 '''if ( Timer &lt;= 0 )'''
   '''if ( [[GetStage]] MS02 &lt; 110 ) &amp;&amp; ( LorgrenYap == 1 )'''
   '''BenirusDoorRef.[[Activate]]'''
   '''BenirusDoorRef.[[Lock]] 100'''
   '''[[Set]] Timer to MS02LorgrenAltarRef.[[Say]] LorgrenLichSpeech 1 LorgrenBenirusNPC 1'''
   '''[[Set]] LorgrenYap to 2'''
 '''elseif ( LorgrenYap == 2 )'''
  '''[[Set]] Timer to MS02LorgrenAltarRef.[[Say]] LorgrenLichSpeech 1 LorgrenBenirusNPC 1'''
  '''[[Set]] LorgrenYap to 3'''
 '''elseif ( LorgrenYap == 3 )'''
  '''[[Set]] Timer to MS02LorgrenAltarRef.[[Say]] LorgrenLichSpeech 1 LorgrenBenirusNPC 1'''
  '''[[Set]] LorgrenYap to 4'''
 '''elseif ( LorgrenYap == 4 )'''
 '''[[Set]] Timer to MS02LorgrenAltarRef.[[Say]] LorgrenLichSpeech 1 LorgrenBenirusNPC 1'''
 '''[[Set]] LorgrenYap to 5'''
 '''elseif ( LorgrenYap == 5 )'''
 ''(This block does the same speech timer trick as before)''
 
 '''MS02LichMarker.[[PME]] MYTH'''
 ''(PME is shorthand for '''Preload Magical Effects'''. This is used for non-magical references which will display a magical effect, in this case an x-marker. It speeds up the processing to avoid any momentary delay in this effect.)''
 
 '''MS02LorgrenLichRef.[[PlaySound]] AMBBenirusLich'''
 ''(Plays a sound file. The game carries on as the file plays so you remain in control of your player)''
 '''[[PlayGroup]] forward ,0'''
 ''(Animates the Lich)''
 '''[[Player]].[[RemoveItem]] MS02SkeletonHand 1'''
 ''(Gets rid of the skeletal hand)''
 '''MS02LorgrenLichRef.[[Enable]]'''
 ''(enables the Lich creature)''
 '''[[Set]] ILiveAgain to 1'''
 '''[[Set]] LorgrenYap to 6'''
 ''(sets a couple of control variables)''
   '''endif'''
 '''endif'''
 
 '''[[End]]'''  

The Lich has of course got some more script attached.

 '''[[<u>Scriptname</u>]] MS02LorgrenScript'''
 
 '''<u>Begin</u> [[<u>OnDeath</u>]]'''
 '''<u>SetStage</u> MS02 110'''
 ''(this is the simplest script of them all. Creature Dead, bump Stage)''
 '''[[<u>End</u>]]'''


=='''Stage 110'''==

''Completing the skeleton was a ruse and Lorgren rose from the dead! I
had no choice but to destroy him. With his destruction, the curse of
Benirus Manor was lifted. I should return to The Count's Arms and
speak to Velwyn.''

And runs the following results script

 '''BenirusManorHauntedRef.Disable'''
 '''BenirusManorRef.Enable'''
 ''( In the cell containing the house interior are two overlapping interior sets, this switches which one is active or enabled. When you go back upstairs you will find the place better decorated and a lot nicer to live in)''
 '''BenirusManorExteriorHauntedRef.Disable'''
 '''BenirusManorExteriorRef.Enable'''
 ''( Does the same switch with the exterior cells.)''
 '''RFDpot01broke01Ref.Disable'''
 '''MS02HandLightRef.Disable'''
 '''PotLidRef.Disable'''
 '''CandleFat01Yellow64FellRef.Disable'''
 '''CandleFat01Yellow64okRef.Enable'''
 '''RFDpot01okRef.Enable'''
 ''(tidies up the broken pot from earlier in the quest)''

The quest is almost done.

All we have to do is go see Velwyn in the Kings Arms.

When we do this Velwyn will issue a brief statement, close the dialogue and set the stage to 120

=='''Stage 120'''==

''I have met Velwyn back at The Count's Arms. He congratulated me and
then told me he would be off again to live in the Imperial City. Now I
can truly call Benirus Manor my home.''

Stage 120  is the final stage in the quest.

First we get a quest journal update.

Then the following final bit of script runs.

The quest stage is marked as finishing the quest. 

This does not stop the quest from running, it merely moves the journal
entry from active to completed section of the players menu. To stop
the quest script running we use '''StopQuest''' command.

 '''ModPCFame 1'''
 '''VelwynBenirusRef.SetFactionRank AnvilFaction -1'''
 ''(Setting someone's faction value to -1 removes them from the faction)''
 '''VelwynBenirusRef.SetFactionRank ICFaction 0'''
 ''(setting someone's faction value adds that faction to the actors list. If the faction is marked as hide from PC, it will not show up. Only really relevant if the PC joins a faction and you want to decide if the faction will show up on the player's menus)''
 '''SetQuestObject BenirusManorKey 0'''
 ''(Removes the Quest Object status from the key so you can put it down)''
 '''SetQuestObject MS02LorgrenDiary 0'''
 ''(removes Diaries quest object status)''
 '''SetEssential VelwynBenirus 0'''
 ''(removes the essential status from Velwyn so you can kill him for causing you so much bother)''
 '''StopQuest MS02'''
 ''(END THE QUEST)''

I know this has been a marathon, but I hope the journey has been worth
while.  I believe that it illustrates the complex interrelationship
between scripts, quest, dialogue, objects and NPCs better than any
other method.

I hope that despite its complexity, the underlying structure has clearly been illustrated. To summarise: 

* The quest is set in a hiatus, where the PC can do any task they wish, and return to the quest when ready.
* The quest journal updates include an instruction that points the PC to the trigger which will move the quest on.
* When the PC triggers a specific trigger, a series of consequences are released which move the game along. 
* These set a number of variables that set up the next trigger. 
* The quest returns to a hiatus.

'''HOMEWORK:'''

While you wait for '''Lesson Six''', why not try a couple of things?

1. Choose a quest and see if you can reconstruct its path from rumour to completion.
Try to follow the scripts, and in particular see if you can find the Stage bumps.

2. The mod file contains both an unfinished house and dungeon. The house exterior is very rough around the edges, and the dungeon could do with a bit of tidying up. They both work and do the job, but they could do with a bit of decorating - but leave the farmhouse for now.

[[Category:A beginner's guide]]