Skip to main content

AdjustableTimer

The AdjustableTimer class provides a flexible timer system that allows for pausing, resuming, adjusting time scales, and tracking elapsed time. It is designed to be serialized and unserialized for replication and storage across systems. Use in conjunction with the AdjustableTimerManager for easy replication of timers from server to clients.

Example Usage

local timer = AdjustableTimer.new()
timer:Resume() -- Start the timer
task.wait(5) -- Simulate some elapsed time
print(timer:GetElapsedTime())

Functions​

new​

</>
AdjustableTimer.new(config: {
TimeScale: number?,
StartTime: number?,
}?) → AdjustableTimer

Creates a new AdjustableTimer instance. Takes an optional configuration table.

  • TimeScale: The initial time scale for the timer. Defaults to 1.
  • StartTime: The initial start time of the timer. Defaults to the current server time (via workspace:GetServerTimeNow()).
local timer = AdjustableTimer.new()
timer:Resume() -- Start the timer
Starting the Timer

Timers are initialized in a paused state by default. You need to call :Resume() to start the timer.

Unserialize​

</>
AdjustableTimer.Unserialize(data: SerializedAdjustableTimer) → AdjustableTimer

Unserializes a table into an AdjustableTimer instance.

local timer = AdjustableTimer.Unserialize(serializedData)

Serialize​

</>
AdjustableTimer:Serialize() → SerializedAdjustableTimer

Serializes the timer into a saveable/network-safe table.

local serializedData = timer:Serialize()

GetElapsedTime​

</>
AdjustableTimer:GetElapsedTime() → number--

The elapsed time in seconds.

Gets the elapsed time that the timer has been running unpaused.

print(timer:GetElapsedTime())

Pause​

</>
AdjustableTimer:Pause() → AdjustableTimer

Pauses the timer. Returns the timer for chaining.

timer:Pause()

Resume​

</>
AdjustableTimer:Resume() → AdjustableTimer

Resumes the timer. Returns the timer for chaining.

timer:Resume()

IsPaused​

</>
AdjustableTimer:IsPaused() → boolean

Returns whether or not the timer is paused.

print(timer:IsPaused())

SetTimeScale​

</>
AdjustableTimer:SetTimeScale(
newRate: number,--

The new rate at with time will progress.

_newRateChangeTime: number?
) → ()

Changes how fast the timer progresses every unpaused second. 2 means the timer will progress twice as fast, 0.5 means it will progress half as fast. 

timer:SetTimeScale(2)

GetTimeScale​

</>
AdjustableTimer:GetTimeScale() → number--

The current progress rate.

Gets the current time scale of the timer. Represents how fast the timer progresses every unpaused second. 2 means the timer will progress twice as fast, 0.5 means it will progress half as fast.

AddElapsedTime​

</>
AdjustableTimer:AddElapsedTime(
seconds: number,--

The number of seconds to add.

useTimeScale: boolean?--

Whether to apply the current time scale to the given seconds (default is false).

) → ()

Adds progress to the timer in raw seconds.

local time = AdjustableTimer.new():Resume()
print(timer:GetElapsedTime()) -- 0
timer:AddElapsedTime(10)
print(timer:GetElapsedTime()) -- 10
timer:SetTimeScale(2)
timer:AddElapsedTime(5, true)
print(timer:GetElapsedTime()) -- 20

SetElapsedTime​

</>
AdjustableTimer:SetElapsedTime(
seconds: number--

The elapsed time to set.

) → ()

Sets the elapsed time of the timer in raw seconds.

timer:SetElapsedTime(30)

SetStartTime​

</>
AdjustableTimer:SetStartTime(timestamp: number) → ()

Sets the time at which the timer started. This will affect the elapsed time calculation. The timestamp should be relative to workspace:GetServerTimeNow(). Does not account for time scale or paused state. 

