CooldownLib

by Ter13
Handle attack/skill cooldown periods flexibly and simply (supports saving)
ID:2287774
 
cooldowns var (mob)

See also:
  cooldown_preserve var (mob)
  onCooldown() (mob)
  getCooldown() (mob)
  getCooldowns() (mob)
  setCooldown() (mob)

Default value:
  null

The cooldowns list is an associative list that stores string names for cooldowns associated with a world.time offset for when the cooldown was no longer relevant.

A cooldown with a time value ahead of or equal to world.time is still on cooldown, while a cooldown with a time value less than world.time is no longer on cooldown.

Cooldowns can be tested with getCooldown()/getCooldowns() and onCooldown(), and set with setCooldown().

Data in the cooldown list will save according to the rules in the cooldown_preserve associative list.




cooldown_preserve var (mob)

See also:
  cooldowns var (mob)
  setCooldown() (mob)
  Read() (mob)

Default value:
  null

The cooldown_preserve list is an associative list that stores string names for cooldowns associated with a saving flag value from StdLib. The possible values are:

PRESERVE_NONE (0)
PRESERVE_WORLDTIME (1)
PRESERVE_REALTIME (2)

This controls how cooldowns are handled when loading a mob with stored cooldowns from a savefile. In the case of PRESERVE NONE, the cooldown will be removed from the old cooldowns list when the mob is loaded from the savefile. PRESERVE_WORLDTIME will act as though no time passed between saving and loading. PRESERVE_REALTIME will cause the cooldown to account for the time between when the mob was saved and when the mob was loaded.




save_worldtime var (mob)

See also:
  save_realtime var (mob)
  cooldown_preserve var (mob)
  Read() (mob)

Default value:
  null

This value is provided by StdLib. It stores the world time that this mob was saved. This is used to adjust the cooldown timestamps when loading cooldown lists from a savefile.




save_realtime var (mob)

See also:
  save_worldtime var (mob)
  cooldown_preserve var (mob)
  Read() (mob)

Default value:
  null

This value is provided by StdLib. It stores the world.realtime that this mob was saved. This is used to adjust the cooldown timestamps when loading cooldown lists from a savefile.




getCooldown proc (mob)

See also:
  onCooldown proc (mob)
  getCooldowns proc (mob)

Format:
  getCooldown(string id)

Arguments:
  string id: the id of the cooldown you want to check

Returns:
  -1#INF if cooldown not present in cooldowns list
  world.time cooldown was last set to if present

Calling getCooldown() with a string as the argument will get the cooldown time that the cooldown of the matching string id was set to last. If there is no cooldown in the cooldowns list by that id, negative infinity is returned instead.




getCooldowns proc (mob)

See also:
  onCooldown proc (mob)
  getCooldown proc (mob)

Format:
  getCooldowns(string id,[string id...])

Arguments:
  string id: the id of the cooldown you want to check (you can supply multiple ids as args)

Returns:
  -1#INF if no cooldowns present in cooldowns list
  the highest cooldown time offset if any are present in the cooldowns list

getCooldowns() is similar to getCooldown(), but instead of taking a single id, it can take any number of ids, and will return the highest value of all ids present in the list. Any values not present will be interpreted as negative infinity.




onCooldown proc (mob)

See also:
  getCooldown proc (mob)
  getCooldowns proc (mob)

Format:
  onCooldown(string id,[string id...])

Arguments:
  string id: the id of the cooldown you want to check (you can supply multiple ids as args)

Returns:
  0 if no specified cooldowns are set to a future time
  1 if any of the specified cooldowns are set to a future time

onCooldown() takes a variable number of cooldown ids, much like getCooldowns(), but instead of returning the time, onCooldown() returns true if any of the cooldowns is greater than world.time, and false if none of them are.




setCooldown proc (mob)

See also:

  cooldowns var (mob)
  cooldown_preserve var (mob)

Format:
  onCooldown(string id,world timestamp [,offset=1,preserve=PRESERVE_REALTIME])

Arguments:
  string id: the id of the cooldown you want to change
  world timestamp: depending on the value of offset, this will either be the number of ticks from now that the cooldown will expire, or the actual world.time that the cooldown will expire at.
  offset (optional): if true, the timestamp will be considered an offset from the current time. if false, the timestamp will be considered a specified world time that the cooldown expires.
  preserve (optional): one of the preservation flags from StdLib. This determines how this cooldown is handled when loaded from a savefile.


setCooldown() is called to set a cooldown.

If cooldowns is not a list, both cooldowns and cooldown_preserve will be initialized. Then, the cooldown at id will be set to either a time offset from now, or the actual time specified based on whether the offset argument is true. Since offset is true by default, you have to specify an offset of 0 to specify a specific time. Otherwise, the time you set the cooldown to will be relative to the current world.time.

Last, cooldown_preserve[id] is set to the value in the preserve argument. See cooldown_preserve's documentation for possible values and details on what they mean. cooldown_preserve is set to PRESERVE_REALTIME because that is the most sensible behavior for the vast majority of combat systems.




Read proc (mob)

See also:

  cooldowns var (mob)
  cooldown_preserve var (mob)


DO NOT CALL THIS PROC MANUALLY, YOU DONKEY! It is part of the default savefile handling system of BYOND. You should never, ever call it manually.

Read() has been overridden by CooldownLib to recalculate the world time offsets stored in the cooldowns list according to the rules in cooldown_preserve. Cooldowns marked PRESERVE_NONE are removed from the cooldowns list along with any cooldowns that are already expired. This helps clean the cooldowns list, which will have a tendency to grow during runtime.

Cooldowns marked PRESERVE_WORLDTIME will simply be adjusted to the current world time. Provided that value is in the future, they will be readded to the new cooldowns list.

Cooldowns marked PRESERVE_REALTIME will also account for the real time since the savefile was written. Again, any values not in the future will be removed from the cooldowns list and the preservation list.