JS-MUD-CHARGES

The Mud charges methods are used to simulate items or spells or feats which can only be used periodically. For example, Reincarnation can only be used once every mud year.

There are three methods, and all take the same options:

Mud.useCharge( <object>, <prefix>, <options> ... )
Mud.showCharges( <object>, <prefix>, <options ... )
Mud.hasCharge( <object>, <prefix>, <options ... )

where options consist of the following:

'count', <count>      The item or feat can only be used count number of
                      times.
'timer', <seconds>    The item or feat's charges are recharged every
                      seconds seconds.

Additional, the 'status charges' command will cause the charges event to be sent to all auras and items on a character. If you implement an aura or item with a charged ability, you should handle the charges event and report the number of charges left using Mud.showCharges().

For example, if you wanted to create an Reincarnation ability that can only be used once per mud month, you could do:

abeh reincarnation javascript charges .
actor.msg( 'Reincarnation: '
  + Mud.showCharges( actor.db, 'reincarnation', 'timer', 1071000 ) );
/s
abeh reincarnation javascript deathblow .
if ( !Mud.useCharge( actor.db, 'reincarnation', 'timer', 1071000 ) )
  return;

// perform reincarnation code here
/s

There are 1071000 seconds for every mud year. See PULSE for more information on timing and intervals on the mud. Mud.useCharge() returns true and uses up a charge if there is a charge available. If there are no charges left, Mud.useCharge() will return false. In the above example, the Reincarnation code is only run if the there is a charge left.

The object and prefix options tell the mud where to store information about what charges are left. In this example, the time left will be stored in the actor's database object under the name "reincarnationX" where "X" will be replaced with either "Timer" or "Count" depending upon what kind of charged timer you are using. You do not normally need to mess with these properties.

If you specify both a count and a timer, then the methods will allow count charges every timer interval. For example:

..., 'timer', 1800, 'count', 3

Will permit 3 charges per mud day (there are 1800 seconds in a mud day).