Platform.spells.GetSpellCooldown

Call as

addon.Platform:GetSpellCooldown(spell)

Available directly through addon; no dependency is needed.

What it does

Read and normalize a spell cooldown across supported clients. The returned record contains startTime, duration, isEnabled and modRate. The timestamps and duration already describe expiration in GetTime() seconds; do not divide them by modRate. When the client hides the times (Retail and Forever in combat) the record is nil with reason restricted-value, followed by the never-secret isEnabled, isActive and isOnGCD flags when they can be read.

Arguments

Name	Type	What it does
`self`	`RMPlatform`	Rotation Master platform adapter. A dot reference requires addon.Platform as the first argument; a colon call supplies it implicitly.
`spell`	`number \| string`	Spell ID or client-recognized spell name whose cooldown should be read.

Returns

1	`table \| nil`	Readable cooldown record, or nil when unavailable.
2	`string \| nil`	Availability or validation reason when the record is nil.
3	`boolean \| nil`	With restricted-value only: isEnabled, false while the cooldown is on hold.
4	`boolean \| nil`	With restricted-value only: isActive, true while a cooldown (its own or the global one) is running.
5	`boolean \| nil`	With restricted-value only: isOnGCD, true when the running cooldown is the global cooldown; may be nil.

Editions

Built In helpers are registered on every edition. What differs is the game API they read; where one is missing the helper falls back or returns nil with a reason.

Not available on that edition (the reason is in the tooltip)
Only while Blizzard's deprecation fallbacks are on

Game API
`C_Spell.GetSpellCooldown`
`GetSpellCooldown`

Secret values (Retail and Forever)

On Retail and Forever the game hands addons secret values. This helper checks what it reads (addon.Platform:CanReadValue) and returns nil with a reason such as restricted-value instead of a secret it cannot compare. Treat nil as unavailable, not as false.

Example

local record, reason, isEnabled, isActive = addon.Platform:GetSpellCooldown(value.spell)
if record then return record.isEnabled and record.duration == 0 end
-- Times are secret in combat on Retail and Forever; fall back to the flags.
if reason == "restricted-value" and isActive ~= nil then return isEnabled and not isActive end
return nil

Dependencies

cooldownFields (builtin:Platform/spells.lua:cooldownFields)
cooldownFlags → Platform.spells.cooldownFlags
identifier → Platform.spells.identifier
own → Platform.spells.own

Source

Platform/spells.lua, line 393. Read only in game; Duplicate makes an editable copy.

Platform.spells.GetSpellCooldown(self, spell)

    local valid, reason = identifier(spell)
    if not valid then return nil, reason end
    local ok, record, built
    if C_Spell and type(C_Spell.GetSpellCooldown) == "function" then
        ok, record = pcall(C_Spell.GetSpellCooldown, spell)
    elseif type(GetSpellCooldown) == "function" then
        local start, duration, enabled, rate
        ok, start, duration, enabled, rate = pcall(GetSpellCooldown, spell)
        if not ok then return nil, "api-error" end
        if not self:CanReadValue(start) or not self:CanReadValue(duration) or not self:CanReadValue(enabled)
            or not self:CanReadValue(rate) then return nil, "restricted-value" end
        if start ~= nil then
            if enabled ~= 0 and enabled ~= 1 then return nil, "invalid-api-result" end
            record = {startTime=start, duration=duration, isEnabled=enabled == 1, modRate=rate or 1};built = true
        end
    else return nil, "missing-api" end
    if not ok then return nil, "api-error" end
    if not self:CanReadValue(record) then return nil, "restricted-value" end
    if record == nil then return nil, "spell-data-unavailable" end
    local cooldown, why = own(record, cooldownFields, built)
    if not cooldown then
        if why == "restricted-value" and not built then return nil, why, cooldownFlags(self, record) end
        return nil, why
    end
    if cooldown.startTime == nil or cooldown.duration == nil or cooldown.isEnabled == nil
        or cooldown.startTime < 0 or cooldown.duration < 0 or (cooldown.modRate and cooldown.modRate <= 0) then
        return nil, "invalid-api-result"
    end
    cooldown.modRate = cooldown.modRate or 1
    return cooldown

Back to Function reference