Editing Scripting Tutorial: Creating a Simple Timer

Timers are one of the most useful code snippets in Oblivion scripting. Their uses range from remote spell casting to manipulating animation playback. One could find a use for them in almost every script. Timers also happen to be the least understood of scripting elements, especially so when it comes to learning the scripting language for the first time. It must be noted that there aren't as complex as they may seem - They are pretty easy to wrap your head around if you understand the basic logic behind ObScript.

For this exercise, we shall be creating a simple timer that displays a message after a certain amount of time passes.

{{Tools|req0=[[The Elder Scrolls Construction Set|Construction Set]]}}

== Requirements ==
Basic knowledge of:
* Coding
* The [[Tescs|Construction Set]] and its usage

== Commands and Functions used ==
* [[If]]
* [[Set]]
* [[Return]]
* [[GetSecondsPassed]]
* [[Message]]
* [[StopQuest]]


== Tutorial ==
* Start the Construction Set. We need not load the game's master file('''Oblivion.esm''') for this exercise for we will not be using any resources from it.
* Open the [[Edit Scripts|script window]] and use the File menu to create a new one. Set the script type to [[Quest script]]
* Start with the script name:
 scn <name of the script>
We shall call it '''timerTestScript'''.
* Declare a ''float'' [[variable]]. We shall call it '''timer'''
<pre>scn timerTestScript

float timer</pre>
Float is used as the data type because [[getSecondsPassed]] returns a [[floating point]] value, i.e., the time that has passed since the last time the function was called
* We shall now define the timer.
<pre>scn timerTestScript

float timer
float fQuestDelayTime

begin gameMode
     set fQuestDelayTime to 0.001

     if ( timer < 5 )
         set timer to timer + getSecondsPassed
     else                                                                
         Message "Your 5 seconds are up !"
     endif
end</pre>
The duration of the timer is set in the if condition. [[fQuestDelayTime]] is a special variable used in quest scripts to change their processing speeds.
* Save the script. Create a [[quest]] with the '''Start Game Enabled''' flag and attach the timer script to it
* Finally, save the plugin. Launch the game with it activated


== Mechanics ==
The quest script starts when the game is loaded. The [[gameMode]] block runs every frame. On each run ( in this case, every frame ), the timer variable is checked for the condition ( i.e., if it's less than 5 ). If the condition evaluates true, the timer variable is incremented with the value returned by the '''getSecondsPassed''' function.

When the condition evaluates false i.e., when the timer variable's value equals or exceeds 5, our message is displayed. Since '''getSecondsPasssed''' returns values that are comparable to realtime seconds, the script has effectively run for 5 seconds.

But the script doesn't end here - it keeps printing the message since the if condition checks only if the timer's value equals or exceeds 5. The If statement's condition can be modified to walk through this issue by adding a do-once catch.
<pre>scn timerTestScript

float timer
float fQuestDelayTime

short doOnce

begin gamemode
     set fQuestDelayTime to 0.001

     if ( doOnce )         ; the == operator isn't necessary when checking boolean values....
         return            ; ... the above expression is equivalent to (doOnce != 0)
     elseif( timer > 5 )    
         set doOnce to 1
         Message "Your 5 seconds are up"  
     else
         set timer to timer + getSecondsPassed
     endif
end</pre>


Alternatively, the timer variable can be decremented, after setting it to the duration of the timer. 
<pre>scn timerTestScript

float timer
float fQuestDelayTime

short doOnce

begin gamemode
     set fQuestDelayTime to 0.001

     if ( doOnce == 0 )
         set timer to 5   ; Initialize the timer variable
         set doOnce to 1
     endif
     
     if ( timer > 0 )                                                
         set timer to timer - getSecondsPassed        
     else                                                                
         Message "Your 5 seconds are up"
     endif  
end</pre>

The '''doOnce''' variable is used to make sure the initialization happens only once, i.e., during the script's first iteration. But this method not preferable as it calls more comparisons, is longer and needs initialization.

If you use a timer in your own mod, it may be helpful to make a new quest such as MRFiveSecondTimerQuest with the five second timer script on it (replace MR with whatever your initials are, or whatever your alias is to avoid other mod conflicts). Then when you want to initialize the timer, just call StartQuest <questName> and it should run the timer. Then you can replace the "Time's Up" message to set a variable, or do something else if you like. Also, make sure you call StopQuest <questName>, or it will continue to use system resources.

<pre>scn MRFiveSecondTimerQuestScript

float timer
float fQuestDelayTime

short doOnce

begin gamemode
     set fQuestDelayTime to 0.001

     if ( doOnce == 0 )
         set timer to 5   ; Initialize the timer variable
         set doOnce to 1
     endif
     
     if ( timer > 0 )                                                
         set timer to timer - getSecondsPassed        
     else                                                                
         Message "Your 5 seconds are up"
         StopQuest MRFiveSecondTimerQuest
     endif  
end</pre>


[[Category: Useful Code]]
[[Category: Tutorials]]
[[Category: Scripting_Tutorials]]

<!-- Begin Search Terms
 Timer
 Tutorial
 Timers
 Creating Timers
End Search Terms -->