Skip to content

API

The 'EventTracker' tool will allow developers to easily integrate "live" events into Roblox experiences.

EventTracker is based around an OOP paradigm, instantiating events and then using that generated object to interact with the Live event. Here are a few features that this module offers:

  • Event Objects
    • Event Objects allow developers to easily generate events that'll occur at a specific point in the future.
  • UTC Time-Based
    • UTC (Coordinated Universal Time) is the primary time standard that is used to regulate things like clocks, we've inherited this behaviour into the Event Tracker as well!

EventTracker

Types

TimeZone

type TimeZone = {
    CentralAfricaTime: number,
    EastAfricaTime: number,
    WestAfricaTime: number,
    SouthAfricaStandardTime: number,
    MoroccoStandardTime: number,
    IndiaStandardTime: number,
    ChinaStandardTime: number,
    JapanStandardTime: number,
    KoreaStandardTime: number,
    CentralEuropeanTime: number,
    EasternEuropeanTime: number,
    BritishSummerTime: number,
    GreenwichMeanTime: number,
    EasternStandardTime: number,
    CentralStandardTime: number,
    MountainStandardTime: number,
    PacificStandardTime: number,
    AlaskaStandardTime: number,
    HawaiiAleutianStandardTime: number,
    AustralianEasternStandardTime: number,
    AustralianCentralStandardTime: number,
    AustralianWesternStandardTime: number,
    LordHoweStandardTime: number
}

Properties

Event

EventTracker.Event: Event

EventActivated

EventTracker.EventActivated: Signal

EventDeactivated

EventTracker.EventDeactivated: Signal

Timer

EventTracker.Timer: Timer

TimersUpdated

EventTracker.TimersUpdated: Signal

TimeZone

EventTracker.TimeZone: TimeZone

UTC

EventTracker.UTC: UTC

Functions

:GetActiveEvents

EventTracker:GetActiveEvents(): { Event }

This function will retrieve an array of active events happening at the moment

:GetEvent

EventTracker:GetEvent(eventLabel: string): Event

This function will retrieve an event from it's label.

:GetNextEvent

EventTracker:GetNextEvent(): Event?

This function will retrieve the next tracked event

:GetUpcomingEvents

EventTracker:GetUpcomingEvents(): { Event }

This function will retrieve an sorted array of upcoming events, the array is sorted so closest events are first.

:SetTimerFrequency

EventTracker:SetTimerFrequency(value: number): Event
Example Usage 
EventTracker:SetTimerFrequency(0.5)

local t = tick()
EventTracker.TimersUpdated:Wait()
print(tick() - t) -- > around 0.5

:Start

EventTracker:Start(): ()

This function will start the background process for updating all event timers. It is important this function is called during runtime.

Warning

This function is required to be called during your games init process, if this function is not called then events will not be started/ended

Event

The 'Event' class is the primary class developers will interact with, it's job is to manipulate the logic for a live event.

Properties

Activated

Event.Activated: Signal

Deactivated

Event.Deactivated: Signal

EndTimer

Event.EndTimer: Timer?

StartTimer

Event.StartTimer: Timer?

UTCEndTime

Event.UTCEndTime: UTC?

UTCStartTime

Event.UTCStartTime: UTC?

Label

Event.Label: string

Functions

.new

Event.new(name: string, data: { UTCStartTime: UTC?, UTCEndTime: UTC? }): Event

This function constructs a new 'Event' class

.is

Event.is(object?: Event?): boolean

This function compares the first parameter to the 'Event' class

:Destroy

Event:Destroy(): ()

This function will cleanup any connections the Event has made in it's lifetime.

:DisableTimerUpdates

Event:DisableTimerUpdates(): ()

This function will disable the logic for updating timers, developers may want to do this in the case they want to manually start or stop an event without timers taking precedence over event state.

:EnableTimerUpdates

Event:EnableTimerUpdates(): ()

This function will enable the logic for updating timers.

:GetState

Event:GetState(): boolean

This function will return the state of an event, if this state is 'true' then the event is active.

:GetTimeUntilEnd

Event:GetTimeUntilEnd(): number

This function will return the amount of seconds before the end of an event.

:GetTimeUntilStart

Event:GetTimeUntilStart(): number

This function will return the amount of seconds before the start of an event.

:IsTracked

Event:IsTracked(): boolean

This function will return a boolean depending if this event has time constraints.

:OnActivated

Event:OnActivated(): ()

This lifecycle function is called when the event is first activated.

Warning

Aim to perform synchronous operations inside of lifecycle methods

:OnDeactivated

Event:OnDeactivated(): ()

This lifecycle function is called when the event has expired.

Warning

Aim to perform synchronous operations inside of lifecycle methods

:SetState

Event:SetState(state: boolean): ()

This function will set the state of an event, this is typically handled internally but is exposed for developer debugging.

:ToString

Event:ToString(): string

This function generates a string that shows the following; Event Type, Event Label.

:UpdateTimers

Event:UpdateTimers(): ()

This function will update the Timers generated by this event.

Timer

The 'Timer' class is an internal class that helps to track the time left before the start or end of an event occurs.

Functions

.new

Timer.new(expirationUTC: UTC): Timer

This function constructs a new 'Timer' class.

.is

Timer.is(object: Timer?): boolean

This function compares the first parameter to the 'Timer' class.

:GetDeltaTime

Timer:GetDeltaTime(): number

This function will return the time required to hit the UTC target.

:IsActive

Timer:IsActive(): boolean

This function will return the current state of the Timer, weather or ot it is active.

:IsExpired

Timer:IsExpired(): boolean

This function will let developers know if we've passed the UTC target, then causing the Timer to expire.

:ToString

Timer:ToString(): string

This function generates a string that shows the following; Timer Type, UTC

UTC

Functions

.from

UTC.from(epoch: number): UTC

This function constructs a new 'UTC' class from an unix timestamp.

.is

UTC.is(object?: UTC?): boolean

This function compares the first parameter to the 'Event' class.

.new

UTC.new(dateTable: { Year: number, Month: number, Day: number, Hour: number, Minute: number, Second: number }): UTC

This function constructs a new 'UTC' class.

.now

UTC.now(): UTC

This function returns the current UTC time.

:GetEpochTime

UTC:GetEpochTime(): number

This function will return the epoch time with an UTC offset applied.

:SetUTCOffset

UTC:SetUTCOffset(offset: number): UTC

This function will apply a UTC offset to the epoch.

:ToString

UTC:ToString(): string

This function generates a string that shows the following; UTC Type, Epoch