cooldown helper functions

# Reusable cooldown helpers — call from any command to add a cooldown
# with formatted remaining-time messages. No more hand-rolled
# 'difference between {cd::%player%} and now' boilerplate.
#
# Usage:
#   command /heal:
#       trigger:
#           if onCooldown(player, "heal") is true:
#               send "&cWait %cooldownLeft(player, \"heal\")%" to player
#               stop
#           setCooldown(player, "heal", 30)
#           heal player

function setCooldown(p: player, key: string, seconds: number):
    set {cooldowns::%uuid of {_p}%::%{_key}%} to (now + {_seconds} seconds)

function onCooldown(p: player, key: string) :: boolean:
    if {cooldowns::%uuid of {_p}%::%{_key}%} is not set:
        return false
    return {cooldowns::%uuid of {_p}%::%{_key}%} > now

function cooldownLeft(p: player, key: string) :: string:
    if {cooldowns::%uuid of {_p}%::%{_key}%} is not set:
        return "ready"
    if {cooldowns::%uuid of {_p}%::%{_key}%} <= now:
        return "ready"
    set {_diff} to difference between now and {cooldowns::%uuid of {_p}%::%{_key}%}
    return "%{_diff}%"

function clearCooldown(p: player, key: string):
    delete {cooldowns::%uuid of {_p}%::%{_key}%}

# Optional: periodically prune expired entries so the variable file stays small
every 5 minutes:
    loop {cooldowns::*}:
        loop {cooldowns::%loop-index-1%::*}:
            if {cooldowns::%loop-index-1%::%loop-index-2%} <= now:
                delete {cooldowns::%loop-index-1%::%loop-index-2%}