Cooldown by NoirSplash

Simple non-yielding Roblox module for managing time between actions.

Similar to a Maid, Cooldown intends to streamline development by keeping your debounce and cooldown management in one place.

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Cooldown = require(ReplicatedStorage.Cooldown()

[!IMPORTANT] Cooldown is not a timer module. There are no methods or signals provided to listen for when a cooldown expires and their status is evaluated only when called.

Roblox Model | Latest Release

[image: ko-fi]

Properties

GARBAGE_COLLECT_INTERVAL : number

private, constant

Describes how long (in seconds) the garbage collector should wait between cleanings. Expired cooldowns are automatically cleaned up when they are queried, garbage collection only affects cooldowns that expire and are never called on again. Does nothing if Cooldown.doCleaning is set to false. default 120

Cooldown.doCleaning : boolean

public, variable

Determines if expired cooldowns are automatically cleaned up by the garbage collector. If set to false, the cache must be cleaned manually by iterating through and calling Cooldown.get() on each entry to remove expired cooldowns or by other means to avoid memory leaks. The loop cannot be restarted once disabled. default true

Methods

Cooldown.set(string, number, boolean?) -> ()

This function sets (or resets) a cooldown based on the given identifier and duration.

Parameters

Cooldown.get(string) -> (number?)

Returns the remaining duration of the cooldown matching the identifier given or nil if it is expired/does not exist.

Parameters

Code Examples

Generic Debounce Pattern

The following code block shows off the intended usage for simple cooldowns (or debounce.) Because Cooldown.get() returns nil if a cooldown is expired, the conditional statement will only evaluate true if the duration of the cooldown has elapsed or does not exist.

if Cooldown.get("Debounce") then
    return
end
Cooldown.set("Debounce", DEBOUNCE_LENGTH)

Refreshable Cooldown/Combo Timer

Instead of blocking a function this code will reset the timer on a cooldown if it is active, else it will reset a variable. Keep in mind the value will not reset until called again, even if the timer expires.

local combo = 0
if Cooldown.get("ComboTimer") then
    combo += 1
    Cooldown.set("ComboTimer", COMBO_DURATION) -- Reset the timer so you can continue the combo!
else
    combo = 0
    Cooldown.set("ComboTimer", COMBO_DURATION) -- Start the combo chain!
end

Simplified

local combo = 0
local function combo()
    combo = if Cooldown.get("ComboTimer") then combo + 1 else 0
    Cooldown.set("ComboTimer", COMBO_DURATION)
end

Jump Reducer

This script combines the above two techniques into a system that reduces the player's jump height the more consecutive jumps they make, without restricting jumping entirely.

local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local UserInputService = game:GetService("UserInputService")

local Cooldown = require(ReplicatedStorage.lib.Cooldown)

local DEFAULT_JUMP_HEIGHT = 7.2
local JUMP_COOLDOWN = 0.7
local REQUEST_DEBOUNCE = 75 -- milliseconds

local jumpCount = 0

local function setCooldownTimer()
    if Cooldown.get("LocalJump") then
        Cooldown.set("LocalJump", JUMP_COOLDOWN)
    else
        jumpCount = 0
        Cooldown.set("LocalJump", JUMP_COOLDOWN)
    end
end

UserInputService.JumpRequest:Connect(function()
    if Cooldown.get("JumpRequestDebounce") then
        return
    end
    Cooldown.set("JumpRequestDebounce", REQUEST_DEBOUNCE, true)
    setCooldownTimer()
    jumpCount += 1

    local character = Players.LocalPlayer.Character
    local humanoid = character and character:FindFirstChildOfClass("Humanoid")
    if not character or not humanoid then
        return
    end

    local jumpHeight = DEFAULT_JUMP_HEIGHT * math.clamp(1 - jumpCount * 0.1, 0, 1)
    humanoid.JumpHeight = jumpHeight
end)