DateTime
An immutable representation of a date and time, which may be either local time or UTC.
Constructors
Constructor Name | Return Type | Description | Tags |
---|---|---|---|
DateTime.New(table parameters) | DateTime | Constructs a new DateTime instance, defaulting to midnight on January 1, 1970, UTC. The parameters table may contain the following values to specify the date and time:year (integer) : Specifies the year. month (integer) : Specifies the month, from 1 to 12. day (integer) : Specifies the day of the month, from 1 to the last day of the specified month. hour (integer) : Specifies the hour of the day, from 0 to 23. minute (integer) : Specifies the minute, from 0 to 59. second (integer) : Specifies the second, from 0 to 59. millisecond (integer) : Specifies the millisecond, from 0 to 999. isLocal (boolean) : If true, the new DateTime will be in local time. Defaults to false for UTC. Values outside of the supported range for each field will be clamped, and a warning will be logged. | None |
Properties
Property Name | Return Type | Description | Tags |
---|---|---|---|
year | integer | The year component of this DateTime. | Read-Only |
month | integer | The month component of this DateTime, from 1 to 12. | Read-Only |
day | integer | The day component of this DateTime, from 1 to 31. | Read-Only |
hour | integer | The hour component of this DateTime, from 0 to 23. | Read-Only |
minute | integer | The minute component of this DateTime, from 0 to 59. | Read-Only |
second | integer | The second component of this DateTime, from 0 to 59. | Read-Only |
millisecond | integer | The millisecond component of this DateTime, from 0 to 999. | Read-Only |
isLocal | boolean | True if this DateTime is in the local time zone, false if it's UTC. | Read-Only |
secondsSinceEpoch | integer | Returns the number of seconds since midnight, January 1, 1970, UTC. Note that this ignores the millisecond component of this DateTime. | Read-Only |
millisecondsSinceEpoch | integer | Returns the number of milliseconds since midnight, January 1, 1970, UTC. | Read-Only |
Functions
Function Name | Return Type | Description | Tags |
---|---|---|---|
ToLocalTime() | DateTime | Returns a copy of this DateTime adjusted to local time. If this DateTime is already in local time, simply returns a copy of this DateTime. | None |
ToUtcTime() | DateTime | Returns a copy of this DateTime adjusted to UTC. If this DateTime is already in UTC, simply returns a copy of this DateTime. | None |
ToIsoString() | string | Returns this date and time, adjusted to UTC, formatted as an ISO 8601 string (YYYY-mm-ddTHH:MM:SS.sssZ ) | None |
Class Functions
Class Function Name | Return Type | Description | Tags |
---|---|---|---|
DateTime.CurrentTime([table optionalParameters]) | DateTime | Returns the current date and time in UTC. The optionalParameters table may contain the following values to change the date and time returned: isLocal (boolean) : If true, the current local time will be returned instead of UTC. | None |
DateTime.FromSecondsSinceEpoch(integer secondsSinceEpoch) | DateTime | Returns the date and time that is secondsSinceEpoch seconds since midnight, January 1, 1970, UTC. | None |
DateTime.FromMillisecondsSinceEpoch(integer millisecondsSinceEpoch) | DateTime | Returns the date and time that is millisecondsSinceEpoch milliseconds since midnight, January 1, 1970, UTC. | None |
DateTime.FromIsoString(string) | DateTime | Parses the given string as an ISO 8601 formatted date (YYYY-MM-DD ) or date and time (YYYY-mm-ddTHH:MM:SS(.sss)(Z/+hh:mm/+hhmm/-hh:mm/-hhmm) ). Returns the parsed UTC DateTime, or nil if the string was an invalid format. | None |
Examples
Example using:
CurrentTime
ToIsoString
In this example, we take the local time and print it to the Event Log in two different ways. By using tostring()
we are able to see the local interpretation of the DateTime
. By using ToIsoString()
we see the time converted to UTC and formatted according to the ISO 8601 standard.
local now = DateTime.CurrentTime({isLocal = true})
print(tostring(now))
print(now:ToIsoString())
Example using:
CurrentTime
ToIsoString
FromIsoString
secondsSinceEpoch
In some games it may be important to know if a player is new and, if they are not, how much time has passed since they were last playing. In this example, we catch the moment players join and leave. Using storage, we save the timestamp when they leave and use that information the next time they join. By comparing the timestamps of leaving and joining we know how many seconds elapsed.
local function OnPlayerLeft(player)
local data = Storage.GetPlayerData(player)
local now = DateTime.CurrentTime()
data.leftDateTime = now:ToIsoString()
Storage.SetPlayerData(player, data)
end
local function OnPlayerJoined(player)
local data = Storage.GetPlayerData(player)
if data.leftDateTime then
local leftAt = DateTime.FromIsoString(data.leftDateTime)
local now = DateTime.CurrentTime()
local secondsElapsed = now.secondsSinceEpoch - leftAt.secondsSinceEpoch
print("player ".. player.name .." was away for "..secondsElapsed.." seconds.")
else
print("New player ".. player.name ..". First time playing.")
end
end
Game.playerLeftEvent:Connect(OnPlayerLeft)
Game.playerJoinedEvent:Connect(OnPlayerJoined)
See also: Storage.GetPlayerData | Game.playerLeftEvent | Player.name
Example using:
CurrentTime
hour
minute
second
In this example, a client-context script displays to the player their local clock. This appears in the form hh:mm:ss
. The value is written to a UI Text Box
that is assigned as a custom property.
local UI_TEXT = script:GetCustomProperty("UITextBox"):WaitForObject()
function FormatDigitalTime(dateTime)
-- Hour
local str = dateTime.hour .. ":"
-- Minutes
if dateTime.minute < 10 then
str = str .. "0"
end
str = str .. dateTime.minute .. ":"
-- Seconds
if dateTime.second < 10 then
str = str .. "0"
end
str = str .. dateTime.second
return str
end
function Tick()
local now = DateTime.CurrentTime({isLocal = true})
UI_TEXT.text = FormatDigitalTime(now)
Task.Wait(1)
end
See also: UIText.text | CoreObject.GetCustomProperty | CoreObjectReference.WaitForObject | Task.Wait
Example using:
New
CurrentTime
FromSecondsSinceEpoch
secondsSinceEpoch
year
month
day
It can be really useful to know how much time remains until an upcoming event. Perhaps there is a global countdown for all players until a new piece of content is revealed. In this example, we calculate when is the next midnight and how many seconds remain until that threshold arrives. We then take that remaining time and format it in a way that would be appropriate to show to a casual player. Example output: "Time until midnight: 10 h 23 m". This type of operation could be done every second and displayed in a World Text
or UI Text
.
local SECONDS_IN_DAY = 60 * 60 * 24
-- This function takes a number of remaining seconds and formats it into a string
local function FormatCasualTimespan(totalSeconds)
local seconds = totalSeconds
local minutes = math.floor(seconds / 60)
seconds = seconds - minutes*60
if minutes > 0 then
local hours = math.floor(minutes / 60)
minutes = minutes - hours*60
if hours > 0 then
local days = math.floor(hours / 24)
hours = hours - days*24
if days > 0 then
if hours > 0 then
return days.."d " .. hours.."h"
end
return days.."d"
elseif (minutes > 0) then
return hours.."h " .. minutes.."m"
end
return hours.."h"
end
return minutes.."m " .. seconds.."s"
end
return seconds.."s"
end
-- Calculate when is the next midnight
local now = DateTime.CurrentTime()
local tomorrow = DateTime.FromSecondsSinceEpoch(now.secondsSinceEpoch + SECONDS_IN_DAY)
local nextMidnight = DateTime.New({
year = tomorrow.year,
month = tomorrow.month,
day = tomorrow.day,
hour = 0
})
-- Print to the Event Log how much time remains until midnight
local secondsUntilMidnight = nextMidnight.secondsSinceEpoch - now.secondsSinceEpoch
print("Time until midnight: " .. FormatCasualTimespan(secondsUntilMidnight))