TIMER
|
- This page discusses how to get HSL calls at regular intervals via the TIMER datatype.
TIMER is a complex data type that causes a call to an HSL script after a specified interval of time.
Overview
Managing the concept of time, intervals and timers is important in MMOs. In particular, MMOs have various unusual needs for keeping track of time. For example, some game systems might work on real time (called "wall time", as in what time the "clock on the wall" says it is), vs. time that only elapses while logged on. Many common MMO game-play features, such as enhancements / buffs /etc. can be implemented using a Timer. HeroEngine timers contain important features such as the ability to be paused (for example, if a player is talking to the game-staff for customer service, a script can pause timers that might otherwise go off when it isn't appropraite, such as bleeding to death, etc.).
A timer is implemented as a field data type that causes a script call after a specified interval of time. HSL timers are like .NET timers in that they automatically repeat. If a scripter wants a 1-shot timer, they build removal or stopping of the timer into the tick() functionality.
When the timer's timespan has elapsed, a call is made to either a function or method with the format of <timer_field_name>_tick(). If the script subfield is set to a valid script, the function in that script is called; otherwise, the method is called on the node containing this timer field.
Related datatypes
Subfields
TIMER is a complex data type with member subfields.
timerState
- Type: Enumeration (ON, OFF, and PAUSED)
- Tracks the current state of the timer.
realTime
- Type: Boolean
- When true, the timer experiences time while not loaded. When loaded, a timer with this flag set to TRUE will call tick(), exactly once, if it is due to fire. It is a runtime error to modify this flag when timerState is not null or OFF.
startTime
- Type: DateTime
- Holds the timestamp of when start() was run.
stopTime
- Type: DateTime
- Holds the timestamp of when stop() was run.
lastFired
- Type: DateTime
- Holds the timestamp of the timer's last call to tick(), or SYSTEM.TIME.STARTDATE if the timer has never called tick().
- Is set following the call to tick(), to the value of SYSTEM.TIME.NOW during that call.
fireRate
- Type: TimeInterval
- Holds the time to elapse between calls to tick().
- A fireRate equal to SYSTEM.TIME.NULLTIME prevents the timer from firing.
- fireRate may only be changed when timerState equal to OFF
elapsedTime
- Type: Time Interval
- Holds the amount of time since the last call to tick().
- Is set following the call to tick(), to the value of SYSTEM.TIME.NOW during that call.
pausedTime
- Type: Time Interval
- Holds the cumulative time spent in a paused state.
script
- Type: Script Ref
- Holds the script for calling tick()
timerTimeSource
(timerTimeSource is an upcoming feature in a future HeroEngine update)
- Type: Enumeration [COORDINATED, LOCAL] (default is COORDINATED)
- tracks which time source the timer should use for its time calcualtions
Functions
The TIMER data type also has member functions that can be called.
start()
- Calls initialize() in script;
- Sets timerState to ON;
- Sets initializedTime to SYSTEM.TIME.NOW, and;
- Sets lastFired to SYSTEM.TIME.STARTDATE;
- Clears pausedTime;
- Clears and begins incrementing elapsedTime.
- Calling start() when timerState is not equal to OFF throws a runtime error.
stop()
- Sets timerState to OFF;
- Ends incrementing elapsedTime, and;
- Ends incrementing pausedTime.
- Calling stop() when timerState is not equal to ON or PAUSED throws a runtime error.
pause()
- Sets timerState to PAUSED;
- Ends incrementing elapsedTime, and;
- Begins incrementing pausedTime.
- Calling pause() when timerState is not equal to ON throws a runtime error.
unpause()
- Sets timerState to ON;
- Begins incrementing elapsedTime, and;
- Ends incrementing pausedTime.
- Calling unpause() when timerState is not equal to PAUSED throws a runtime error.
forceTick()
- Forces the timer to fire immediately, doing all the things it would normally do when it fires, like setting lastFired and clearing elapsedTime.
- It is permissible to call forceTick() for any timerState (ON, OFF, or PAUSED). Doing so does not cause timerState to change.
timeRemaining()
- Returns a Time Interval until the next call to tick() will occur.
- Calling timeRemaining() when timerState is equal to OFF throws a runtime error.
initializeDefault()
- Sets timerState to OFF.
- Sets timerType to GENERAL.
- Sets realTime to FALSE.
- Sets nextTickAlt to FALSE.
- Sets startTime to SYSTEM.TIME.STARTDATE.
- Sets stopTime to SYSTEM.TIME.STARTDATE.
- Sets lastFired to SYSTEM.TIME.STARTDATE.
- Sets fireRate to SYSTEM.TIME.NULLTIME.
- Sets elapsedTime to SYSTEM.TIME.NULLTIME.
- Sets pausedTime to SYSTEM.TIME.NULLTIME.
- Sets script reference to NONE.
Examples
Create field "custom_timer"
: cfd "custom_timer" timer;
Define "candle" class, with the above field.
: ccd "candle", asset, custom_timer; --> Node 4 (for example)
The following example assumes that a class GenericTimer has already been created, which has a timer field named myTimer
function foo() n as NodeRef of Class GenericTimer = CreateNodeFromClass("GenericTimer") n.myTimer.script = SYSTEM.EXEC.THISSCRIPT n.myTimer.fireRate = 0:05:45 n.myTimer.realTime = true n.myTimer.start() . function myTimer_tick() where me is kindof GenericTimer if (me.myTimer.elapsedTime.inMilliseconds > 100) println( me.myTimer.lastFired.hour ) println( me.myTimer.startTime.monthString ) . me.myTimer.stop() . .
