Show Posts
16
SCI Community How To's & Tutorials / Using timers
« on: January 29, 2007, 05:48:58 PM »
The Timer class in the template game has gone largely unused, and that
is a shame. So here's my attempt at explaining how to use it.
First, there is no need to instantiate an object unless you want to
change the timeout later on. The class methods are designed to take
care of that. Second, the Timer class works by cueing a script when it
expires. I can't recall whether that's in the documentation or not,
but it simply means incrementing the current state number by 1 and
calling changeState. Third, the only real advantage of the Timer class
is its mutator methods. All other functionality is available directly
in the Script class, so if your timing needs are simple, you don't
need this class at all.
Next, I'll describe the architecture of Timer (and Script, in this
regard) objects. There are actually two separate properties devoted
for timing: They are called 'cycles' ('cycleCnt' in the Timer class) and
'seconds'. The difference between them is (obviously) their
resolution and, consequently, also their range. A cycle in SCI
parlance is 1/60th of a second. Thus, the maximum range of a timer if
you choose to use the cycle counter is about 18 minutes. If you choose
to use the second counter, the range is about 45 hours.
The mutator functions I hinted at above are called setCycles, set, and
setReal, respectively. The first one is simple; it takes a cycle count
(which you would have to calculate yourself) and starts a new timer
with that timeout. You would call it like so:
(Timer:setCycle(RoomScript 30))
where RoomScript is the script that will be cued when the timer
expires. The timeout will be half a second (30/60).
The set method is a bit smarter. It automatically calculates the
correct cycle count given a count of seconds, minutes, and hours. This
method also adjusts the final count for the currently set game speed,
which is not always what you want. And it uses the cycle
counter (see above for a description); the real range of the Timer
class may vary if you use this method. You would use it like so:
(Timer:set(RoomScript 30))
for a thirty-second delay.
Finally, there's the setReal method. Like set, it
performs all calculations on its own, but it uses the seconds
counter, and it does not adjust for game speed. Thus, it is
ideal for game events that depend on how much "real time" passes.
However, it does not work out of the box due to a typo in the template
game. To fix it, find the doit method of the timer class (in
Timer.sc), and the line that says:
(if (not seconds)
CueClient()
)
Fix the first line so it reads:
(if (not --seconds)
and you're all set.
Finally, the cases where you don't need a Timer object. As I've
mentioned, the Script class has comparable properties (but no methods)
to the Timer class. So you can simply use your room script and the
cycles and seconds properties directly, if you are so inclined. This
is what Sierra did in most cases; you don't really see the Timer class
used much in the games. You would simply do
(instance RoomScript of Script
(method (changeState newState)
(super:changeState(newState))
(switch (newState)
(case 1
= seconds 15)
(case 2
Print("Time's up!")))))
When using the Timer class, you would similarly put your initialization code in case 1 above (or in a room's init method).
is a shame. So here's my attempt at explaining how to use it.
First, there is no need to instantiate an object unless you want to
change the timeout later on. The class methods are designed to take
care of that. Second, the Timer class works by cueing a script when it
expires. I can't recall whether that's in the documentation or not,
but it simply means incrementing the current state number by 1 and
calling changeState. Third, the only real advantage of the Timer class
is its mutator methods. All other functionality is available directly
in the Script class, so if your timing needs are simple, you don't
need this class at all.
Next, I'll describe the architecture of Timer (and Script, in this
regard) objects. There are actually two separate properties devoted
for timing: They are called 'cycles' ('cycleCnt' in the Timer class) and
'seconds'. The difference between them is (obviously) their
resolution and, consequently, also their range. A cycle in SCI
parlance is 1/60th of a second. Thus, the maximum range of a timer if
you choose to use the cycle counter is about 18 minutes. If you choose
to use the second counter, the range is about 45 hours.
The mutator functions I hinted at above are called setCycles, set, and
setReal, respectively. The first one is simple; it takes a cycle count
(which you would have to calculate yourself) and starts a new timer
with that timeout. You would call it like so:
(Timer:setCycle(RoomScript 30))
where RoomScript is the script that will be cued when the timer
expires. The timeout will be half a second (30/60).
The set method is a bit smarter. It automatically calculates the
correct cycle count given a count of seconds, minutes, and hours. This
method also adjusts the final count for the currently set game speed,
which is not always what you want. And it uses the cycle
counter (see above for a description); the real range of the Timer
class may vary if you use this method. You would use it like so:
(Timer:set(RoomScript 30))
for a thirty-second delay.
Finally, there's the setReal method. Like set, it
performs all calculations on its own, but it uses the seconds
counter, and it does not adjust for game speed. Thus, it is
ideal for game events that depend on how much "real time" passes.
However, it does not work out of the box due to a typo in the template
game. To fix it, find the doit method of the timer class (in
Timer.sc), and the line that says:
(if (not seconds)
CueClient()
)
Fix the first line so it reads:
(if (not --seconds)
and you're all set.
Finally, the cases where you don't need a Timer object. As I've
mentioned, the Script class has comparable properties (but no methods)
to the Timer class. So you can simply use your room script and the
cycles and seconds properties directly, if you are so inclined. This
is what Sierra did in most cases; you don't really see the Timer class
used much in the games. You would simply do
(instance RoomScript of Script
(method (changeState newState)
(super:changeState(newState))
(switch (newState)
(case 1
= seconds 15)
(case 2
Print("Time's up!")))))
When using the Timer class, you would similarly put your initialization code in case 1 above (or in a room's init method).