Script function

world.AddTimer

Type

Method

Summary

Adds a timer

Prototype

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

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 (see rules for names below)
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

* Rules for names

Names of triggers, aliases, timers and variables must follow these rules:

a. Start with a letter (A-Z)
b. Be followed by letters (A-Z), numbers (0-9) or the underscore character (_)

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

See Also ...

Topics

Aliases
Default triggers/aliases/timers/macros/colours
Getting started
Groups
Plugins
Timers
Triggers

Functions

(DeleteGroup) Deletes a group of triggers, aliases and timers
(DeleteTemporaryTimers) Deletes all temporary timers
(DeleteTimer) Deletes a timer
(DeleteTimerGroup) Deletes a group of timers
(DoAfter) Adds a one-shot, temporary timer - simplified interface
(DoAfterNote) Adds a one-shot, temporary note timer - simplified interface
(DoAfterSpecial) Adds a one-shot, temporary, timer to carry out some special action
(DoAfterSpeedWalk) Adds a one-shot, temporary speedwalk timer - simplified interface
(EnableGroup) Enables/disables a group of triggers, aliases and timers
(EnableTimer) Enables or disables an timer
(EnableTimerGroup) Enables/disables a group of timers
(GetPluginTimerOption) Gets the value of a named timer option for a specified plugin
(GetPluginTriggerOption) Gets the value of a named trigger option for a specified plugin
(GetTimer) Gets details about a timer
(GetTimerInfo) Gets details about a timer
(GetTimerList) Gets the list of timers
(GetTimerOption) Gets the value of a named timer option
(ImportXML) Imports configuration data in XML format
(IsTimer) Tests to see if a timer exists
(ResetTimer) Resets a named timer
(ResetTimers) Resets all timers
(SetTimerOption) Sets the value of a named timer option

(Help topic: function=AddTimer)