timer:SetStartTime(workspace:GetServerTimeNow() - 60) -- Set start time to 60 seconds ago
Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Creates a new AdjustableTimer instance. Takes an optional configuration table.\n\n- `TimeScale`: The initial time scale for the timer. *Defaults to 1*.\n- `StartTime`: The initial start time of the timer. *Defaults to the current server time (via workspace:GetServerTimeNow())*.\n\n```lua\nlocal timer = AdjustableTimer.new()\ntimer:Resume() -- Start the timer\n```\n:::important Starting the Timer\nTimers are initialized in a paused state by default. You need to call `:Resume()` to start the timer.\n:::",
            "params": [
                {
                    "name": "config",
                    "desc": "",
                    "lua_type": "{\r\n\tTimeScale: number?,\r\n\tStartTime: number?,\r\n}?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "AdjustableTimer\r\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 59,
                "path": "lib/adjustabletimer/src/init.luau"
            }
        },
        {
            "name": "Serialize",
            "desc": "Serializes the timer into a saveable/network-safe table.\n```lua\nlocal serializedData = timer:Serialize()\n```",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "SerializedAdjustableTimer\r\n"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 85,
                "path": "lib/adjustabletimer/src/init.luau"
            }
        },
        {
            "name": "Unserialize",
            "desc": "Unserializes a table into an AdjustableTimer instance.\n```lua\nlocal timer = AdjustableTimer.Unserialize(serializedData)\n```",
            "params": [
                {
                    "name": "data",
                    "desc": "",
                    "lua_type": "SerializedAdjustableTimer"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "AdjustableTimer\r\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 101,
                "path": "lib/adjustabletimer/src/init.luau"
            }
        },
        {
            "name": "GetElapsedTime",
            "desc": "Gets the elapsed time that the timer has been running unpaused.\n\n```lua\nprint(timer:GetElapsedTime())\n```",
            "params": [],
            "returns": [
                {
                    "desc": "The elapsed time in seconds.",
                    "lua_type": "number"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 123,
                "path": "lib/adjustabletimer/src/init.luau"
            }
        },
        {
            "name": "Pause",
            "desc": "Pauses the timer. Returns the timer for chaining.\n\n```lua\ntimer:Pause()\n```",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "AdjustableTimer"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 139,
                "path": "lib/adjustabletimer/src/init.luau"
            }
        },
        {
            "name": "Resume",
            "desc": "Resumes the timer. Returns the timer for chaining.\n\n```lua\ntimer:Resume()\n```",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "AdjustableTimer"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 158,
                "path": "lib/adjustabletimer/src/init.luau"
            }
        },
        {
            "name": "IsPaused",
            "desc": "Returns whether or not the timer is paused.\n```lua\nprint(timer:IsPaused())\n```",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean\r\n"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 174,
                "path": "lib/adjustabletimer/src/init.luau"
            }
        },
        {
            "name": "SetTimeScale",
            "desc": "Changes how fast the timer progresses every unpaused second.\n`2` means the timer will progress twice as fast, `0.5` means it will progress half as fast.\n```lua\ntimer:SetTimeScale(2)\n```",
            "params": [
                {
                    "name": "newRate",
                    "desc": "The new rate at with time will progress.",
                    "lua_type": "number"
                },
                {
                    "name": "_newRateChangeTime",
                    "desc": "",
                    "lua_type": "number?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 186,
                "path": "lib/adjustabletimer/src/init.luau"
            }
        },
        {
            "name": "GetTimeScale",
            "desc": "Gets the current time scale of the timer. Represents how fast the timer progresses every unpaused second.\n`2` means the timer will progress twice as fast, `0.5` means it will progress half as fast.",
            "params": [],
            "returns": [
                {
                    "desc": "The current progress rate.",
                    "lua_type": "number"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 208,
                "path": "lib/adjustabletimer/src/init.luau"
            }
        },
        {
            "name": "AddElapsedTime",
            "desc": "Adds progress to the timer in raw seconds.\n\n```lua\nlocal time = AdjustableTimer.new():Resume()\nprint(timer:GetElapsedTime()) -- 0\ntimer:AddElapsedTime(10)\nprint(timer:GetElapsedTime()) -- 10\ntimer:SetTimeScale(2)\ntimer:AddElapsedTime(5, true)\nprint(timer:GetElapsedTime()) -- 20\n```",
            "params": [
                {
                    "name": "seconds",
                    "desc": "The number of seconds to add.",
                    "lua_type": "number"
                },
                {
                    "name": "useTimeScale",
                    "desc": "Whether to apply the current time scale to the given seconds (default is false).",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 227,
                "path": "lib/adjustabletimer/src/init.luau"
            }
        },
        {
            "name": "SetElapsedTime",
            "desc": "Sets the elapsed time of the timer in raw seconds.\n```lua\ntimer:SetElapsedTime(30)\n```",
            "params": [
                {
                    "name": "seconds",
                    "desc": "The elapsed time to set.",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 244,
                "path": "lib/adjustabletimer/src/init.luau"
            }
        },
        {
            "name": "SetStartTime",
            "desc": "Sets the time at which the timer started. This will affect the elapsed time calculation.\nThe timestamp should be relative to `workspace:GetServerTimeNow()`.\nDoes not account for time scale or paused state.\n```lua\ntimer:SetStartTime(workspace:GetServerTimeNow() - 60) -- Set start time to 60 seconds ago\n```",
            "params": [
                {
                    "name": "timestamp",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 259,
                "path": "lib/adjustabletimer/src/init.luau"
            }
        },
        {
            "name": "OnChanged",
            "desc": "Registers a callback to be invoked when the timer changes.\n```lua\nlocal disconnect = timer:OnChanged(function(actionType, ...)\n\tprint(\"Timer changed:\", actionType, ...)\nend)\n```",
            "params": [
                {
                    "name": "callback",
                    "desc": "The callback function to register.",
                    "lua_type": "function"
                }
            ],
            "returns": [
                {
                    "desc": "A function to disconnect the callback.",
                    "lua_type": "function"
                }
            ],
            "function_type": "method",
            "private": true,
            "source": {
                "line": 278,
                "path": "lib/adjustabletimer/src/init.luau"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "AdjustableTimer",
    "desc": "The AdjustableTimer class provides a flexible timer system that allows for pausing, resuming, adjusting time scales, and tracking elapsed time. \nIt is designed to be serialized and unserialized for replication and storage across systems. Use in conjunction with the `AdjustableTimerManager` for\neasy replication of timers from server to clients.\n\n### Example Usage\n```lua\nlocal timer = AdjustableTimer.new()\ntimer:Resume() -- Start the timer\ntask.wait(5) -- Simulate some elapsed time\nprint(timer:GetElapsedTime())\n```",
    "source": {
        "line": 16,
        "path": "lib/adjustabletimer/src/init.luau"
    }
}