Cooldown

Overview

The cooldown module provides a simple key-value cache with optional TTL (time-to-live) expiration, powered by GetGameTimer(). It is exported as cooldown and can be used to gate actions, throttle events, or store short-lived state.

Functions

cooldown:set

Ocean.cooldown:set(key, value, expiration)

Stores a value under key. If expiration is provided, the entry will expire after that many milliseconds.

• key: string
• value: any
• expiration: number — milliseconds until expiry

cooldown:get

Ocean.cooldown:get(key)

Returns the cached value for key, or nil if it does not exist or has expired. Expired entries are automatically removed.

• key: string
• Returns: any | nil

cooldown:update

Ocean.cooldown:update(key, value)

Updates the value of an existing cache entry. Does nothing if the key is not already set.

• key: string
• value: any

cooldown:remove

Ocean.cooldown:remove(key)

Explicitly removes a key from the cache and clears its TTL.

• key: string

cooldown:getOrSet

Ocean.cooldown:getOrSet(key, resolver, ttl)

Returns the cached value for key if it exists. Otherwise, calls resolver(), stores the result with the given TTL, and returns it.

• key: string
• resolver: fun(): any
• ttl: number — milliseconds until expiry
• Returns: any

Example

local cache = Ocean.cooldown()
 
local playerId = 1
local key = ('action:%d'):format(playerId)
 
if cache:get(key) then
    print("Player is on cooldown")
    return
end
 
cache:set(key, true, 5000)
print("Action triggered")
 
local data = cache:getOrSet('someKey', function()
    return fetchExpensiveData()
end, 10000)