AddTimer
Script function

world.AddTimer

DOC_scripting Read about scripting

Type

Method

Summary

Adds a timer

Prototype

long AddTimer(BSTR TimerName, short Hour, short Minute, double Second, BSTR ResponseText, long Flags, BSTR ScriptName);

DOC_data_types View list of data type meanings

Description

Adds a timer to the list of timers.

Timers can be used to cause something to happen periodically, either every x seconds, or at a certain time of day.

Periodical timers (which fire after a certain time has elapsed) are intended for periodical events (eg. save your world file every hour, drink a potion every minute, check your health every 10 seconds).

Timers that fire at a certain time of day are intended to do things like start a new log file at midnight, warn you if when it is time to go to work, that sort of thing. :)

You can make a "one-shot" timer that does something once, and then deletes itself. This is useful for making a single thing happen in the future (eg. in 5 minutes) rather than happening every 5 minutes.

You can use "DoAfter", "DoAfterNote", "DoAfterSpeedWalk" or "DoAfterSpecial" for a simplified way of adding timers.

TimerName: name of this timer - may be empty
Hour: The hour to fire (0 - 23)
Minute: The minute to fire (0 - 59)
Second: The second to fire (0 - 59.9999)
Response_text: what to send to the world
Flags: various flags, see list below
ScriptName: Which script subroutine to execute

Time Interval

From version 3.61 onwards of MUSHclient the seconds part of the time may include fractions (ie. it is a floating-point number). This lets you set up sub-second timers (eg. 0.5 seconds, 1.2 seconds).

To enable this you need to go to Global Configuration -> Timers and set the Timer Interval in seconds to zero.

The maximum granularity of the timers is currently 0.1 seconds.

Flags

The flags can be one or more of the constants below. For example, to enable the timer, and make it a one-shot, the flags would be 5. Preferably use the constant declarations in your script file, and "OR" them together. E.g.

VBscript: eEnabled or eOneShot
JScript: eEnabled | eOneShot
Lua: timer_flag.Enabled + timer_flag.OneShot


VBscript constants:

const eEnabled = 1 ' is timer enabled?
const eAtTime = 2 ' if not set, time is "every"
const eOneShot = 4 ' if set, timer only fires once
const eTimerSpeedWalk = 8 ' timer does a speed walk when it fires
const eTimerNote = 16 ' timer does a world.note when it fires
const eActiveWhenClosed = 32 ' timer fires even when world is disconnected
const eReplace = 1024 ' replace existing timer of same name
const eTemporary = 16384 ' temporary - do not save to world file


JScript constants:

var eEnabled = 1; // is timer enabled?
var eAtTime = 2; // if not set, time is "every"
var eOneShot = 4; // if set, timer only fires once
var eTimerSpeedWalk = 8; // timer does a speed walk when it fires
var eTimerNote = 16; // timer does a world.note when it fires
var eActiveWhenClosed = 32; // timer fires even when world is disconnected
var eReplace = 1024; // replace existing timer of same name
var eTemporary = 16384; // temporary - do not save to world file


PerlScript constants:

my $eEnabled = 1; # is timer enabled?
my $eAtTime = 2; # if not set, time is "every"
my $eOneShot = 4; # if set, timer only fires once
my $eTimerSpeedWalk = 8; # timer does a speed walk when it fires
my $eTimerNote = 16; # timer does a world.note when it fires
my $eActiveWhenClosed = 32; # timer fires even when world is disconnected
my $eReplace = 1024; # replace existing timer of same name
my $eTemporary = 16384; # temporary - do not save to world file

Lua constants (in the timer_flag table):

timer_flag.Enabled = 1
timer_flag.AtTime = 2
timer_flag.OneShot = 4
timer_flag.TimerSpeedWalk = 8
timer_flag.TimerNote = 16
timer_flag.ActiveWhenClosed = 32
timer_flag.Replace = 1024
timer_flag.Temporary = 16384

VBscript example

world.addtimer "my_timer", 0, 0, 1, "go north", 5, ""


Jscript example

world.addtimer("my_timer", 0, 0, 1, "go north", 5, "");


PerlScript example

$world->addtimer("my_timer", 0, 0, 1, "go north", 5, "");


Python example

world.addtimer("my_timer", 0, 0, 1, "go north", 5, "")


Lua example

AddTimer ("my_timer", 0, 0, 1.5, "go north", 
          timer_flag.Enabled + timer_flag.OneShot, "")


Lua notes

The script name is optional.

The timer flags are built into the "timer_flag" table, as follows:

Enabled = 1
AtTime = 2
OneShot = 4
TimerSpeedWalk = 8
TimerNote = 16
ActiveWhenClosed = 32
Replace = 1024
Temporary = 16384


Return value

eInvalidObjectLabel: The timer name is not valid
eTimerAlreadyExists: A timer of that name already exists
eScriptNameNotLocated: The script name cannot be located in the script file
eTimeInvalid: The time is invalid (eg. hour not in range 0 to 23).
eOK: added OK


DOC_errors View list of return code meanings

See Also ...

Topics

DOC_aliases Aliases
DOC_defaults Default triggers/aliases/timers/macros/colours
DOC_starting Getting started
DOC_group Groups
DOC_plugins Plugins
DOC_timers Timers
DOC_triggers Triggers

Functions

FNC_DeleteGroup DeleteGroup (Deletes a group of triggers, aliases and timers)
FNC_DeleteTemporaryTimers DeleteTemporaryTimers (Deletes all temporary timers)
FNC_DeleteTimer DeleteTimer (Deletes a timer)
FNC_DeleteTimerGroup DeleteTimerGroup (Deletes a group of timers)
FNC_DoAfter DoAfter (Adds a one-shot, temporary timer - simplified interface)
FNC_DoAfterNote DoAfterNote (Adds a one-shot, temporary note timer - simplified interface)
FNC_DoAfterSpecial DoAfterSpecial (Adds a one-shot, temporary, timer to carry out some special action)
FNC_DoAfterSpeedWalk DoAfterSpeedWalk (Adds a one-shot, temporary speedwalk timer - simplified interface)
FNC_EnableGroup EnableGroup (Enables/disables a group of triggers, aliases and timers)
FNC_EnableTimer EnableTimer (Enables or disables an timer)
FNC_EnableTimerGroup EnableTimerGroup (Enables/disables a group of timers)
FNC_GetTimer GetTimer (Gets details about a timer)
FNC_GetTimerInfo GetTimerInfo (Gets details about a timer)
FNC_GetTimerList GetTimerList (Gets the list of timers)
FNC_GetTimerOption GetTimerOption (Gets the value of a named timer option)
FNC_ImportXML ImportXML (Imports configuration data in XML format)
FNC_IsTimer IsTimer (Tests to see if a timer exists)
FNC_ResetTimer ResetTimer (Resets a named timer)
FNC_ResetTimers ResetTimers (Resets all timers)
FNC_SetTimerOption SetTimerOption (Sets the value of a named timer option)

(Help topic: function=AddTimer)

DOC_contents Documentation contents page