Skip to main content

Timer

Observable

Inherits Observable

Observable which counts down from a max value in realtime whenever played via Timer:Play.

Includes utility methods for mapping this "remaining time" value into more complex animationed sequences.

Constructor

Dex.Timer

Dex.Timer({
    duration: number,
    isPlaying: CanBeObservable<boolean>?,
    playOnChange: Observable<any>?,
}) -> Timer

Creates a new Timer Observable, the value of which decreases in realtime after Timer:Play is called.

Props:

duration is a required prop that specifies the initial time of the timer.

isPlaying specifies that timer should play and stop depending on an observable boolean value. If set to true, the timer will immediately start playing.

playOnChange specifies that the timer should restart whenever an input observable changes.

Timers can safely be garbage collected while dereferenced, unsubscribed, and unused by a VirtualInstance.

INFO

Timers must currently be Subscribed or Mounted to exhibit expected behavior. This is a requirement for all realtime-simulated observables, which enables safe garbage collection when writing Dex components.

Usage Example:

local timer = Dex.Timer({
    duration = 10,
    isPlaying = true,
})
local frame = Dex.New("Frame")({
    -- Opaque for 5 seconds, then fades to Transparent over 5 seconds:
    BackgroundTransparency = timer:Alpha(5, 0),
})

Types​

TimerProps​

</>
interface TimerProps {
duration: number
isPlaying: CanBeObservable<boolean>?,
playOnChange: Observable<any>?,
}

Type that specifies the props for constructing a Timer observable (via Dex.Timer)

duration is a required prop that specifies the initial time of the timer.

isPlaying specifies that timer should play and stop depending on an observable boolean value. If set to true, the timer will immediately start playing.

playOnChange specifies that the timer should restart whenever an input observable changes.

Functions​

Play​

</>
Timer:Play() → ()

Starts the Timer Observable. The observable will update with new values every heartbeat in real-time until it is stopped.

Stop​

</>
Timer:Stop() → ()

Stops the Timer Observable, reseting the remaining time.

Pause​

</>
Timer:Pause() → ()

Pauses the Timer Observable at its current remaining time position.

Pause​

</>
Timer:Pause() → ()

Sets the current remaining time of the Timer.

SetDuration​

</>
Timer:SetDuration(duration: number) → ()

Sets the duration of the Timer.

Lerp​

</>
Timer:Lerp() → Observable<T>

Creates an observable that outputs an interpolated value between the start value and end value based on the current remaining time.

Alpha​

</>
Timer:Alpha(
startTime: number,
endTime: number
) → Alpha

Derives an observble number that maps the remaining time from from 0 at the provided start time, and 1 at the provided end time.

Show raw api
{
    "functions": [
        {
            "name": "Play",
            "desc": "Starts the Timer Observable. The observable will update with new\nvalues every heartbeat in real-time until it is stopped.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 21,
                "path": "src/Observables/BaseTimer.luau"
            }
        },
        {
            "name": "Stop",
            "desc": "Stops the Timer Observable, reseting the remaining time.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 40,
                "path": "src/Observables/BaseTimer.luau"
            }
        },
        {
            "name": "Pause",
            "desc": "Pauses the Timer Observable at its current remaining time position.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 58,
                "path": "src/Observables/BaseTimer.luau"
            }
        },
        {
            "name": "Pause",
            "desc": "Sets the current remaining time of the Timer.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 86,
                "path": "src/Observables/BaseTimer.luau"
            }
        },
        {
            "name": "SetDuration",
            "desc": "Sets the duration of the Timer.",
            "params": [
                {
                    "name": "duration",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 103,
                "path": "src/Observables/Timer.luau"
            }
        },
        {
            "name": "Lerp",
            "desc": "Creates an observable that outputs an interpolated value between\nthe start value and end value based on the current remaining time.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Observable<T>"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 115,
                "path": "src/Observables/Timer.luau"
            }
        },
        {
            "name": "Alpha",
            "desc": "Derives an observble number that maps the remaining time from from 0 at the\nprovided start time, and 1 at the provided end time.",
            "params": [
                {
                    "name": "startTime",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "endTime",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Alpha"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 140,
                "path": "src/Observables/Timer.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "TimerProps",
            "desc": "Type that specifies the props for constructing a [Timer] observable (via\n[Dex.Timer])\n\n`duration` is a required prop that specifies the initial time of the timer.\n\n`isPlaying` specifies that timer should play and stop depending on an\nobservable boolean value. If set to `true`, the timer will immediately start\nplaying.\n\n`playOnChange` specifies that the timer should restart whenever an input\nobservable changes.",
            "fields": [
                {
                    "name": "duration",
                    "lua_type": "number",
                    "desc": ""
                },
                {
                    "name": "isPlaying",
                    "lua_type": "CanBeObservable<boolean>?,",
                    "desc": ""
                },
                {
                    "name": "playOnChange",
                    "lua_type": "Observable<any>?,",
                    "desc": ""
                }
            ],
            "source": {
                "line": 181,
                "path": "src/Observables/Timer.luau"
            }
        }
    ],
    "name": "Timer",
    "desc": "#### Inherits [Observable]\n\nObservable which counts down from a max value in realtime whenever played\nvia [Timer:Play].\n\nIncludes utility methods for mapping this \"remaining time\" value into more\ncomplex animationed sequences.\n\n## Constructor\n\n---\n\n### Dex.Timer\n```lua\nDex.Timer({\n    duration: number,\n    isPlaying: CanBeObservable<boolean>?,\n    playOnChange: Observable<any>?,\n}) -> Timer\n```\n\nCreates a new [Timer] Observable, the value of which decreases in realtime\nafter [Timer:Play] is called.\n\n#### Props:\n\n`duration` is a required prop that specifies the initial time of the timer.\n\n`isPlaying` specifies that timer should play and stop depending on an\nobservable boolean value. If set to `true`, the timer will immediately start\nplaying.\n\n`playOnChange` specifies that the timer should restart whenever an input\nobservable changes.\n\n----\n\nTimers can safely be garbage collected while dereferenced, unsubscribed,\nand unused by a VirtualInstance.\n\n:::info\nTimers must currently be ***Subscribed*** or ***Mounted*** to exhibit\nexpected behavior. This is a requirement for all realtime-simulated\nobservables, which enables safe garbage collection when writing Dex\ncomponents.\n:::\n\nUsage Example:\n```lua\nlocal timer = Dex.Timer({\n    duration = 10,\n    isPlaying = true,\n})\nlocal frame = Dex.New(\"Frame\")({\n    -- Opaque for 5 seconds, then fades to Transparent over 5 seconds:\n    BackgroundTransparency = timer:Alpha(5, 0),\n})\n```",
    "tags": [
        "Observable"
    ],
    "source": {
        "line": 77,
        "path": "src/Observables/Timer.luau"
    }
}