Cooldowns

Cooldown helpers store short-lived markers in Kicklet's runtime cooldown storage. Use them for script-specific limits that are separate from the command's configured global and user cooldowns.

Limits: default accounts can have up to 100 active runtime cooldown entries, and one cooldown can last up to 1 hour. Premium accounts can have up to 100000 active runtime cooldown entries, and one cooldown can last up to 30 days. The limit counts active key + scope entries per account. Use stable cooldown keys and put viewer-specific data in the scope argument.

When the active cooldown entry limit is reached, cooldowns.use() returns false. Use cooldowns.tryUse() when the command should show a specific message for limit failures.

Engine v2

Use cooldown with status

Starts a cooldown and returns a status object instead of throwing for expected limit errors.

Viewer cooldown with limit handlingAdvanced Script

const cooldown = cooldowns.tryUse("hourly-bonus", 3600, { viewer: sender.username });

if (cooldown.limitReached) {
  async.messages.send("Too many active cooldowns. Try again later.");
} else if (!cooldown.used) {
  async.messages.send(`Try again in ${time.duration(cooldown.remaining)}.`);
} else {
  points.add(sender.username, 10);
  async.messages.send("Hourly bonus claimed.");
}

API reference

cooldowns.tryUse

cooldowns.tryUse(key, seconds, scope?)

Input

key

string

Cooldown name.

seconds

number

Cooldown duration in seconds.

scopeoptional

stringobject

Optional scope, for example {viewer: sender.username}.

Output

object

Cooldown status.

ok

boolean

False when a limit prevented the operation.

used

boolean

True when the cooldown was started.

remaining

number

Remaining seconds when the cooldown is already active.

limitReached

boolean

True when the account cooldown-entry limit was reached.

error

string

Backend error message for limit failures.

Use cooldown

Starts a cooldown when it is currently free. Returns false while the cooldown is active or when the active cooldown limit was reached. Use cooldowns.tryUse() when you need details.

Viewer cooldownAdvanced Script

if (!cooldowns.use("hourly-bonus", 3600, { viewer: sender.username })) {
  const seconds = cooldowns.remaining("hourly-bonus", { viewer: sender.username });
  async.messages.send(`Try again in ${time.duration(seconds)}.`);
} else {
  points.add(sender.username, 10);
  async.messages.send("Hourly bonus claimed.");
}

API reference

cooldowns.use

cooldowns.use(key, seconds, scope?)

Input

key

string

Cooldown name.

seconds

number

Cooldown duration in seconds.

scopeoptional

stringobject

Optional scope, for example {viewer: sender.username}.

Output

boolean

True when the cooldown was started.

Check cooldown

Returns true when a cooldown is currently free.

API reference

cooldowns.check

cooldowns.check(key, scope?)

Input

key

string

Cooldown name.

scopeoptional

stringobject

Optional cooldown scope.

Output

boolean

True when no cooldown is active.

Cooldown remaining seconds

Returns the remaining cooldown time in seconds.

API reference

cooldowns.remaining

cooldowns.remaining(key, scope?)

Input

key

string

Cooldown name.

scopeoptional

stringobject

Optional cooldown scope.

Output

number

Remaining seconds, or 0 when free.

Reset cooldown

Clears a runtime cooldown so it can be used again immediately.

Reset viewer cooldownAdvanced Script

cooldowns.reset("hourly-bonus", { viewer: sender.username });
async.messages.send("Your hourly bonus cooldown was reset.");

API reference

cooldowns.reset

cooldowns.reset(key, scope?)

Input

key

string

Cooldown name.

scopeoptional

stringobject

Optional cooldown scope.

Output

boolean

True when the reset operation completed.

Async cooldown wrappers

Async wrapper for cooldowns.tryUse(key, seconds, scope).

API reference

async.cooldowns.tryUse

async.cooldowns.tryUse(key, seconds, scope?)

Input

key

string

Cooldown name.

seconds

number

Cooldown duration in seconds.

scopeoptional

stringobject

Optional scope, for example {viewer: sender.username}.

Output

object

Cooldown status.

ok

boolean

False when a limit prevented the operation.

used

boolean

True when the cooldown was started.

remaining

number

Remaining seconds when the cooldown is already active.

limitReached

boolean

True when the account cooldown-entry limit was reached.

error

string

Backend error message for limit failures.

Async wrapper for cooldowns.use(key, seconds, scope).

API reference

async.cooldowns.use

async.cooldowns.use(key, seconds, scope?)

Input

key

string

Cooldown name.

seconds

number

Cooldown duration in seconds.

scopeoptional

stringobject

Optional scope, for example {viewer: sender.username}.

Output

boolean

True when the cooldown was started.

Async wrapper for cooldowns.check(key, scope?).

API reference

async.cooldowns.check

async.cooldowns.check(key, scope?)

Input

key

string

Cooldown name.

scopeoptional

stringobject

Optional cooldown scope.

Output

boolean

True when no cooldown is active.

Async wrapper for cooldowns.remaining(key, scope).

API reference

async.cooldowns.remaining

async.cooldowns.remaining(key, scope?)

Input

key

string

Cooldown name.

scopeoptional

stringobject

Optional cooldown scope.

Output

number

Remaining seconds, or 0 when free.

Async wrapper for cooldowns.reset(key, scope?).

API reference

async.cooldowns.reset

async.cooldowns.reset(key, scope?)

Input

key

string

Cooldown name.

scopeoptional

stringobject

Optional cooldown scope.

Output

boolean

True when the reset operation completed.

Engine v1

Use command cooldown settings or temporary variables.